- From: Dominique Hazael-Massieux via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 04 Jul 2011 12:55:09 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/messaging
In directory hutz:/tmp/cvs-serv25004
Modified Files:
Overview.html
Log Message:
incorporated robin's feedback per action-400
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/messaging/Overview.html,v
retrieving revision 1.45
retrieving revision 1.46
diff -u -d -r1.45 -r1.46
--- Overview.html 5 May 2011 16:09:44 -0000 1.45
+++ Overview.html 4 Jul 2011 12:55:07 -0000 1.46
@@ -28,8 +28,7 @@
</head>
<body>
<section id='abstract'>
- <p>
- This specification defines an API that provides access to messaging functionality in the device, including SMS, MMS and e-mail.
+ <p>The Contacts API provides a method to send messages based on URIs (e.g. email, MMS, SMS) with optional attachments.
</p>
</section>
@@ -47,28 +46,27 @@
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 e-mail) there is a need to indicate that conformant implementations need only expose available functionality.
- </p>
+ <p>Since not all devices have all messaging functionality (e.g. a phone may have only SMS and MMS while a PC may have only e-mail), conformant implementations need only expose available functionality.</p>
- <p>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.</p>
+ <p>Implementations that use ECMAScript to expose the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]].</p>
<section class='informative' id="intro">
<h1>Introduction</h1>
<p>
- 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.
+ The Messaging API provides a method to send messages based on URIs (e.g. email, MMS, SMS) with optional attachments.
</p>
- <p>These APIs complement what <code>sms:</code>, <code>mms:</code>, and <code>mailto:</code> URI schemes provide with:</p>
+ <p>This API complements what <code>sms:</code>, <code>mms:</code>, and <code>mailto:</code> URI schemes provide with:</p>
<ul>
<li>the possibility to attach files to messages,</li>
- <li>a callback on success / error when a message is sent.</li>
+ <li>a callback on success (resp. error) when a message is successfully passed (resp. has failed to pass) to the platform’s application that handles sending such messages..</li>
</ul>
- <p>The following code extracts illustrate how to create and send messages. </p>
- <div> <p>
- Sending an MMS with an attached picture, if device supports it.
- </p> </div>
+ <p>The following code shows how to send a message with an attachment:</p>
+<pre
+ class='example sh_html'>
+<p><label>Load file to attach: <input type="file" id='attachment'></p>
+<p><input type='submit' value='Send' id='send'></p>
+lt;script></pre>
<pre
class='example sh_javascript_dom'>
function successCB() {
@@ -79,12 +77,16 @@
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);
-}
+document.getElementById('send').addEventListener('click', send, false);
- </pre>
+function send() {
+ if (navigator.sendMessage) {
+ picture = document.getElementById('attachment').files[0];
+ navigator.sendMessage("mms:+460000000001?body=Welcome%20%to%Atlantis", [picture], successCB, errorCB);
+ }
+} </pre>
+<pre
+ class='example sh_html'></script></pre>
</section>
@@ -99,7 +101,7 @@
<p>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.</p>
<p>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.</p>
- <p>In general, user’s consent is expected to be confirmed for each invocation of the <code>sendMessage</code> methods.</p>
+ <p>In general, user’s consent is expected to be confirmed for each invocation of the <code>sendMessage</code> methods. Typically, the user agent would bring forward the application responsible for editing/sending the type of message with pre-filled entries, and the ability for the user to send the message through the said application.</p>
</section>
@@ -113,12 +115,6 @@
<p class="issue">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.</p>
- <section>
- <h2>SMS specific concerns</h2>
- <p>
- 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).
- </p>
- </section>
</section>
<section>
@@ -126,25 +122,26 @@
<section>
<h2> <a>DeviceMessaging</a> </h2>
<p>
- The <a href='#devicemessaging'>DeviceMessaging</a> object is exposed on the <code>navigator.device</code> object, as defined in [[!CORE-DEVICE]].
- </p>
+ The <a href='#devicemessaging'>DeviceMessaging</a> object is exposed on the <code>navigator</code> object</p>
- <div class='idl' title='Device implements DeviceMessaging'></div>
+ <div class='idl' title='Navigator implements NavigatorMessaging'></div>
- <dl title='[NoInterfaceObject] interface DeviceMessaging' class='idl'>
+ <dl title='[NoInterfaceObject] interface NavigatorMessaging' class='idl'>
<dt>void sendMessage()</dt>
<dd>
Sends a message with attachments to the specified address.
<dl class='parameters'>
<dt>
- DOMString to
+ DOMString uri
</dt>
<dd>
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
</dd>
<dt>optional sequence<Blob>? attachments</dt>
<dd>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.</dd>
+ <dt>optional messagingSuccessCB successCB</dt>
+ <dd>A callback function called when the messaging application reports success on sending the message.</dd>
<dt>optional messagingErrorCB errorCB</dt>
<dd>A callback function called when there was an error with sending the message.</dd>
</dl>
@@ -158,16 +155,27 @@
<section>
+ <h2><a>MessagingSuccessCB</a></h2>
+ <dl title='[Callback, NoInterfaceObject] interface MessagingSuccessCB' class='idl'>
+ <dt>
+ void onSuccess ()
+ </dt>
+ <dd>
+ This interface defines the method invoked asynchronously when the messaging application reports success on sending the message.
+ </dd>
+ </dl>
+
+ </section>
+
+
+ <section>
<h2><a>MessagingErrorCB</a></h2>
- <p>
-
- </p>
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface MessagingErrorCB' class='idl'>
+ <dl title='[Callback, NoInterfaceObject] interface MessagingErrorCB' class='idl'>
<dt>
void onError (in MessagingError error )
</dt>
<dd>
- This interface defines the method invoked on failed messaging asynchronous calls defined in this API.
+ This interface defines the method invoked when the messaging application could not be invoked or reported failure on sending the message.
</dd>
<dl class='parameters'>
<dt>
@@ -184,9 +192,6 @@
<section>
<h2><a>MessagingError</a></h2>
- <p class="note">
- Adds Messaging API specific error codes.
- </p>
<p>
The <code>MessagingError</code> interface encapsulates all errors in the manipulation of <code>Messaging</code> objects in the messaging API.
</p>
@@ -197,55 +202,17 @@
<dd>
An unknown error occurred.
</dd>
+
<dt>
- const unsigned short INVALID_ARGUMENT_ERROR = 1
- </dt>
- <dd>
- An invalid parameter was provided when the requested method was invoked.
- </dd>
- <dt>
- const unsigned short TIMEOUT_ERROR = 3
- </dt>
- <dd>
- The requested method timed out before it could be completed.
- </dd>
- <dt>
- const unsigned short PENDING_OPERATION_ERROR = 4
- </dt>
- <dd>
- If the <a>user agent</a> is currently waiting for a callback on an asynchronous messaging operation, as defined in this specification.
- </dd>
- <dt>
- const unsigned short IO_ERROR = 5
- </dt>
- <dd>
- An error occurred in communication with the underlying implementation that meant the requested method could not complete.
- </dd>
- <dt>
- const unsigned short NOT_SUPPORTED_ERROR = 6
- </dt>
- <dd>
- The requested method is not supported by the current implementation.
- </dd>
- <dt>
- const unsigned short PERMISSION_DENIED_ERROR = 20
- </dt>
- <dd>
- Access to the requested method was denied at the implementation or by the user.
- </dd>
- <dt>
- const unsigned short MESSAGE_SIZE_EXCEEDED = 30
+ const unsigned short SENDING_FAILED = 1
</dt>
- <dd>
- The message that has been tried to be sent exceeds the maximum supported size for that message type.
+ <dd>The messaging application failed to send the message.
</dd>
<dt>
- readonly attribute unsigned short code
+ const unsigned short MUA_NOTFOUND = 2
</dt>
- <dd>
- An error code assigned by an implementation when an error has occurred in Messaging API processing.
+ <dd>The user agent was unable to connect with the messaging application.
</dd>
-
</dl>
</section>
Received on Monday, 4 July 2011 12:55:10 UTC