- From: Niklas Widell via cvs-syncmail <cvsmail@w3.org>
- Date: Fri, 22 Jan 2010 14:30:00 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/messaging
In directory hutz:/tmp/cvs-serv20436
Modified Files:
Overview.html
Log Message:
First rough draft
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/messaging/Overview.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Overview.html 14 Sep 2009 15:36:05 -0000 1.2
+++ Overview.html 22 Jan 2010 14:29:58 -0000 1.3
@@ -3,10 +3,8 @@
<head>
<title>The Messaging API</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
- <script src='../ReSpec.js/js/simple-node.js' class='remove'></script>
- <script src='../ReSpec.js/js/shortcut.js' class='remove'></script>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
- <script src='../ReSpec.js/bibref/biblio.js' class='remove'></script>
+
<script class='remove'>
var respecConfig = {
specStatus: "ED",
@@ -14,31 +12,397 @@
// publishDate: "2009-08-06",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/messaging/",
- // lcEnd: "2009-08-05",
+ editors: [
+ {name: "Daniel Coloma", company: "Telefonica"},
+ {name: "Niklas Widell", company: "Ericsson AB"},
+ ],
+ // lcEnd: "2009-08-05",
};
</script>
<script src='../common/config.js' class='remove'></script>
</head>
<body>
<section id='abstract'>
- This is the abstract for your specification.
+ <p>
+ This specification defines an API that provides access to messaging functionality in the device, including SMS, MMS and email.
+ </p>
+ <p class=note>
+ Currently only SMS is covered.
+ </p>
</section>
<section id='conformance'></section>
+ <p>
+ This specification defines conformance criteria that apply to a single product:
+ <dfn>
+ user agents
+ </dfn>
+ that implement the interfaces that it contains.
+ </p>
+ <p class='note'>
+ 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.
+ </p>
+
+
+ <section id='informative'>
+ <h1>Introduction</h1>
+
+ <p>
+ 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, and to inspect and manipulate the folders where the messages are kept.
+ </p>
+
+ <p>
+ The email and SMS APIs defined in this specification complements rather than replaces the mailto and SMS URLs defined. For a discussion please see <a href='#alternate-messaging-options'>Alternate Messaging Options</a> section below.
+ </p>
+
+ <p>
+ The following code extracts illustrate how to create, send and receive messages.
+ </p>
+ <div>
+ <p>
+ Creating an SMS.
+ </p>
+ <pre class='example sh_javascript_dom'>mySMS=navigator.device.messaging.createSMS(
+ {to: [{'+460000000001'}], body: "Welcome to Atlantis"});
+ </div>
+
+ <div>
+ <p>
+ Sending an SMS.
+ </p>
+ <pre class='example sh_javscript_dom'>
+function successSMSCB(message) {
+ // do something with resulting message objects
+ // ...
+}
+
+function errorSMSCB(error) {
+ // do something with resulting errors
+ // ...
+}
+
+pendOp=navigator.device.messaging.sendSMS(mySMS, sucessSMSCB, errorSMSCB);
+// May use pendOp to cancel sending request
+
+ </div>
+ <div>
+ <p>
+ Register listener for new SMS events.
+ </p>
+ <pre class='example sh_javascript_dom'>
+// Register listener for new SMS events
+mySMSListener=navigator.device.messaging.subscribeSMSEvent(onSMSEvent); </div>
+ </section>
+
<section>
- <h2>Requirements</h2>
+ <h1>Scope</h1>
+ <p>
+ This specification is limited to providing a scripting API for creating, sending and receiving messages; as well as inspection and manipulation of message folders; on a device. The supported messaging types include SMS, MMS and Email.
+ </p>
+
+ <p>
+ The specification does not replace RFCs for Mail or SMS URLs. The specification includes complementary functionality to these. Please see <a href='#alternate-messaging-options'>Alternate Messaging Options</a> section for a discussion on this topic.
+ </p>
+ </section>
+
+ <section>
+ <h1>Security Considerations</h1>
+ <p class=note>
+ Obviously more work is needed here. Presumably a security model similar to Geolocation may be used. Due to slightly different nature of SMS/MMS and email minor differences may need to be spelt out explicitly.
+ </p>
+ <p>
+ Some observations:
+ </p>
+ <ul>
+ <li>SMS and MMS often have an associated cost creating an additional economic risk for the user</li>
+ <li>Currently preferred points that would require user security attention are (a) upon sending the finished message, (b) upon saving something in message folder, and (c) upon start of message folder exploration.</li>
+ </ul>
+ </section>
+
+ <section>
+ <h1>API Description</h1>
+ <section>
+ <h2><a>DeviceMessaging</a> interface</h2>
+ <p>
+ The <a href='#devicemessaging-interface'><code>DeviceMessaging</code></a>object is exposed on the <code>navigator.device</code> object, as defined in [[CORE_DEVICE]].
+ </p>
+
+ <div class='idl' title='Device implements DeviceMessaging'></div>
+
+ <dl title='[NoInterfaceObject] interface DeviceMessaging' class='idl'>
+ <dt>
+ readonly attribute Messaging messaging
+ </dt>
+ <dd>
+ The root node from which the messaging functionality can be accessed.
+ </dd>
+ </dl>
+ <p>
+
+ </p>
+
+ </section>
+
+ <section>
+ <h2><a>Messaging</a></h2>
+ <p>
+ This is the core class for managing messaging. It provides functionality to create and send messages, registering for notifications of new messages and is the entry point for managing messaging accounts.
+ </p>
+ <dl title='interface Messaging' class='idl'>
+ <dt>SMS createSMS (in SMSOptions smsoptions)</dt>
+ <dd>
+ Creates a new <code>SMS</code> object. Note that there are size limitations for SMS's sent on a network (the actual maximum size depends on language encoding the content). When an too long SMS object is sent the device may split of the message into several parts.
+ <dl class='parameters'>
+ <dt>
+ SMSOptions smsoptions
+ </dt>
+ <dd>
+ The fields in the SMS, including list of recipients, text body etc.
+ </dd>
+ </dl>
+ </dd>
+
+ <dt>PendingOp sendSMS (in SMS sms, in SuccessCallback successCB, [optional] in ErrorCallback errorCB)</dt>
+ <dd>
+ Sends the SMS. The success function is called when the SMS has been sent, to the implementation it means that the SMS has been placed in the Outgoing Messages folder. The <code>pendingOp</code> return object allows canceling the sending of the SMS.
+ <dl class='parameters'>
+ <dt>
+ SMS sms
+ </dt>
+ <dd>
+ The SMS to be sent.
+ </dd>
+
+ <dt>
+ SuccessCallback successCB
+ </dt>
+ <dd>
+ The success function is called when the SMS has been sent. To the implementation it means that the SMS has been placed in the Outgoing Messages folder.
+ </dd>
+
+ <dt>
+ ErrorCallback errorCB
+ </dt>
+ <dd>
+ </dd>
+ </dl>
+ </dd>
+
+ <dt>int subscribeSMSEvent (in OnIncomingSMS smsEventCB)</dt>
+ <dd>
+ Registers the page to be notified on incoming new SMSs. The return parameter of the function call is a handle to the requested subscription
+ <dl class=parameters>
+ <dt>
+ OnIncomingSMS smsEventCB
+ </dt>
+ <dd>
+ The callback method for new SMS events
+ </dd>
+ </dl>
+ </dd>
+
+ <dt>void unsubscribeSMSEvent (in int subscribeHandle)</dt>
+ <dd>
+ Removes subscription for new SMS events.
+ <dl class=parameters>
+ <dt>
+ int subscribeHandle
+ </dt>
+ <dd>
+ Handle to the subscription to be cancelled.
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2><a>SMS</a></h2>
+ <p>
+ The <code>SMS</code> interface captures a single SMS message. The interface extends the <a href='#smsoptions-interface'><code>SMSOptions</code></a> interface.
+ </p>
+ <dl title='interface SMS implements SMSOptions' class='idl'>
+ <dt> Object getProperty(in DOMString propertyName)</dt>
+ <dd>
+ Returns value of specified SMS message property
+ </dd>
+ <dl class=parameters>
+ <dt>
+ DOMString propertyName
+ </dt>
+ <dd>
+ Name of requested property
+ </dd>
+ </dl>
+
+ <dt> void setProperty(in DOMString propertyName, in DOMString propertyValue)</dt>
+ <dd>
+ Sets the specified property to the specified value.
+ </dd>
+ <dl class=parameters>
+ <dt>
+ DOMString propertyName
+ </dt>
+ <dd>
+ Name of property to be set.
+ </dd>
+ <dt>
+ DOMString propertyValue
+ </dt>
+ <dd>
+ New value of property.
+ </dd>
+ </dl>
+
+ <dt> readonly attribute DOMString id </dt>
+ <dd>
+ System set read-only unique identifier to assigned to the message by the platform.
+ </dd>
+ <dt> attribute DOMString body </dt>
+ <dd>
+ Text message body of the SMS
+ </dd>
+ <dt> attribute sequence<DOMString> to</dt>
+ <dd>
+ List of phone numbers of intended recipients of the message.
+ </dd>
+
+
+
+ </dl>
+ </section>
+
+ <section>
+ <h2><a>SMSOptions</a></h2>
+ <p>
+ This interface captures the data fields in an SMS.
+ </p>
+ <dl title='[NoInterfaceObject] interface SMSOptions' class='idl'>
+ <dt> attribute sequence<DOMString> to
+ </dt>
+ <dd>
+ The set of phone numbers of the recipients.
+ </dd>
+
+ <dt>
+ attribute DOMString body
+ </dt>
+ <dd>
+ The text body of an SMS. If the text body is too long it will be divided into multiple messages (multi-part SMS).
+ </dd>
+ </dl>
+ </section>
+
+ <section>
+ <h2><a>OnIncomingSMS</a></h2>
+ <p>
+ This interface defines the method called on new message (SMS) events.
+ </p>
+ <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingSMS' class='idl'>
+ <dt>
+ void onEvent (in SMS message)
+ </dt>
+ <dd>
+ This method is invoked when an SMS arrives.
+ </dd>
+ <dl class=parameters>
+ <dt>
+ SMS message
+ </dt>
+ <dd>
+ Reference to the incoming SMS.
+ </dd>
+ </dl>
+ </dl>
+
+ </section>
+ </section>
+
+
+
+ <section class="informative">
+ <h2>ToDo</h2
+ <ul>
+ <li>Support for MMS, email</li>
+ <li>Account management</li>
+ <li>Support for other messaging types (IM, CPM)?</li>
+ <li>Is account functionality per messaging type or general</li>
+ <li>Notion of default accounts</li>
+ <li>Relationship attachements/file system (how to address/find attachments</li>
+ <li>device==>service or whatever comes of out of "hang discussion"</li>
+ <li>Reference to MAILTO and SMS URI documents</li>
+ </ul>
+ </section>
+
+ <section class="informative">
+ <h2>Alternate messaging options</h2>
+ <section>
+ In addition to the messaging options described in this specification there is an option to use URL based schemes with email (mailto) RFC2368 and SMS RFC5724 for web page initiated messaging.
+
+ <section>
+ <h3>SMS URI (RFC5724)</h3>
+ <p>
+ RFC5724 introduces a URI scheme similar to mailto to allow specifying recipients and body text for SMS messages. When a SMS URI is activated, the user agent may open an SMS messaging client to send an SMS. In similarity to mailto, this requires that the browser can handle the scheme and that an external SMS messaging program is correctly configured. There is no requirement that the SMS messaging program must be running same device as the user agent, allowing the use of e.g. external web based services to fulfill the request. The URI specification requires one or more phone numbers (a la RFC3966 Section 5.1) and an optional percent-encoded UTF-8 text body. The implementation is required to correctly translate the text body to suitable encoding.
+ </p>
+
+ <p>
+ The user agent must handle the SMS URI with similar carefulness as specified for mailto (i.e. must not pass obviously unsafe headers, must not send without user action, etc).
+ </p>
+
+ <p>
+ Examples of SMS URI usage
+ </p>
+ <ul>
+ <li><code>sms:+4646000001</code> (addressing single recipient)</li>
+ <li><code>sms:+4646000001,+4646000002</code> (addressing two recipients)</li>
+ <li><code>sms:+4646000001?body=Welcome%20to%20Atlantis</code> (sending message single recipient with initial message indicated)</li>
+ </ul>
+ <p>
+ <i>Comments on relationship between DAP Messaging and SMS URI</i> The SMS URI approach typically hands of the details of the messaging to an external messaging application. It thus commonly leaves the control of the user agent and web application, providing no feedback to the application whether something was sent or not, or what a sent message actually contained. The SMS URI specification does not cover events resulting from arriving SMSs, nor the manipulation of the SMS message store, making the creation of a web application based SMS messaging application difficult.
+ </p>
+ </section>
+ </section>
+ </section>
+
+ <section>
+ <h2>Use-cases and Requirements</h2>
+ <section>
+ <h3>Use-cases</h3>
+ <section>
+ <h4>Use case 1: Create and send message</h4>
+ <p>The user wants to create and send a message (of any configured type). The Messaging API allows creation and sending of messages all performed within the web application, without distracting change to other application. The Messaging API also allows progress feedback to the web application on whether the message was sent or not.
+ </p>
+ <p class=note>(The SMS and Mailto URL schemes satisfy the "create" and "enable send" part of this use case.) </p>
+ </section>
+ <section>
+ <h4>Use case 2: Create and send message from particular account</h4>
+ A user has multiple messaging accounts configured on a device (e.g. "personal", "work"). The user wants to send a message through the "personal" account. The Messaging API allows selection of messaging account for outgoing messages.
+ </section>
+ </section>
+
+ <section>
+ <h3>Requirements</h3>
<p>
- ...
+ This interface:
</p>
+ <ul>
+ <li><em title="must" class="rfc2119">must</em> support messages in one or several formats and transports supported by the platform (email, SMS, MMS...);</li>
+ <li><em title="must" class="rfc2119">must</em> allow creating and sending messages;</li>
+ <li><em title="must" class="rfc2119">must</em> support multiple accounts for each transport/format type;</li>
+ <li><em title="must" class="rfc2119">must</em> support setting various envelope fields corresponding to the message type (email, SMS...);</li>
+ <li><em title="must" class="rfc2119">must</em> support attaching files when the format allows it.</li>
+ </ul>
+ </section>
+
</section>
+
<section class='appendix'>
<h2>Features for Future Consideration</h2>
<p>
- This 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.
+ This 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.
</p>
<ul>
<li>...</li>
@@ -52,4 +416,4 @@
</p>
</section>
</body>
-</html>
+</html>
\ No newline at end of file
Received on Friday, 22 January 2010 14:30:02 UTC