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 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.
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 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); }
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.
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.
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 {
void sendMessage (in DOMString to, in sequence<Blob>? attachments, in messagingErrorCB? errorCB);
};
sendMessage
Parameter | Type | Nullable | Optional | Description |
---|---|---|---|---|
to | DOMString | ✘ | ✘ | 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 |
attachments | sequence<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. |
errorCB | messagingErrorCB | ✔ | ✘ | A callback function called when there was an error with sending the message. |
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 short...
No informative references.