The Messaging API

4.1 Privacy considerations for implementors of the Messaging API

A user agent must not send messages or subscribe for incoming ones without the express permission of the user. A user agent must acquire permission through a user interface, unless they have prearranged trust relationships with users, as described below. The user interface must include the URI of the document origin, as defined in [HTML5]. Those permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond the time when the browsing context, as defined in [HTML5], is navigated to another URL) must be revocable and a user agent must respect revoked permissions.

The methods that require user's express permission to be accessed are:

• SMSMessage.send(), MMSMessage.send() and EmailMessage.send().
• MessagingManager.onSMS(), MessagingManager.onMMS() and MessagingManager.onEmail().

Obtaining once the user's express permission to access those methods does not imply the user has granted permission for later invocations of the same method or any other method provided by this API. This is especially important in the case of message sending, as every method invocation may lead to extra charges to the user.

A user agent may have prearranged trust relationships that do not require such user interfaces. For example, while a Web browser will present a user interface when a Web site request an SMS subscription, a Widget Runtime may have a prearranged, delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to authorize that operation.

5.1 SMS specific concerns

Note that there are size limitations for SMSs sent on a network (the actual maximum size depends on language encoding the content). When an SMS exceeds the maximum size the device may divide the SMS into several parts. This means that one SMS object may lead to sending several ones to the network (if the platform supports multi-part SMSs).

6.1 DeviceMessaging

The DeviceMessaging object is exposed on the navigator.device object, as defined in [CORE-DEVICE].

Device implements DeviceMessaging;

[NoInterfaceObject]
interface DeviceMessaging {
    readonly attribute MessagingManager messaging;
};

6.2 MessagingManager

This interface provides the general functionality that relates to messaging as well as the entry point for message creation and sending.

interface MessagingManager {
    SMSMessage   createSMS (in SMSProperties smsProperties);
    MMSMessage   createMMS (in MMSProperties mmsProperties);
    EmailMessage createEmail (in EmailProperties emailProperties);
    int          onSMS (in OnIncomingSMS messageEventCB);
    int          onMMS (in OnIncomingMMS messageEventCB);
    int          onEmail (in OnIncomingEmail messageEventCB);
    void         unsubscribe (in int subscriptionHandle);
};

6.3 SMSMessage

This interface describes generic functionality of SMS message.

[NoInterfaceObject]
interface SMSMessage : SMSProperties {
    readonly attribute DOMString id;
    readonly attribute Date      timestamp;
    readonly attribute DOMString from;
    readonly attribute DOMString folder;
    PendingOp send (in MessagingSuccessCB successCB, in optional MessagingErrorCB? errorCB);
};

6.4 MMSMessage

This interface describes generic functionality of MMS message.

[NoInterfaceObject]
interface MMSMessage : MMSProperties {
    readonly attribute DOMString id;
    readonly attribute Date      timestamp;
    readonly attribute DOMString from;
    readonly attribute DOMString folder;
    PendingOp send (in MessagingSuccessCB successCB, in optional MessagingErrorCB? errorCB);
};

6.5 EmailMessage

This interface describes generic functionality of E-mail message.

[NoInterfaceObject]
interface EmailMessage : EmailProperties {
    readonly attribute DOMString id;
    readonly attribute Date      timestamp;
    readonly attribute DOMString from;
    readonly attribute DOMString folder;
    PendingOp send (in MessagingSuccessCB successCB, in optional MessagingErrorCB? errorCB);
};

6.6 SMSProperties

This interface captures the data fields in an SMS message. See Supported Messaging Types for the list of attributes that must be supported for SMS type.

[NoInterfaceObject]
interface SMSProperties {
    attribute DOMString[] to;
    attribute DOMString   body;
};

6.7 MMSProperties

This interface captures the data fields in an MMS message. See Supported Messaging Types for the list of attributes that must be supported for MMS type.

[NoInterfaceObject]
interface MMSProperties {
    attribute DOMString[] to;
    attribute DOMString   subject;
    attribute DOMString   body;
    attribute Blob[]      attachments;
};

6.8 EmailProperties

This interface captures the data fields in an E-mail message. See Supported Messaging Types for the list of attributes that must be supported for E-mail type.

[NoInterfaceObject]
interface EmailProperties {
    attribute DOMString[] to;
    attribute DOMString[] cc;
    attribute DOMString[] bcc;
    attribute DOMString   subject;
    attribute DOMString   body;
    attribute DOMString   accountId;
    attribute DOMString   priority;
    attribute Blob[]      attachments;
};

6.9 OnIncomingSMS

This interface defines the method called on new SMS events.

[Callback=FunctionOnly, NoInterfaceObject]
interface OnIncomingSMS {
    c void onEvent (in SMSMessage message);
};

6.10 OnIncomingMMS

This interface defines the method called on new MMS events.

[Callback=FunctionOnly, NoInterfaceObject]
interface OnIncomingMMS {
    void onEvent (in MMSMessage message);
};

6.11 OnIncomingEmail

This interface defines the method called on new MMS events.

[Callback=FunctionOnly, NoInterfaceObject]
interface OnIncomingEmail {
    void onEvent (in EmailMessage message);
};

6.12 MessagingSuccessCB

[Callback=FunctionOnly, NoInterfaceObject]
interface MessagingSuccessCB {
    void onSuccess ();
};

6.13 MessagingErrorCB

[Callback=FunctionOnly, NoInterfaceObject]
interface MessagingErrorCB {
    void onError (in MessagingError error);
};

6.14 MessagingError interface

Adds Messaging API specific error codes.

The MessagingError interface encapsulates all errors in the manipulation of Messaging objects in the messaging API.

[NoInterfaceObject]
interface MessagingError : GenericError {
    const unsigned short UNKNOWN_ERROR = 0;
    const unsigned short INVALID_ARGUMENT_ERROR = 1;
    const unsigned short NOT_FOUND_ERROR = 2;
    const unsigned short TIMEOUT_ERROR = 3;
    const unsigned short PENDING_OPERATION_ERROR = 4;
    const unsigned short IO_ERROR = 5;
    const unsigned short NOT_SUPPORTED_ERROR = 6;
    const unsigned short PERMISSION_DENIED_ERROR = 20;
    const unsigned short MESSAGE_SIZE_EXCEEDED = 30;
    readonly attribute unsigned short code;
};