module push { [Callback=FunctionOnly, NoInterfaceObject] interface SubscriptionSuccessCallback { void onSuccess(in unsigned long subscriptionID); }; [Callback=FunctionOnly, NoInterfaceObject] interface PushEventCallback { void onPushEvent(in PushMessage message); }; interface PushManager { PendingOperation subscribe(in SubscriptionSuccessCallback successCallback, in ErrorCallback errorCallback, in PushEventCallback listener, [Optional] in DOMString registrationUri, [Optional] in DOMString accept, [Optional] in DOMString appid, [Optional] in boolean exclusive) raises(SecurityError, DeviceAPIError); void unsubscribe(in unsigned long subscriptionID) raises(SecurityError, DeviceAPIError); }; interface PushMessage { DOMString getAllMessageHeaders(); DOMString getMessageHeader(in DOMString header); readonly attribute DOMString messageText; readonly attribute Document messageXML; }; }; BONDI Push API

This API provides functionality of OMA Push delivery to Web Applications running in the widget context, which includes; subscription/unsubscription of web applications to Push messages from the OMA Push enabler, and delivery of received Push messages to the subscribeed application(s).

This module offers the functionality to subscribe to OMA Push messages. A subscription to Push messages will remain active until explicit unsubscription. While subscribed, Push messages that match application preferences will be delivered to the application if possible, through a call to the application-defined Push message listener.

The basic structure of OMA Push messages is very similar to HTTP messages, i.e. they include headers and a content body.

Headers:

Push Application ID: an OMNA-registered value for BONDI "x-oma-bondi:widget.ua", (see OMA Push Application ID Registry), which is used by OMA Push Clients to route incoming Push to the widget user agent.
Content Type: MIME type of the Push body.
Other headers (application specific or standardized).

Content:

Content: may be a text or binary file. Text files may be in plain text XML, or any other text content type. Text files may be delivered to the terminal in compressed form (e.g. content encoding as WBXML or GZIP), and will be uncompressed before delivery to the subscribed application. OMA Push defines standard XML-based content types of general use for notification/wakeup-type purposes, e.g. the "Service Indication" and "Service Loading" content types.

OMA Push messages are delivered via various bearers and protocols, depending upon the support of the specific device. The specific bearer used is transparent to the application, except as arranged through a specific Push Registration URI (a parameter of the subscription process).

The latest OMA Push Candidate Enabler release is OMA Push 2.3. OMA Push "Over-the-Air" protocol reference: Push-OTA

Subscribe for access to Push messages

All the Push features

Subscribe for access to Push messages Push Application ID to be subscribed to. The parameter can be used to restrict access to events meant for certain application types, e.g. OMA-standardized Push applications (browsing, Multimedia Messaging (MMS), Instant Messaging (IM), Device Management (DM), etc.) by blocking subscription to appid values prefixed by "x-wap" or "x-oma". Content (MIME) types to be subscribed to. The parameter can be used to restrict access to content intended for a specific pre-define handler, e.g. OMA-standardized Push applications (MMS notifications, IM notifications, DM notifications, etc) by blocking subscription to MIME types associated with those applications. Request exclusive subscription to the selected parameters. The parameter can be used to ensure that only a single application can act as a handler for the event types. Note that the user agent will deny exclusive subscription if that conflicts with device-native clients (e.g. browsing, MMS, IM, DM, etc).

Bryan Sullivan <bryan.sullivan@att.com> 0.3 [Callback=FunctionOnly, NoInterfaceObject] interface SubscriptionSuccessCallback { void onSuccess(in unsigned long subscriptionID); }; The success callback for subscription to incoming Push messages.

This callback completes the asynchronous operation initiated by the subscribe() method, confirms successful subscription to the requested Push message events, and provides the subscription ID that can be used to cancel the subscription at a later time, via the unsubscribe() method.

void onSuccess(in unsigned long subscriptionID); Method invoked when subscribing is successful

Identifier of the subscription

[Callback=FunctionOnly, NoInterfaceObject] interface PushEventCallback { void onPushEvent(in PushMessage message); }; Push message callback

Callback for incoming Push messages. When the callback is invoked its input parameters are the Push message header array and content.

void onPushEvent(in PushMessage message); Method invoked to notify about incoming Push message

The Push message

interface PushManager { PendingOperation subscribe(in SubscriptionSuccessCallback successCallback, in ErrorCallback errorCallback, in PushEventCallback listener, [Optional] in DOMString registrationUri, [Optional] in DOMString accept, [Optional] in DOMString appid, [Optional] in boolean exclusive) raises(SecurityError, DeviceAPIError); void unsubscribe(in unsigned long subscriptionID) raises(SecurityError, DeviceAPIError); }; Manager class exposed as the Push module API.

