Widget Handset APIs

Introduction

The WAC 1.0 API provides a mechanism to access services available on the handset. Access to these services is via a semi-object-oriented paradigm in which functions and properties are accessed via objects that correspond to the handset.

The JIL API provides access to handset services in the following categories:

• PIM: for accessing contacts and calendar information
• Multimedia: for accessing multi-media capabilities such as the camera
• Device: for accessing information about the phone
• Messaging: for sending SMS for example

Access to these categorized services is via a JavaScript object-containment namespacing mechanism. In this mechanism, all services are accessed via a hierarchical identification scheme in which the Widget object is the top-level entry point. Objects are defined to correlate to key features of the device, such as Widget.PIM, Widget.Multimedia.Camera, Widget.Device, etc. These primary objects are invoked statically. For feature security, please refer to the security mapping.

E.g., Widget.Device.launchApplication(…);

Declaring Features

Every Handset API object used by a widget must be declared using the <feature> tag of the widget’s config.xml file, as described in the WAC 1.0 Widget Packaging specification. E.g., in order to call Widget.Device.launchApplication() in the above example, the widget’s config.xml MUST contain the Camera feature definition:

<feature name=”http://jil.org/jil/api/1.1/device” required=”false”/>

A widget SHOULD also declare the use of any implicit parent objects. E.g., in the above example, the Widget object is also referenced and should therefore also be declared:

<feature name=”http://jil.org/jil/api/1.1/widget” required=”false”/>

Note that many runtimes may implicitly declare parent objects, such as Widget, on behalf of widget. Even so, recommended best practice is for the widget to declare every object that is used.

Note that an object will be UNDEFINED if it is not properly defined in the config.xml via the tag.

Indirectly utilized objects, like parameters that are passed into other objects, should also be declared via the element. For example, if the following JavaScript is used in a widget:

Widget.PIM.onAddressBookItemsFound=function(addressBookItem){
            … …
    };

then the addressBookItem feature should also be declared in the config.xml:

<feature name=”http://jil.org/jil/api/1.1/addressbookitem” required=”true”/>

This principle applies to all JIL objects that could be used as parameters, including the following:

• Widget.Device.DeviceStateInfo.onPositionRetrieved
• Widget.PIM.onAddressBookItemsFound
• Widget.Messaging.createMessage

Unsupported Features

It is possible that all WAC Widget runtimes may not provide support for all API features. E.g., a runtime might not provide support of the Camera object. If a widget requires access to a particular feature, then the feature must be declared as mandatory in the config.xml. e.g.,

<feature name=”http://jil.org/jil/api/1.1.2/camera” required=”true”/>

A widget runtime MUST NOT install a widget if the widget declares a mandatory feature that is not supported by the runtime.

A widget runtime MUST install a widget if the widget declares an optional feature that is not supported by the runtime. In this case, the corresponding object will be UNDEFINED. At the runtime’s discretion, it may also throw an UNSUPPORTED exception if a method is not supported by a runtime. When processing optional API functionality, a widget developer SHOULD test for both undefined objects and functions that may throw UNSUPPORTED exceptions.

Feature Tag Declaration Scenarios

1) If a feature is declared as “required=true” in the config.xml, then the widget MUST have access to the feature; if the feature is not supported by the runtime, then the widget MUST NOT be installed.

2) If a feature is declared as “required=false” in the config.xml, then the widget is expected to function without access to the feature. The widget will be installed by run-times that do not support the feature. The widget MUST gracefully handle the lack of support by both ensuring that the associated feature object is not undefined and handling any UNSUPPORTED exceptions that may be thrown.

3) If a feature is not declared in the config.xml, then the feature’s corresponding object will not be available to the widget. The widget may be installed by the run-time, but the feature object will be undefined or throw an UNSUPPORTED exception (the exception is thrown at the runtime’s discretion).

Note that for condition #3 above, WAC 1.0 requests that widgets explicitly identify every feature that is used, including parent objects such as Widget and PIM. As noted above, some run-time may implicitly load parent features, but the widget developer SHOULD NOT rely on this.

Please consult section for details about the handset specification. Electronic HTML API documentation is also available upon request.

The following table illustrates how the WRT behaves if the feature tag is declared or missed while the API is invoked in the widget.

XmlHttpRequest Support

WAC 1.0 also requires support for XmlHttpRequest. In order to use XmlHttpRequest, MUST be declared. If “network=true” is not defined, then XmlHttpRequest object SHOULD be undefined and XmlHttpRequest operations cannot be performed. A config.xml definition is not required in order to access this functionality.

Object and Method Summary Table

The following table provides a summary of the WAC 1.0 objects and their methods. For brevity, not all properties are listed; please consult objects individually to see full descriptions and details.