2009/dap/messaging Overview.html,1.6,1.7

Update of /sources/public/2009/dap/messaging
In directory hutz:/tmp/cvs-serv9253

Modified Files:
	Overview.html 
Log Message:
Radical rewrite - all messages are equal

Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/messaging/Overview.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- Overview.html	27 Jan 2010 10:46:35 -0000	1.6
+++ Overview.html	22 Feb 2010 20:51:17 -0000	1.7
@@ -14,6 +14,7 @@
           edDraftURI:           "http://dev.w3.org/2009/dap/messaging/",
           editors: [
           {name: "Daniel Coloma", company: "Telefonica"},
+          {name: "Max Froumentin", company: "Opera"},
           {name: "Niklas Widell", company: "Ericsson AB"},
            ],
           // lcEnd: "2009-08-05", 
@@ -26,9 +27,7 @@
       <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>
@@ -44,9 +43,7 @@
     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>
 
-			<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 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> 
     
     
     <section id='informative'>
@@ -54,7 +51,7 @@
 
     <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.
+    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>
@@ -64,32 +61,25 @@
     <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.
+  	Sending an SMS, if device supports it. 
   	</p>
   	<pre class='example sh_javscript_dom'>
-function successSMSCB(message) {
+function successCB(message) {
 	// do something with resulting message objects
 	// ...
 }
 
-function errorSMSCB(error) {
+function errorCB(error) {
 	// do something with resulting errors
 	// ...
 }
 
-pendOp=navigator.device.messaging.sendSMS(mySMS, sucessSMSCB, errorSMSCB);  
-// May use pendOp to cancel sending request
+if (navigator.device.messaging.supportsType(MESSAGE_TYPE_SMS))
+   navigator.device.messaging.create({to: [{'+460000000001'}], body:
+"Welcome to Atlantis"}).send(successCB, errorCB);
 
   	</div>
   	<div>
@@ -97,8 +87,10 @@
   		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>
+mySMSListener=navigator.device.messaging.subscribe(SMS_TYPE, onEvent);  	</div>
     </section>
       
     <section>
@@ -107,10 +99,10 @@
     	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 class='note'>
+    	The specification does not replace RFCs for Mail or SMS URLs. The specification includes complementary functionality to these. Please see <a  href='#scheme-based-messaging-options'>Scheme based Messaging Options</a> section for a discussion on this topic.
     	</p>
-    </section>
+    	</section>
     
     <section>
     	<h1>Security Considerations</h1>
@@ -126,6 +118,74 @@
     	</ul>
     	</section>
     
+    <section>
+    	<h1>Supported messaging types</h1>
+    	
+		<p class='note'>
+			There is a question of how much differentiation should be made between different messaging types. The current approach is to define a set of generic attributes shared by all messages. 
+		</p>
+		<p>
+			The table below presents the attributes that must be supported for each given message type. By support is meant that the implementation must be able to correctly per attribute type handle non-<code>null</code> attributes of this type. Thus, a message may have a non-null value in a attribute which is not supported in the message's type, but the user agent is free to disregard the attribute. 
+		</p>
+		<table border="1">
+		<tr>
+			<th>Attribute</th>
+			<th>SMS</th>
+			<th>MMS</th>
+			<th>Email</th>
+		</tr>
+		<tr>
+			<td><code>to</code></td>
+			<td>X</td>
+			<td>X</td>
+			<td>X</td>
+		</tr>
+		<tr>
+			<td><code>cc</code></td>
+			<td>-</td>
+			<td>-</td>
+			<td>X</td>
+		</tr>
+		<tr>
+			<td><code>bcc</code></td>
+			<td>-</td>
+			<td>-</td>
+			<td>X</td>
+		</tr>
+		<tr>
+			<td><code>from</code></td>
+			<td>X</td>
+			<td>X</td>
+			<td>X</td>
+		</tr>
+		<tr>
+			<td><code>subject</code></td>
+			<td>-</td>
+			<td>-</td>
+			<td>X</td>
+		</tr>
+		<tr>
+			<td><code>body</code></td>
+			<td>X</td>
+			<td>X</td>
+			<td>X</td>
+		</tr>
+		<tr>
+			<td><code>attachments</code></td>
+			<td>-</td>
+			<td>X</td>
+			<td>X</td>
+		</tr>
+		</table>
+		
+		<section>
+		<h3>SMS specific concerns</h3>
+		<p>
+			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. This means that one message objects may be split into several actual messages sent (if the platform supports multi-part messages). 
+		</p>
+		</section>
+	</section>
+	
 	<section>
     	<h1>API Description</h1>
       	<section>
@@ -138,7 +198,7 @@
 					
 				<dl title='[NoInterfaceObject] interface DeviceMessaging' class='idl'>
 					<dt>
-						readonly attribute Messaging messaging
+						readonly attribute MessagingManager messaging
 					</dt>
 					<dd>
 						The root node from which the messaging functionality can be accessed.
@@ -151,173 +211,216 @@
 		</section>
 		
 		<section>
-			<h2><a>Messaging</a></h2>
+			<h2><a>MessagingManager</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.
+				This interface general functionality that relates to messaging. 
 			</p>
-				<dl title='[NoInterfaceObject] interface Messaging' class='idl'>
-				<dt>SMS createSMS (in SMSOptions smsoptions)</dt>
+			<dl title='interface MessagingManager' class='idl'>
+				<dt>const unsigned short SMS_TYPE = 1</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>
+						Constant to indicate messages of type SMS. 
 					</dd>
-					
-				<dt>PendingOp sendSMS (in SMS sms, in SuccessCallback successCB, [optional] in ErrorCallback errorCB)</dt>
+				<dt>const unsigned short MMS_TYPE = 2</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. 
+						Constant to indicate messages of type MMS. 
+					</dd>
+				<dt>const unsigned short EMAIL_TYPE = 3</dt>
+					<dd>
+						Constant to indicate messages of type email. 
+					</dd>
+				
+				<dt>Message create (unsigned short messagingType, in MessageProperties messageProperties)</dt>
+					<dd>
+						Creates a new  <code>Message</code> object, with type set to <code>messagingType</code>. 
 						<dl class='parameters'>
 							<dt>
-								SMS sms
+								unsigned short messagingType
 							</dt>
 							<dd>
-								The SMS to be sent.
+								Type of message (SMS, MMS or email).
 							</dd>
-							
 							<dt>
-								SuccessCallback successCB
+								MessageProperties messageProperties
 							</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.
+								The fields in the message, may include list of recipients, text body etc. 
 							</dd>
-							
+						</dl>
+					</dd>
+					
+				<dt>Boolean supports (unsigned short messagingType)</dt>
+					<dd>
+						Checks if messaging using <code>messagingType</code> is currently supported
+						<dl class='parameters'>
 							<dt>
-								ErrorCallback errorCB
+								unsigned short messagingType
 							</dt>
 							<dd>
+								Requested messaging type. 
 							</dd>
 						</dl>
 					</dd>
+				
 					
-				<dt>int subscribeSMSEvent (in OnIncomingSMS smsEventCB)</dt>
+				<dt>int subscribe (in unsigned short messagingType, 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
+						Registers the page to be notified on incoming new messages. The function call returns a handle to the  subscription
 						<dl class=parameters>
 							<dt>
-								OnIncomingSMS smsEventCB
+								unsigned short messagingType
 							</dt>
 							<dd>
-								The callback method for new SMS events
+								The type of messaging events (e.g. SMS, MMS or email) to listen to. 
+							</dd>
+							<dt>
+								OnIncomingMessage messageEventCB
+							</dt>
+							<dd>
+								The callback method for new messaging events
 							</dd>			
 						</dl>
 					</dd>
 					
-				<dt>void unsubscribeSMSEvent (in int subscribeHandle)</dt>
+				<dt>void unsubscribe (in int subscriptionHandle)</dt>
 					<dd>
 						Removes subscription for new SMS events.
 						<dl class=parameters>
 							<dt>
-								int subscribeHandle
+								int subscriptionHandle
 							</dt>
 							<dd>
 								Handle to the subscription to be cancelled. 
 							</dd>			
 						</dl>
 					</dd>
-			</dl>	
-			</section>
-			
+			</dl>
+				
+				
+				
+			</dl>
+		</section>
+		
 		<section>
-			<h2><a>SMS</a></h2>
+			<h2><a>Message</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. 
+				This interface describes generic functionality of message. 
 			</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>
-				
+			<dl title='[NoInterfaceObject] interface Message implements MessageProperties' class='idl'>
+
 				<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
+				<dt>
+					readonly attribute Date timestamp
+				</dt>
+				<dd>
+					A readonly time stamp indicating when the message was sent, edited or recieved. Interpretation of datetime depends on what message folder the message is found in. 
 				</dd>
-				<dt> attribute sequence&lt;DOMString> to</dt>
-				<dd> 
-					List of phone numbers of intended recipients of the message.
+				<dt>
+					readonly attribute unsigned short messagingType
+				</dt>
+				<dd>
+					The type of the message.
 				</dd>
-				
-				
-				
+				<dt>PendingOp send (in SuccessCallback successCB, [optional] in ErrorCallback errorCB)</dt>
+					<dd>
+						Sends the message. The success function is called when the message has been sent, to the implementation it means that the message has been placed in the Outgoing Messages folder. The <code>pendingOp</code> return object allows canceling the sending of the message. 
+						<dl class='parameters'>
+							<dt>
+								Message message
+							</dt>
+							<dd>
+								The message to be sent.
+							</dd>
+							
+							<dt>
+								SuccessCallback successCB
+							</dt>
+							<dd>
+								The success function is called when the message has been sent. To the implementation it means that the message has been placed in the Outgoing Messages folder.
+							</dd>
+							
+							<dt>
+								ErrorCallback errorCB
+							</dt>
+							<dd>
+							</dd>
+						</dl>
+					</dd>
 			</dl>
-			</section>
-			
+		</section>
+		
 		<section>
-			<h2><a>SMSOptions</a></h2>
+			<h2><a>MessageProperties</a></h2>
 			<p>
-				This interface captures the data fields in an SMS. 
+				This interface captures the data fields in an message. Note that not all fields will be used when sending messages of certain types. See <a  href='#supported-messaging-types'>Supported Messaging Types</a> for the list of attributes that must be supported for each type.  
 			</p>
-			<dl title='[NoInterfaceObject] interface SMSOptions' class='idl'>
+			<dl title='[NoInterfaceObject] interface MessageProperties' class='idl'>
 				<dt> attribute sequence&lt;DOMString> to
 				</dt>
 				<dd>
-					The set of phone numbers of the recipients.
-				</dd>				
+					The set of addresses of the recipients. For SMS and MMS these are phone numbers, for email it is email addresses. 				</dd>				
+				<dt> attribute sequence&lt;DOMString> cc
+				</dt>
+				<dd>
+					The set of cc (carbon copy) addresses of the recipients.
+					</dd>				
+				<dt> attribute sequence&lt;DOMString> bcc
+				</dt>
+				<dd>
+					The set of bcc (blind carbon copy) addresses of the recipients. 
+					</dd>				
+				<dt>
+					attribute DOMString subject
+				</dt>
+				<dd>
+					The message subject
+				</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).
+					The message text body
 				</dd>
+				
+				<dt>
+					attribute DOMString from
+				</dt>
+				<dd>
+					The sender the message. 
+				</dd>
+				
+				<dt>
+					attribute DOMString attachments[]
+				</dt>
+				<dd>
+					The list of paths to attachments that will be sent together with message
+				</dd>	
+				
 			</dl>	
-			</section>
-			
+		</section>	
+		
+					
 		<section>
-			<h2><a>OnIncomingSMS</a></h2>
+			<h2><a>OnIncomingMessage</a></h2>
 			<p>
-				This interface defines the method called on new message (SMS) events. 
+				This interface defines the method called on new message events. 
 			</p>
-			<dl title='[Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingSMS' class='idl'>
+			<dl title='[Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingMessage' class='idl'>
 				<dt>
-					void onEvent (in SMS message)
+					void onEvent (in Message message)
 				</dt>
 				<dd>
-					This method is invoked when an SMS arrives. 
+					This method is invoked when an message arrives. 
 				</dd>				
 				<dl class=parameters>
 					<dt>
-						SMS message
+						Message message
 					</dt>
 					<dd>
-						Reference to the incoming SMS. 
+						Reference to the incoming Message. 
 					</dd>
 				</dl>
 			</dl>	
@@ -325,24 +428,10 @@
 			</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>
+      <h2>Scheme based 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. 
       
@@ -365,10 +454,26 @@
       		<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. 
+      	<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. RFC5724 was accepted in January 2010, and implementation of the scheme is therefore limited. However, at least some platforms use a simpler form of SMS URI without the capacity to pre-populate the message body (e.g. iPhone). 
+      	</p>
+      	</section>
+      	<section>
+      	<h3>The mailto URL scheme (RFC2368)</h3>
+      	<p>
+      	RFC2368 defines the well known mailto URL scheme, for that allows presents a way to pass a request to send an email to the specfied receivers with a specified text body.  If the browser can handle the scheme and an external email program is correctly configured, then the user agent typically passes over the URL contents to a email program that handles the editing and sending of the email. There is no requirement that the email 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 implementation is required to correctly translate the text body to suitable encoding.
+      	</p>
+      
+      	<p>
+      	RFC2368 prescribes a number of security measures that the UA must take when handling mailto URLs(i.e. must not pass obviously unsafe headers, must not send without user action, etc).
+      	</p>
+      	
+      	<p>
+      	<i>Comments on relationship between DAP Messaging and mailto</i> The mailto 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. RFC2368 specification does not cover events resulting from arriving emails, nor the manipulation of the email message store, making the creation of a web application based email messaging application difficult. The mailto scheme is commonly supported in many/most platforms. 
       	</p>
       	</section>
       </section>
+
+
      </section>
     
     <section>
@@ -385,6 +490,11 @@
       <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>
+      <h4>Use case 3: New message event</h4>
+      A web page can register to be informed when a new message arrives at a local inbox. There is no need to poll for new messages in this case. 
+      
+      </section>
       </section>
       
       <section>
@@ -399,8 +509,7 @@
         <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>
    
     
@@ -409,10 +518,16 @@
       <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.
       </p>
+      <h3>ToDo</h3>
       <ul>
-        <li>...</li>
+      	<li>Account management</li>
+        <li>Notion of default accounts</li>
+        <li>References to mailto and SMS RFCs</li>
+        <li>Need to o verification of fields in messages (check that addresses are appropriate for type, check that attachment file have correct urls etc)
       </ul>
     </section>
+      
+    </section>
 
     <section class='appendix'>
       <h2>Acknowledgements</h2>

Received on Monday, 22 February 2010 20:51:21 UTC