Registration

Registration and Capability API is a part of the Smart Extension APIs.

This API is used by accessory extensions and accessory host applications. Typically host applications insert and maintain information about the accessories capabilities. Extensions use the capability information in order to interact with the accessories in a correct way. Before an extension can interact with an accessory it must provide (register) some information needed by the host applications. The API defines and implements an Android ContentProvider that applications access via the Android ContentResolver API. The ContentProvider implementation is backed by a database implementation.

Topics covered here:

1. Using the capabilities API
2. Extension registration
3. User extension configuration
4. Security.

Using the capabilities API

This API is an Android content provider that provides information about the capabilities of the accessories. The information is provided by the host applications and are used by the extensions to obtain necessary information in order to interact with the accessories through the Control, Widget and Sensor APIs. The content provider contains the tables shown in the picture below.

For each accessory there is a corresponding record in the Registration.HostApp table. A Particular host application is identified by its package name. For each host application there is one or more device records in the Registration.Device table. A particular device can support zero or more displays, sensors, leds and inputs, defined in the Registration.Display, Registration.Sensor, Registration.Led, Registration.Input and Registration.Widget tables respectively. There is a Registration.SensorType table describing each type of sensor, a Registration.KeyPad table describing the capabilities of the keypads of each input type. The capabilities tables are accessible through the content provider.

Capability URI's and description

1. Host application URI URI and columns Registration.HostAppColumns
2. Host application URI URI and columns Registration.DeviceColumns
3. Host application URI URI and columns Registration.DisplayColumns
4. Host application URI URI and columns Registration.SensorColumns
5. Host application URI URI and columns Registration.InputColumns
6. Host application URI URI and columns Registration.LedColumns
7. Host application URI URI and columns Registration.WidgetColumns
8. Host application URI URI and columns Registration.SensorTypeColumns
9. Host application URI URI and columns Registration.KeyPadColumns

It is also possible to use a view that returns all capabilities in a single query. The URI is URI.

Extension registration

Before an extension can use an accessory, the extension must use the Registration API content provider to insert a record in the extension table. The URI is defined in the extension interface URI and the table scheme is defined in the ExtensionColumns interface Registration.ExtensionColumns.

After inserting a record in the extensions table, the extension is ready to use the Notification API. No further registration is needed in order to use the Notification API and start writing sources and events. More advanced extensions that also want to use any of the Widget API, Control API or Sensor API must also register information in the registration table. This should be done for each host application that the extension wants to interact with. In order to find out what host applications are available and what capabilities they support, the extension should use the capability API. The URI of the registration table is defined in the ApiRegistration interface URI and the table schema is defined in the ApiRegistrationColumns interface Registration.ApiRegistrationColumns. The extension should provide the host application package name and indicate what APIs it will use. If the extension wants to use Widget API version 3 or later it registers the available widgets in the Registration.WidgetRegistration table.

Before an application can register itself as an extension, there must be at least one host application installed on the phone. This is to prevent that extensions start writing data into the databases when there are no host applications (user has no accessories).

The application should register upon reception of the EXTENSION_REGISTER_REQUEST_INTENT intent. This intent is broadcasted when a new application is installed and when a new host application has added its capabilities to the tables.

User extension configuration

Extensions may require configuration by the user before they can fully function. For example, the end user might need to login to a service on the Internet before events can be retrieved. The extension is responsible for providing this configuration UI to be displayed.

Host applications have their own configuration UIs from within the configuration UIs of registered extensions can be reached. When registering to the Smart Connect, there is a column in the extension table called configurationActivity. If your extension needs to be configured after it is registered, insert your Android Activity class name in this column.

...
        String configName = new ComponentName(getPackageName(),
                RssPluginConfig.class.getName()).flattenToShortString();
        values.put(ExtensionColumns.CONFIGURATION_ACTIVITY, configName);
        ...
        cr.insert(Extension.URI, values);

When the user wishes to launch your configuration UI, the host application will launch the registered Activity.

Security

Each extension that wants to interact with the Registration & Capabilities API should specify a specific plug-in permission in their manifest file EXTENSION_PERMISSION. The API implements a security mechanism that ensure that each extension only can access their own registration and notification data. Sharing information between extensions can be obtained for extensions that use the sharedUserId mechanism, however this approach is not recommended. Extensions do not have permission to write data in the capability tables, only host applications have write access.

Android Intents are sent when interaction with the extension is needed. See the documentation of the Control API, Widget API, Sensor API and Notification API for more information about intents. To enable the extension to verify the sender of the Intents is a trusted application with access to the APIs and not a malicious application that sends the same Intents on pretext of being a trusted application, the EXTENSION_KEY field allows plug-in developers to store something that can be used as identification when the Intents are received. Except where startActivity(android.content.Intent) is used, this key is attached to every Intent the different accessory host applications send to the extension as these applications are granted access to the accessory information. The receiving extension should check the value of the key to see if it matches what it has. If not, the plug-in should ignore the Intent. This key is generated by the extension itself. It should be as unique as possible to minimize the risk of several extensions having the key. An extension is free to change the key stored in the database that it owns. As an added precaution, Intents are sent as directed Intents where possible.