Please note that Web Extension support is deprecated. Please use Platform Services (cobalt/doc/platform_services.md) instead. This is an effort to move away from injecting compile-time modules into the Cobalt layer in favor of using runtime extensions provided by the Starboard layer.
In order to extend the interface, one should add the following lines to the
variables section of
<platform-directory>/cobalt/configuration.gypi (see Starboard's Application Customization for more information):
cobalt_webapi_extension_source_idl_files This should be a list of IDL files that define the collection of new interfaces introduced by your extensions. One of these new interfaces can be selected to be injected into the
window element (see 3.
cobalt_webapi_extension_generated_header_idl_files This is a list of all files that may result in automatic header file generation that might be referenced from other C++ code. An example of this is the definition of
enums that may then be referenced as types in a file from 1.
cobalt_webapi_extension_gyp_target This is the gyp target that will provide the IDL interface implementations, as well as any necessary auxiliary code. It will be added as a dependency of browser/cobalt.gyp:cobalt. It is expected that this target will implement the interface defined in browser/webapi_extension.h, which let you name the injected window property, and provide a function to instantiate it (i.e. to let you select which IDL object is the “entry point”).
The first two lists get included by cobalt/browser/browser_bindings_gen.gyp, where you can look to see many examples of existing Cobalt IDL files that define the Web API available through Cobalt. For each of these, you can also examine their corresponding
.h files and in most cases their
.cc files as well.
An example configuration for these variables is available at starboard/shared/test_webapi_extension/test_webapi_extension.gypi, which contains the following variable definitions:
'cobalt_webapi_extension_source_idl_files': [ 'my_new_interface.idl' ], 'cobalt_webapi_extension_generated_header_idl_files': [ 'my_new_enum.idl' ], 'cobalt_webapi_extension_gyp_target': '<(DEPTH)/starboard/shared/test_webapi_extension/webapi_extension.gyp:cobalt_test_webapi_extension',
As discussed above in 3.
cobalt_webapi_extension_gyp_target, you must provide an implementation of the two functions declared in browser/webapi_extension.h.
You should implement
GetWebAPIExtensionObjectPropertyName() to return the name of the injected
window property. For example, in the example from the beginning of this document,
window.myInterface.RunMyFunction(), we would have the function return
std::string("myInterface"). If you return
nullopt from this function, it is assumed that you do not wish to extend the web interface.
Note that you should NOT name your
This function should instantiate and return the object to be accessed from
window. The object must be defined by an IDL file.
Here is an example of an example interface being exercised through the debug console: