Copyright © 2011 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 e-mail.
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 was published by the Device APIs and Policy Working Group as a 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 e-mail) 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.
This section is non-normative.
The Messaging API defines a high-level interface to messaging functionality, including SMS, MMS and e-mail. It includes APIs to create and send messages.
These APIs complement what sms:
, mms:
, and mailto:
URI schemes provide with:
The following code extracts illustrate how to create and send 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);
The API defined in this specification can be used to create and send messages through different technologies. Sending messages usually has an associated cost (especially SMSs and MMSs), hence a conforming implementation of this specification should provide a mechanism that ensures that no message is sent without the user's consent.
The methods for sending messages that require user's express permission to be accessed are: SMSMessage.send()
, MMSMessage.send()
and EmailMessage.send()
.
Since the implications of sending a given message may depend on the message attributes (e.g. destination address) and content, the approach used to ensure user’s consent should include the relevant information, typically the type of message and its destination address.
A typical (but not required) way of ensuring user’s consent would be to use the same mechanism as the one used when the user click on a link using one the relevant URI schemes, for instance, bringing up the platform messaging application with pre-filled fields.
In general, user’s consent is expected to be confirmed for each invocation of the send
methods.
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 | |
---|---|---|---|
sentTime |
✓ | ✓ | ✓ |
to |
✓ | ✓ | ✓ |
cc |
N/A | N/A | ✓ |
bcc |
N/A | N/A | ✓ |
subject |
N/A | ✓ | ✓ |
body |
✓ | ✓ | ✓ |
attachments |
N/A | ✓ | ✓ |
priority |
N/A | N/A | ✓ |
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.
The Working Group plans in reworking this interface to rely more directly on URI schemes rather than having a per messaging protocol method.
interface MessagingManager {
SMSMessage
createSMS (in SMSProperties
smsProperties);
MMSMessage
createMMS (in MMSProperties
mmsProperties);
EmailMessage
createEmail (in EmailProperties
emailProperties);
};
createEmail
EmailMessage
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
emailProperties |
| ✘ | ✘ | The e-mail properties may include the "to", "cc", "bcc", "subject", "body", "priority" and "attachments" attributes. |
EmailMessage
createMMS
MMSMessage
object.
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
mmsProperties |
| ✘ | ✘ | The MMS properties may include the "to", "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
SMSMessage
This interface describes generic functionality of SMS message.
[NoInterfaceObject]
interface SMSMessage : SMSProperties
{
readonly attribute Date sentTime;
PendingOp send (in MessagingSuccessCB
successCB, in optional MessagingErrorCB
errorCB);
};
sentTime
of type Date, readonlysend
pendingOp
return 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 Date sentTime;
PendingOp send (in MessagingSuccessCB
successCB, in optional MessagingErrorCB
errorCB);
};
sentTime
of type Date, readonlysend
pendingOp
return 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 Date sentTime;
PendingOp send (in MessagingSuccessCB
successCB, in optional MessagingErrorCB
errorCB);
};
sentTime
of type Date, readonlysend
pendingOp
return object allows cancelling 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 EmailAddress
[] to;
attribute EmailAddress
[] cc;
attribute EmailAddress
[] bcc;
attribute DOMString subject;
attribute DOMString body;
attribute DOMString priority;
attribute Blob[] attachments;
};
attachments
of type array of Blobbcc
of type array of EmailAddress
body
of type DOMStringcc
of type array of EmailAddress
priority
of type DOMStringsubject
of type DOMStringto
of type array of EmailAddress
EmailAddress
This interface captures the data fields in an e-mail address.
[NoInterfaceObject]
interface EmailAddress {
attribute DOMString address;
attribute DOMString name;
};
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
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 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_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 shortThe following messaging functionalities have been delayed to a future version of the API.
...
No informative references.