Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines an API that provides access to messaging functionality in the device, including SMS, MMS and email.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document represents the early consensus of the group on the scope and features of the proposed Messaging API; in particular, the group intends to work on messages management (move, delete, copy, etc.) in a separate specification.
Issues and editors note in the document highlight some of the points on which the group is still working and would particularly like to get feedback.
This document was published by the Device APIs and Policy Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-device-apis@w3.org (subscribe, archives). All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: user agents that implement the interfaces that it contains.
Since not all devices will have all messaging functionality (e.g. a phone may have only SMS and MMS while a PC may have only email) there is a need to indicate that conformant implementations need only expose available functionality.
Implementations that use ECMAScript to implement the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL], as this specification uses that specification's terminology.
The Messaging API defines a high-level interface to Messaging functionality, including SMS, MMS and Email. It includes APIs to create, send and receive messages.
The following code extracts illustrate how to create, send and receive messages.
Sending an SMS, if device supports it.
function successCB() { alert("The Message has been sent successfully"); } function errorCB(error) { alert("The Message could not be sent " + error.code); } if (navigator.device.messaging.createSMS) navigator.device.messaging.createSMS({to: [{'+460000000001'}], body: "Welcome to Atlantis"}).send(successCB, errorCB);
Register listener for new SMS events.
// function to receive new SMS notifications function incomingSMS(message) { alert("New incoming SMS from " + message.from); if (mySMSListener != null) navigator.device.messaging.unsubscribe(mySMSListener); } // Register listener for new SMS events var mySMSListener = null; mySMSListener = navigator.device.messaging.onSMS(incomingSMS);
This specification is limited to providing a scripting API for creating, sending and receiving messages. The supported messaging types include SMS, MMS and Email.
The specification does not replace RFCs for Mail or SMS URLs. The specification includes complementary functionality to these.
The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made to this API to reflect requirements or support for privacy-related functionality.
The API defined in this specification can be used to create and subscribe for incoming messages through different technologies.Sending messages usually have a cost associated to them, especially SMSs and MMSs. Furthermore this cost may depend on the message attributes (e.g. destination address) or external conditions (e.g. roaming status). Apart from billing implications, there are also privacy considerations due to the capability to access message contents. A conforming implementation of this specification must provide a mechanism that protects the user's privacy and this mechanism should ensure that no message is sent or no subscription is establisehd without the user's express permission.
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:
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.
The specification supports three kinds of messages: SMS, MMS and E-mail. For each of them specific interfaces and data types have been defined and they will be detailed in the following section. The table below summarizes the attributes that are supported for each given message type.
Attribute | SMS | MMS | |
---|---|---|---|
from |
X | X | X |
timestamp |
X | X | X |
folder |
X | X | X |
account Id |
- | - | X |
to |
X | X | X |
cc |
- | - | X |
bcc |
- | - | X |
subject |
- | X | X |
body |
X | X | X |
attachments |
- | X | X |
priority |
- | - | X |
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).
DeviceMessaging
The DeviceMessaging object is exposed on the navigator.device
object, as defined in [CORE-DEVICE].
Device implements DeviceMessaging
;
All instances of the Device
type are defined to also implement the DeviceMessaging
interface.
[NoInterfaceObject]
interface DeviceMessaging {
readonly attribute MessagingManager
messaging;
};
messaging
of type MessagingManager
, readonlyMessagingManager
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);
};
createEmail
EmailMessage
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
emailProperties |
| ✘ | ✘ | The E-mail properties may include the "to", "cc", "bcc", "subject", "body", "accountId", "priority" and "attachments" attributes. |
EmailMessage
createMMS
MMSMessage
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mmsProperties |
| ✘ | ✘ | The MMS properties may include the "to", "cc", "bcc", "subject", "body" and "attachments" attributes. |
MMSMessage
createSMS
SMSMessage
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
smsProperties |
| ✘ | ✘ | The SMS properties may include the "to" and "body" attributes. |
SMSMessage
onEmail
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
messageEventCB |
| ✘ | ✘ | The callback method for new Email events |
int
onMMS
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
messageEventCB |
| ✘ | ✘ | The callback method for new MMS events |
int
onSMS
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
messageEventCB |
| ✘ | ✘ | The callback method for new SMS events |
int
unsubscribe
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
subscriptionHandle | int | ✘ | ✘ | Handle to the subscription to be cancelled. |
void
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);
};
folder
of type DOMString, readonlyfrom
of type DOMString, readonlyid
of type DOMString, readonlytimestamp
of type Date, readonlysend
pendingOp
returns object allows canceling the sending of the message.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCB |
| ✘ | ✘ | Function to call when the asynchronous operation completes. |
errorCB |
| ✔ | ✔ | Function to call when the asynchronous operation fails. |
PendingOp
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);
};
folder
of type DOMString, readonlyfrom
of type DOMString, readonlyid
of type DOMString, readonlytimestamp
of type Date, readonlysend
pendingOp
returns object allows canceling the sending of the message.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCB |
| ✘ | ✘ | Function to call when the asynchronous operation completes. |
errorCB |
| ✔ | ✔ | Function to call when the asynchronous operation fails. |
PendingOp
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);
};
folder
of type DOMString, readonlyfrom
of type DOMString, readonlyid
of type DOMString, readonlytimestamp
of type Date, readonlysend
pendingOp
returns object allows canceling the sending of the message.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
successCB |
| ✘ | ✘ | Function to call when the asynchronous operation completes. |
errorCB |
| ✔ | ✔ | Function to call when the asynchronous operation fails. |
PendingOp
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;
};
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;
};
attachments
of type array of Blobbody
of type DOMStringsubject
of type DOMStringto
of type array of DOMStringEmailProperties
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;
};
accountId
of type DOMStringattachments
of type array of Blobbcc
of type array of DOMStringbody
of type DOMStringcc
of type array of DOMStringpriority
of type DOMStringsubject
of type DOMStringto
of type array of DOMStringOnIncomingSMS
This interface defines the method called on new SMS events.
[Callback=FunctionOnly, NoInterfaceObject]
interface OnIncomingSMS {
c void onEvent (in SMSMessage
message);
};
onEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
message |
| ✘ | ✘ |
c void
OnIncomingMMS
This interface defines the method called on new MMS events.
[Callback=FunctionOnly, NoInterfaceObject]
interface OnIncomingMMS {
void onEvent (in MMSMessage
message);
};
onEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
message |
| ✘ | ✘ |
void
OnIncomingEmail
This interface defines the method called on new MMS events.
[Callback=FunctionOnly, NoInterfaceObject]
interface OnIncomingEmail {
void onEvent (in EmailMessage
message);
};
onEvent
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
message |
| ✘ | ✘ |
void
MessagingSuccessCB
[Callback=FunctionOnly, NoInterfaceObject]
interface MessagingSuccessCB {
void onSuccess ();
};
onSuccess
void
MessagingErrorCB
[Callback=FunctionOnly, NoInterfaceObject]
interface MessagingErrorCB {
void onError (in MessagingError
error);
};
onError
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
error |
| ✘ | ✘ |
void
MessagingError
interfaceAdds 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;
};
code
of type unsigned short, readonlyINVALID_ARGUMENT_ERROR
of type unsigned shortIO_ERROR
of type unsigned shortMESSAGE_SIZE_EXCEEDED
of type unsigned shortNOT_FOUND_ERROR
of type unsigned shortNOT_SUPPORTED_ERROR
of type unsigned shortPENDING_OPERATION_ERROR
of type unsigned shortPERMISSION_DENIED_ERROR
of type unsigned shortTIMEOUT_ERROR
of type unsigned shortUNKNOWN_ERROR
of type unsigned shortThis is a list of features that have been discussed with respect to this version of the API but for which it has been decided that if they are included it will be in a future revision.
...