W3C

The Messaging API

W3C Working Draft 14 April 2011

This version:
http://www.w3.org/TR/2011/WD-messaging-api-20110414/
Latest published version:
http://www.w3.org/TR/messaging-api/
Latest editor's draft:
http://dev.w3.org/2009/dap/messaging/
Previous version:
http://www.w3.org/TR/2011/WD-messaging-api-20110120/
Editors:
Dominique Hazaël-Massieux, W3C
Suresh Chitturi, Research in Motion (RIM)
Max Froumentin, Opera
Maria Angeles Oteo, Telefonica
Niklas Widell, Ericsson AB

Abstract

This specification defines an API that provides access to messaging functionality in the device, including SMS, MMS and e-mail.

Status of This Document

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 draft proposes a vastly different approach to the previously published version, using URI schemes as a way to address different messaging protocols instead of using separate methods. The group is specifically looking for feedback on which approach is felt like the most useful.

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.

Table of Contents

1. Conformance

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.

2. Introduction

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 MMS with an attached picture, 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.sendMessage) {
   picture = document.getElementById('attachment').files[0];
   navigator.device.sendMessage("mms:+460000000001?body=Welcome%20%to%Atlantis", [picture], successCB, errorCB);
}

3. Security Considerations

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.

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 and pre-defined attachments.

In general, user’s consent is expected to be confirmed for each invocation of the sendMessage methods.

4. Supported messaging types

The specification supports sending messages on top of protocols for which a URI scheme has been defined, including SMS, MMS and emails.

Using a single method to send message across many protocols make it impossible to detect whether a given user agent supports a specific messaging protocol.

4.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).

5. API Description

5.1 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 {
    void sendMessage (in DOMString to, in sequence<Blob>? attachments, in messagingErrorCB? errorCB);
};

5.1.1 Methods

sendMessage
Sends a message with attachments to the specified address.
ParameterTypeNullableOptionalDescription
toDOMString a URI that specificies the address to which the message is to be sent; that URI may contain query string parameters that specify additional headers and the body of the said message
attachmentssequence<Blob>A list of Blob objects that represent attachments to be sent with the message; only applicable to protocols that support the notion of attachments. Using this parameter on protocols that don't support attachments triggers an error.
errorCBmessagingErrorCBA callback function called when there was an error with sending the message.
No exceptions.
Return type: void

5.2 MessagingErrorCB

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

5.2.1 Methods

onError
This interface defines the method invoked on failed messaging asynchronous calls defined in this API.
ParameterTypeNullableOptionalDescription
errorMessagingError
No exceptions.
Return type: void

5.3 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;
};

5.3.1 Attributes

code of type unsigned short, readonly
An error code assigned by an implementation when an error has occurred in Messaging API processing.
No exceptions.

5.3.2 Constants

INVALID_ARGUMENT_ERROR of type unsigned short
An invalid parameter was provided when the requested method was invoked.
IO_ERROR of type unsigned short
An error occurred in communication with the underlying implementation that meant the requested method could not complete.
MESSAGE_SIZE_EXCEEDED of type unsigned short
The message that has been tried to be sent exceeds the maximum supported size for that message type.
NOT_SUPPORTED_ERROR of type unsigned short
The requested method is not supported by the current implementation.
PENDING_OPERATION_ERROR of type unsigned short
If the user agent is currently waiting for a callback on an asynchronous messaging operation, as defined in this specification.
PERMISSION_DENIED_ERROR of type unsigned short
Access to the requested method was denied at the implementation or by the user.
TIMEOUT_ERROR of type unsigned short
The requested method timed out before it could be completed.
UNKNOWN_ERROR of type unsigned short
An unknown error occurred.

A. Acknowledgements

...

B. References

B.1 Normative references

[CORE-DEVICE]
Robin Berjon. Core Device Interfaces. 02 December 2009. W3C Editor's Draft. (Work in progress.) URL: http://dev.w3.org/2009/dap/device/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219

B.2 Informative references

No informative references.