- From: Maria Angeles Oteo via cvs-syncmail <cvsmail@w3.org>
- Date: Tue, 30 Nov 2010 15:45:23 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/messaging
In directory hutz:/tmp/cvs-serv7890
Modified Files:
Overview.html
Log Message:
Updated Messaging API based on Lyon decision
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/messaging/Overview.html,v
retrieving revision 1.25
retrieving revision 1.26
diff -u -d -r1.25 -r1.26
--- Overview.html 23 Aug 2010 09:24:53 -0000 1.25
+++ Overview.html 30 Nov 2010 15:45:21 -0000 1.26
@@ -108,13 +108,13 @@
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.
+ including SMS, MMS and Email. It includes APIs to create and send messages.
</p>
<p>
- The following code extracts illustrate how to create, send and receive messages.
+ The following code extracts illustrate how to create and send messages.
</p>
@@ -152,44 +152,8 @@
</pre>
- <div> <p>
-
- Register listener for new SMS events.
-
- </p> </div>
-
-<pre
-
- class='example sh_javascript_dom'>
-
-// function to receive new SMS notifications
-
-function incomingSMS(message)
-
-{
-
- alert("New incoming SMS from " + message.from);
-
- if (mySMSListener != null)
-
- navigator.device.messaging.unsubscribe(mySMSListener);
-
-}
-
-
-
-// Register listener for new SMS events
-
-var mySMSListener = null;
-
-mySMSListener = navigator.device.messaging.onSMS(incomingSMS);
-
-
-
- </pre>
-
</section>
@@ -200,7 +164,7 @@
<p>
- This specification is limited to providing a scripting API for creating, sending and receiving messages. The supported messaging types include SMS, MMS and Email.
+ This specification is limited to providing a scripting API for creating and sending messages. The supported messaging types include SMS, MMS and Email.
</p>
@@ -220,48 +184,39 @@
<h1>Security Considerations</h1>
- <p class='note'>
- The overall architecture for addressing privacy in DAP is still under construction. As it is finalized, there may be changes made
- to this API to reflect requirements or support for privacy-related functionality.
+ <p>
+
+ 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
+ MUST provide a mechanism that ensures that no message is sent without the user's express permission.
+
</p>
+
<p>
- The API defined in this specification can be used to create and subscribe for incoming messages through different technologies.Sending messages usually
- have a cost associated to them, especially SMSs and MMSs. Furthermore this cost may depend on the message attributes (e.g. destination address)
- or external conditions (e.g. roaming status). Apart from billing implications, there are also privacy considerations due
- to the capability to access message contents.
-
- A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism
- should ensure that no message is sent or no subscription is establisehd without the user's express permission.
+ The methods for sending messages that require user's express permission to be accessed are:
</p>
-
- <section>
- <h2>
- Privacy considerations for implementors of the Messaging API
- </h2>
- <p>
- A <a>user agent</a> must not send messages or subscribe for incoming ones without the express permission of the
- user. A <a>user agent</a> must acquire permission through a user interface, unless they have prearranged trust relationships with
- users, as described below. The user interface must include the URI of the document origin, as defined in [[HTML5]]. Those
- permissions that are acquired through the user interface and that are preserved beyond the current browsing session (i.e. beyond
- the time when the browsing context, as defined in [[HTML5]], is navigated to another URL) MUST be revocable and a <a>user
- agent</a> must respect revoked permissions.
- </p>
- <p>
- The methods that require user's express permission to be accessed are:
- <ul>
-
- <li> SMSMessage.send(), MMSMessage.send() and EmailMessage.send(). </li>
-
- <li> MessagingManager.onSMS(), MessagingManager.onMMS() and MessagingManager.onEmail().</li>
-
- </ul>
- Obtaining once the user's express permission to access those methods does not imply the user has granted permission for
- later invocations of the same method or any other method provided by this API. This is especially important in the case
- of message sending, as every method invocation may lead to extra charges to the user.
- </p>
+ <p>
+ SMSMessage.send(), MMSMessage.send() and EmailMessage.send().
+ </p>
+
+ <p>
+ Unless the <a>user agent</a> has a prearranged trust relationship with the user, it MUST acquire permission through a user interface.
+ The cost of sending the message may depend on the message attributes (e.g. destination address) or external conditions
+ (e.g. roaming status). Due to that, the user interface MUST include the type of message to be sent and its destination
+ (i.e. the "to" attribute of the message) so that the user can take an informed decision. Additionally, the user interface MUST
+ include the URI of the document origin, as defined in [[!HTML5]].
+ </p>
+
+ <p>
+ Obtaining permission through the user interface for one invocation of the method MUST NOT imply consent for future invocations
+ of the same method, i.e. user interface authorization must be done every time the send method is invoked.
+ </p>
+
+
<p>
A <a>user agent</a> may have prearranged trust relationships that do not require such user interfaces. For example, while a Web
- browser will present a user interface when a Web site request an SMS subscription, a Widget Runtime MAY have a prearranged,
+ browser will present a user interface when a Web site requests sending an SMS, a Widget Runtime MAY have a prearranged,
delegated security relationship with the user and, as such, a suitable alternative security and privacy mechanism with which to
authorize that operation.
</p>
@@ -578,110 +533,8 @@
</dl>
</dd>
-
-
-
-
-
- <dt>int onSMS (in OnIncomingSMS messageEventCB)</dt>
-
- <dd>
-
- Registers the function to be notified on incoming new SMSs. The function call returns a handle to the subscription
-
- <dl class='parameters'>
-
- <dt>
-
- OnIncomingSMS messageEventCB
-
- </dt>
-
- <dd>
-
- The callback method for new SMS events
-
- </dd>
-
- </dl>
-
- </dd>
-
- <dt>int onMMS (in OnIncomingMMS messageEventCB)</dt>
-
- <dd>
-
- Registers the function to be notified on incoming new MMSs. The function call returns a handle to the subscription
-
- <dl class='parameters'>
-
- <dt>
-
- OnIncomingMMS messageEventCB
-
- </dt>
-
- <dd>
-
- The callback method for new MMS events
-
- </dd>
-
- </dl>
-
- </dd>
-
- <dt>int onEmail (in OnIncomingEmail messageEventCB)</dt>
-
- <dd>
-
- Registers the function to be notified on incoming new Emails. The function call returns a handle to the subscription
-
- <dl class='parameters'>
-
- <dt>
-
- OnIncomingEmail messageEventCB
-
- </dt>
-
- <dd>
-
- The callback method for new Email events
-
- </dd>
-
- </dl>
-
- </dd>
-
-
-
-
-
- <dt>void unsubscribe (in int subscriptionHandle)</dt>
-
- <dd>
-
- Removes subscription for new messaging events.
-
- <dl class='parameters'>
-
- <dt>
-
- int subscriptionHandle
-
- </dt>
-
- <dd>
-
- Handle to the subscription to be cancelled.
-
- </dd>
-
- </dl>
-
- </dd>
+
+
</dl>
@@ -991,7 +844,8 @@
<dd>
- Asynchronous method to request sending an message. Upon a successful invocation the message is delivered to the nnetwork. The <code>pendingOp</code> returns object allows canceling the sending of the message.
+ Asynchronous method to request sending an message. Upon a successful invocation the message is delivered to the network.
+ The <code>pendingOp</code> returns object allows cancelling the sending of the message.
<dl class='parameters'>
@@ -1143,7 +997,7 @@
<dd>
- The list of paths to attachments that will be sent together with the MMS
+ The list of files [[!FILE-API]] that will be sent together with the MMS as attachments.
</dd>
@@ -1177,7 +1031,7 @@
<dd>
- The set of e-mail addresses of the recipients.
+ The set of e-mail addresses of the recipients. E-mail addresses MUST use the format specified in [[!EMAIL]].
</dd>
@@ -1189,19 +1043,19 @@
<dd>
- The set of cc (carbon copy) addresses of the recipients.
+ The set of cc (carbon copy) addresses of the recipients. E-mail addresses MUST use the format specified in [[!EMAIL]].
</dd>
- <dt> attribute DOMString[] bcc
+ <dt> attribute DOMString[] bcc.
</dt>
<dd>
- The set of bcc (blind carbon copy) addresses of the recipients.
+ The set of bcc (blind carbon copy) addresses of the recipients. E-mail addresses MUST use the format specified in [[!EMAIL]].
</dd>
@@ -1269,7 +1123,7 @@
<dd>
- The list of paths to attachments that will be sent together with the e-mail
+ The list of files [[!FILE-API]] that will be sent together with the e-mail as attachments.
</dd>
@@ -1281,153 +1135,8 @@
-
-
- <section>
-
- <h2><a>OnIncomingSMS</a></h2>
-
- <p>
-
- This interface defines the method called on new SMS events.
-
- </p>
-
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingSMS' class='idl'>
-
- <dt>
-
- void onEvent (in SMSMessage message)
-
- </dt>
-
- <dd>
-
- This method is invoked when an SMS is received in the device.
-
- </dd>
-
- <dl class='parameters'>
-
- <dt>
-
- SMSMessage message
-
- </dt>
-
- <dd>
-
- Reference to the incoming SMS.
-
- </dd>
-
- </dl>
-
- </dl>
-
-
-
- </section>
-
-
-
- <section>
-
- <h2><a>OnIncomingMMS</a></h2>
-
- <p>
-
- This interface defines the method called on new MMS events.
-
- </p>
-
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingMMS' class='idl'>
-
- <dt>
-
- void onEvent (in MMSMessage message)
-
- </dt>
-
- <dd>
-
- This method is invoked when an MMS is received in the device.
-
- </dd>
-
- <dl class='parameters'>
-
- <dt>
-
- MMSMessage message
-
- </dt>
-
- <dd>
-
- Reference to the incoming MMS.
-
- </dd>
-
- </dl>
-
- </dl>
-
-
-
- </section>
-
-
-
- <section>
-
- <h2><a>OnIncomingEmail</a></h2>
-
- <p>
-
- This interface defines the method called on new MMS events.
-
- </p>
-
- <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingEmail' class='idl'>
-
- <dt>
-
- void onEvent (in EmailMessage message)
-
- </dt>
-
- <dd>
-
- This method is invoked when an E-mail is received in the device.
-
- </dd>
-
- <dl class='parameters'>
-
- <dt>
-
- EmailMessage message
-
- </dt>
-
- <dd>
-
- Reference to the incoming E-mail.
-
- </dd>
-
- </dl>
-
- </dl>
-
-
-
- </section>
-
-
-
+
<section>
Received on Tuesday, 30 November 2010 15:45:25 UTC