Sony Addon SDK public class

Registration

This project is no longer being supported and will not get any further updates.
extends java.lang.Object
  1. java.lang.Object
  2. com.sonyericsson.extras.liveware.aef.registration.Registration

Class Overview

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.

Operating context

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.

Operating context

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.

Summary

Nested Classes
interface Registration.Intents Intents sent to extensions by the host applications either using the broadcast queue or Tunnel.
interface Registration.AccessoryConnectionStatus Interface used to define constants for accessory connection status
interface Registration.Extension Definitions used for interacting with the Extension-table
interface Registration.ExtensionColumns Column-definitions for the Extension table
interface Registration.ApiRegistration Definitions used for interacting with the ApiRegistration-table
interface Registration.ApiRegistrationColumns Column-definitions for the ApiRegistration-table
interface Registration.Capabilities Use separate queries for the individual tables.
interface Registration.HostApp Definitions used for interacting with the Host application-table
interface Registration.HostAppColumns Column-definitions for the Host application table
interface Registration.Device Definitions used for interacting with the Device-table
interface Registration.DeviceColumns Column-definitions for the Device table
interface Registration.Display Definitions used for interacting with the Display-table
interface Registration.DisplayColumns Column-definitions for the Display table
interface Registration.Sensor Definitions used for interacting with the Sensor-table
interface Registration.SensorColumns Column-definitions for the Sensor table
interface Registration.Tap
interface Registration.TapColumns
interface Registration.Led Definitions used for interacting with the Led-table
interface Registration.LedColumns Column-definitions for the Led-table
interface Registration.Input Definitions used for interacting with the Input-table
interface Registration.InputColumns Column-definitions for the Sensor table
interface Registration.SensorType Definitions used for interacting with the Sensor-type-table
interface Registration.SensorTypeColumns Column-definitions for the SensorType table
interface Registration.KeyPad Definitions used for interacting with the Keypad-table
interface Registration.KeyPadColumns Column-definitions for the Keypad table
interface Registration.Version Definitions used for interacting with the Version table
interface Registration.VersionColumns Column-definitions for the Version table
interface Registration.Widget Definitions used for interacting with the Widget table.
interface Registration.WidgetColumns Column-definitions for the Widget table
interface Registration.WidgetRegistration Definitions used for interacting with the WidgetRegistration table.
interface Registration.WidgetRegistrationColumns Column-definitions for the WidgetRegistration table
interface Registration.LaunchMode Specifies which API that shall be started when launching the extension.
interface Registration.LayoutSupport Bit field specifiers for supported layout elements.
interface Registration.KeyPadType Key pad type specifiers
interface Registration.SensorTypeValue Definitions of sensor types
Constants
java.lang.String EXTENSION_PERMISSION tag to use this permission.
java.lang.String HOSTAPP_PERMISSION Permission used by host applications; Extensions shall use this permission to enforce security when sending intents to a host application using sendBroadcast(Intent, String)
java.lang.String AUTHORITY Authority for the Registration provider
Fields
protected static final Uri BASE_URI Base URI for the Registration provider
Protected Constructors
Registration()

Constants

Added in API level 1.0 public static final java.lang.String EXTENSION_PERMISSION

tag to use this permission. The purpose is to indicate to the end user the application containing the extension interacts with the Registration API.

Constant Value: "com.sonyericsson.extras.liveware.aef.EXTENSION_PERMISSION"

Added in API level 1.0 public static final java.lang.String HOSTAPP_PERMISSION

Permission used by host applications; Extensions shall use this permission to enforce security when sending intents to a host application using sendBroadcast(Intent, String)

Constant Value: "com.sonyericsson.extras.liveware.aef.HOSTAPP_PERMISSION"

Added in API level 1.0 public static final java.lang.String AUTHORITY

Authority for the Registration provider

Constant Value: "com.sonyericsson.extras.liveware.aef.registration"

Fields

Added in API level 1.0 protected static final Uri BASE_URI

Base URI for the Registration provider

Protected Constructors

protected Registration()