This manager class exposes the Push base API, such as subscribing to OMA Push message events, delivering received Push message events, and unsubscribing to Push message events.

  var subscriptionID = 0;

        // Define the success callback to get the subscription ID.
        function successCallback(id) {
                subscriptionID = id;
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "Push subscription failed. The error code is: " +  response.code);
        }

        // Define listener for received Push messages
        function gotPush(push) {
                var ctype = push.getMessageHeader("Content-Type");
                if (ctype == "text/vnd.wap.si") {
                        serviceIndication(push.messageXML);
                }
                if (ctype == "text/vnd.wap.sl") {
                        serviceLoad(push.messageXML);
                }
                (... etc for other content types as supported by widget)
        }

        // Subscribe to Push messages
        var accept = "text/vnd.wap.si";
        var appid = "x-oma-application:dcd.ua";
        var pendop = bondi.push.subscribe(successCallback, errorCallback, 
                        gotPush, registrationUri, accept, appid, false);

        // Cancel subscription to Push messages
        bondi.push.unsubscribe(subscriptionID);

PendingOperation subscribe(in SubscriptionSuccessCallback successCallback, in ErrorCallback errorCallback, in PushEventCallback listener, [Optional] in DOMString registrationUri, [Optional] in DOMString accept, [Optional] in DOMString appid, [Optional] in boolean exclusive) raises(SecurityError, DeviceAPIError); Method for subscription to Push events.

This API allows applications to be notified whenever an incoming Push meets a set of conditions. The returned identifier may be used to unsubscribe from these events using the unsubscribe method.

The accept is optional, and can be used by the widget to request notification for specific content (MIME) types only.

The callback argument is mandatory. Whenever a Push message is received the system will call the supplied callback passing the Push message object.

If the widget is not authorized to subscribe for Push messages, a SecurityError with code PERMISSION_DENIED_ERROR will be raised.

If the implementation has not implemented the API, a DeviceAPIError with code NOT_SUPPORTED_ERROR will be raised.

Subscribe to Push messages

        var pendop = bondi.push.subscribe(successCallback, errorCallback, 
               gotPush, registrationUri, accept, appid, false);

PendingOperation enabling the requester to cancel this request.

function called when the invocation ends successfully, use response object to retrieve subscription identifier

function called when an error occurs, the callback provides an input parameter that is an Error object

Callback to be invoked whenever an applicable Push message is received.

The address to which the Push Service Registration procedure [OMA PushOTA] should be executed, e.g. to receive applicable connection profiles for the Push service.

The set of content (MIME) types for which the widget should be notified. Case-insensitive.

The OMNA-registered or unregistered Push Application ID URN associated with the web application. Case-insensitive.

Allows a widget for requesting exclusive subscription for the notifications. If set to true no other application could subscribe to these notifications.

PERMISSION_DENIED_ERROR when access is denied by the security policy, or the request is not possible otherwise (e.g. an exclusive subscription already exists or the appid/accept type is associated with a native client which has exclusive access to the type of Push messages).

NOT_SUPPORTED_ERROR if the the implementation has not implemented the API.

void unsubscribe(in unsigned long subscriptionID) raises(SecurityError, DeviceAPIError); Method to unsubscribe to Push message notifications.

 // "subscriptionID" is the ID returned upon subscription success.
  bondi.push.unsubscribe(subscriptionID);

Subscription identifier

INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

interface PushMessage { DOMString getAllMessageHeaders(); DOMString getMessageHeader(in DOMString header); readonly attribute DOMString messageText; readonly attribute Document messageXML; }; Push Message API

The Push Message interface enables access to the headers and content of a Push message. The interface provides access to the headers as an array or to a specific header (by name), and to the message content as a string or XML document.

DOMString getAllMessageHeaders(); Get all headers of the Push message.

The getAllmessageHeaders() method returns all the Push message headers, as a single string, with each header line separated by a U+000D CR U+000A LF pair, and with each header name and header value separated by a U+003A COLON U+0020 SPACE pair. If there are no headers, the method returns null.

 // "push" is set to a Push message object received earlier.
  var headers = push.getAllMessageHeaders();
  alert(headers); // show the Push message headers

DOMString getMessageHeader(in DOMString header); Get a specific header of the Push message.

The getMessageHeader(header) method returns one of:

If header is an ASCII case-insensitive match for multiple message headers, the values of these headers as a single concatenated string separated from each other by a U+002C COMMA U+0020 SPACE character pair.
If header is an ASCII case-insensitive match for a single message header, the value of that header.
null.

 // "push" is set to a Push message object received earlier.
  var ctype = push.getMessageHeader("Content-Type");
  alert(ctype); // show the Push message content type

Name of the header to retrieve, if present. Case-insensitive.

readonly attribute DOMString messageText; Get Push message content as text.

The messageText attribute returns the text response entity body (if any), as defined for XMLHttpRequest in http://www.w3.org/TR/XMLHttpRequest/#text-response-entity-body.

This is a readonly property.

 // "push" is set to a Push message object received earlier.
  alert(push.messageText); // show the Push message

readonly attribute Document messageXML; Get Push message content as XML.

The messageXML attribute return the XML response entity body (if any), as defined for XMLHttpRequest in http://www.w3.org/TR/XMLHttpRequest/#xml-response-entity-body.

This is a readonly property.

 // "push" is set to a Push message object received earlier.
 var dcdXml = push.messageXML; // get the message as XML
 // get the channel metadata attribute
 var cm = getElementAttributes(dcdXml,"Channel-Metadata",0);