Proposal So you want to add the Widgets API. Let's call it widgets. Defining the Interface How will extensions declare their intent to use widgets?You need to decide this now. In other words, what will a user of widgets need to write in their manifest?Typically this will be either via a permission string or manifest entry. There is no need for both. By convention it should be called "widgets".
There are exceptions:
Tell the extensions platform about widgetsFirstly decide, can your API be applied to any platform built on the web, or does it only make sense for Chrome? Examples of the former: storage, messaging. Examples of the latter: browserAction, bookmarks. A good clue is whether you need to #include anything from chrome.
From here, all files here are relative to either extensions/common/api or chrome/common/extensions/api: First, add an entry in _api_features.json. This tells the extensions platform about when your API should be available (anywhere? only in extension processes?), and what they need to do to use it (do they need a permission? a manifest entry?).
Second, add an entry to either _manifest_feature.json or _permission_features.json. This tells the platform how to interpret "widgets" when it encounters it as either a manifest entry or a permission. What is it available to (extensions? apps? both?), and importantly what channel is it available in (dev? beta? stable?). New extension APIs MUST start in dev (although if they're unimplemented then trunk is advisable). New extension APIs MUST start in dev (just repeating it). Write a schema for widgets Extension APIs can be defined in either IDL (widgets.idl) or JSON Schema (widgets.json). IDL is much more concise, but doesn't include some of the advanced features supported by JSON Schema. You probably want IDL, though be warned IDL syntax errors occasionally cause the compiler to never terminate. Fourth, list the schema in //extensions/common/api/schemas.gni, which tells the build system to generate a bunch of boilerplate for you in <build_dir>/gen/extensions/common/api or <build_dir>/gen/chrome/common/extensions/api: models for your API, and the glue to hook into your implementation. Finally, add some documentation: Adding documentationAdding documentation is very simple:
C++ implementation The actual C++ implementation will typically live in extensions/browser/api/myapi or chrome/browser/extensions/api/myapi (as mentioned above, the magic glue is generated for you). Functions Extension APIs are implemented as subclasses of ExtensionFunction from extensions/browser/extension_function.h.
Model generation Your C++ implementation must live in extensions/browser/api/myapi/myapi_api.h/cc or chrome/browser/extensions/api/myapi/myapi_api.h/cc (depending on where it was declared).This is so that the code generator can find the header file defining your extension function implementations. Remember to add your source files to //chrome/common/extensions/api/api_sources.gni. In your header file, include extensions/common/api/myapi.h or chrome/common/extensions/api/myapi.h to use the generated model. This comes from a code-generated file that lives under e.g. out/Debug/gen/chrome/common/extensions/api. Let's say we have the following IDL (or equivalent JSON schema): // High-level description of your API. This will appear in various places in the docs. namespace myapi { dictionary BazOptions { // Describes what the id argument means. long id; // Describes what the s argument means. DOMString s; }; dictionary BazResult { long x; long y; }; callback BazCallback = void (BazResult result); interface Functions { // An interesting comment describing what the baz operation is. // Note that this function can take multiple input arguments, including things like // long and DOMString, but they have been elided for simplicity. static void doBaz(BazOptions options, BazCallback callback); }; }; A simple C++ implementation might look like this: namespace extensions { // You must follow a naming convention which is ApiNameFunctionNameFunction, // in this case MyapiDoBazFunction. This is so that the generated code // can find your implementation. class MyapiDoBazFunction : public AsyncExtensionFunction { public: virtual ~MyapiDoBazFunction () {} private: // The MYAPI_DOBAZ entry is an enum you add right before ENUM_BOUNDARY // in chrome/browser/extensions/extension_function_histogram_value.h DECLARE_EXTENSION_FUNCTION("myapi.doBaz", MYAPI_DOBAZ); virtual ResponseAction Run() OVERRIDE { // Args are passed in via the args_ member as a base::ListValue. // Use the convenience member of the glue class to easily parse it. std::unique_ptr<api::myapi::DoBaz::Params> params( api::myapi::DoBaz::Params::Create(*args_)); EXTENSION_FUNCTION_VALIDATE(params.get()); api::myapi::BazResult result; result.x = params->options.id; base::StringToInt(params->options.s, &result.y); // Responds to the caller right, but see comments on // ExtensionFunction::Run() for other ways to respond to messages. return RespondNow(ArgumentList(result.ToValue())); } }; } // namespace extensions ExtensionFunction is refcounted and instantiated once per call to that extension function, so use base::Bind(this) to ensure it's kept alive (or use AddRef...Release if that's not possible for some reason). Events Use ExtensionEventRouter (on the UI thread) to dispatch events to extensions. Prefer the versions that allow you to pass in base::Value rather than a JSON serialized format. Event names are auto-generated in the API file (e.g. chrome/common/extensions/api/myapi.h). In the un-common case where an event is not defined in IDL or json, the corresponding event name should be defined in chrome/browser/extensions/event_names.h. As with extension functions, it generates some C++ glue classes. Let's say we have the following IDL (or equivalent JSON Schema): namespace myapi { dictionary Foo { // This comment should describe what the id parameter is for. long id; // This comment should describe what the bar parameter is for. DOMString bar; }; interface Events { // Fired when something interesting has happened. // |foo|: The details of the interesting event. static void onInterestingEvent(Foo foo); };}; To use the generated glue in C++: DCHECK(BrowserThread::CurrentlyOn(BrowserThread::UI)); api::myapi::Foo foo; foo.id = 5; foo.bar = "hello world"; ExtensionSystem::Get(profile)->event_router()->DispatchEventToExtension( extension_id, api::myapi::OnInterestingEvent::kEventName, *api::myapi::OnInterestingEvent::Create(foo), profile, GURL()); Permissions By default, extension APIs should require a permission named the same as the API namespace. New permissions are added in ExtensionAPIPermissions::GetAllPermissions() in extensions/common/permissions/extensions_api_permissions.cc or in ChromeAPIPermissions::GetAllPermissions() in chrome/common/extensions/permissions/chrome_api_permissions.cc. You may also need to modify api_permission.h and chrome_permission_message_rules.cc in those directories; see how it's done for other permissions. Advanced Extension Functionality Custom Bindings Custom JS bindings go in chrome/renderer/resources/extensions/*.js. These are necessary for doing anything special: synchronous API functions, functions bound to types, anything renderer-side. (If it's a common enough operation, please send us patches to do it automatically as part of the bindings generation :). New Manifest Sections If your API requires a new manifest section:
The code which handles the externally_connectable manifest key is a good place to start. Testing Your Implementation Make sure it has tests. Like all of Chrome, we prefer unit tests to integration tests.
Iterating
Going to StableFollow the Going Live Phase instructions. |
|
|