Messaging API Specification

[23 April 2009]

Revision:
$Rev: 245 $

Abstract

This specification defines an API that provides scripted access to messaging services associated with the hosting device.

Status of this document

Nokia hereby grants to the W3C a perpetual, nonexclusive, royalty-free, world-wide right and license under any Nokia copyrights on this contribution, to copy, publish and distribute the contribution under the W3C document licenses.

Additionally, should the submission be used as a contribution towards a W3C Activity, Nokia grants a right and license of the same scope to any derivative works prepared by the W3C and based on, or incorporating all or part of, the contribution. Nokia further agrees that any derivative works of this contribution prepared by the W3C shall be solely owned by the W3C.

Nokia Corporation agrees to offer W3C members and non-members granting reciprocal terms a non-assignable, non-sublicensable, worldwide and royalty free license to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of any portion of the submission that is subsequently incorporated into a W3C Recommendation. Such license shall extend to all Essential Claims owned or controlled by Nokia Corporation and shall be available as long as the Recommendation is in effect.

Table of contents

Introduction

This section is non-normative.

The Messaging API defines a high-level interface to access messaging service of the device.

The following example code illustrates how to work with a messaging service associated with the hosting device.

Example of instantiating a service object to access the device messaging service.

    // Loads an instance of a messaging interface identified by a service name
    // "device", an interface name "messaging" and an interface version "1" or later. 
    var myMessaging = org.w3c.device.load("device", "messaging", "1");
    

NOTE: the namespace for the service interface loader is tentative.

Example of retrieving a list of messages according to a specified match criteria.

    // A callback function for getList(). Once invoked displays a
    // summary of messages.
    function callback(iterator, status, transactionId) {
        var messageInfo, summary;
        if (status) {
            alert("Error: " + status);
        }
        while (messageInfo = iterator.next())  {
            summary += messageInfo.message.subject + "\n";
        }
        alert(summary);
    }
    
    // Asynchronously retrieves a list of messages from a sender identified
    // by a phone number "1234567890". 
    var transactionId = myMessaging.getList(callback, { senders: ["1234567890"] });
    

Example of sending a new SMS message.

     // A callback function for send() to get a notification once the message
     // has been sent.
     function callback(status, transactionId) {
         if (status) {
             alert("Error sending the message: " + status); 
         } else {
             alert("Message sent successfully.");
         }
     }

     var transactionId = myMessaging.send(callback,
         { type: "sms", to: ["1234567890"], body: "Hello world!" });
     

Example of displaying new incoming messages.

     // A callback function invoked once a new message is received
     // to display the message 
     function callback(messageId, status, transactionId) {
         if (status) {
             alert("Error: " + status);
             // Unregister the callback.
             myMessaging.cancelNotification();
             return;
         }
         var messageInfo = myMessaging.getMessage(messageId);
         alert ("New message: " + messageInfo.message.subject);
         // Set the message status as read.
         myMessaging.setStatus(messageId, 0);
     }
     
      // Registers callback function to receive notifications of incoming messages.
      var transactionId = myMessaging.setNotifier(callback);
      

Scope

This section is non-normative.

This specification is limited to [define scope].

Use-Cases and Requirements

Use-Cases

To be written ...

Requirements

Security and privacy considerations

The API defined in this specification can be used to retrieve messages on the hosting device thus a conforming implementation should ensure no messaging information is made available without the user's informed consent.

Privacy considerations for implementers of Messaging API

A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that privacy information is not revealed without user's informed consent.

Conformance requirements

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].

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 [WebIDL].

API Description

Messaging interface

The Messaging object can be used by scripts to pragmatically access the messaging service of the hosting device.

  interface Messaging {
    void startEditor(in MessageData message);
    
    int getList(in MessageListCallback callback);
    int getList(in MessageListCallback callback, in MatchCriteria matchCriteria);
    int getList(in MessageListCallback callback, in MatchCriteria matchCriteria, in SORT_BY sortKey);
    int getList(in MessageListCallback callback, in MatchCriteria matchCriteria, in SORT_BY sortKey, in SortOrder sortOrder);
    
    int send(in SendCallback callback, in MessageData message);
    int send(in SendCallback callback, in MessageData message, in DOMString messageId);
    
    void setNotifier(in NotifierCallback callback);
    
    void cancelNotifier();
    
    MessageInfo getMessage(in DOMString messageId);
    
    void deleteMessage(in DOMString messageId);
    
    void setStatus(in DOMString messageId, in MESSAGE_STATUS status);
    
    void cancel(in int transactionId);
  };
        
  interface MessageListCallback {
     void handleEvent(in MessageIterator messageIterator, 
                      in int status, 
                      in int transactionId);
  };
  
  interface SendCallback {
     void handleEvent(in int status,
                      in int transactionId);
  };
  
   interface NotifierCallback {
     void handleEvent(in DOMString messageId, 
                      in int status, 
                      in int transactionId);
  };
  

The startEditor() method takes a MessageData object as an argument and launches the device messaging editor with pre-populated message data.

An alternative mechanism for launching a device messaging editor for e.g. desktop user agents must be specified. One option would be to use the mailto URL scheme as a standards compliant fallback mechanism.

The getList() method takes one, two, three or four arguments. When called it must immediately return a unique transactionId. Next it must asynchronously retrieve a MessageIterator object based on a specified MatchCriteria object, sortKey and sortOrder and invoke its associated callback argument with the transactionId, the status and the MessageIterator object as arguments.

If the matchCriteria argument is null or undefined the MessageIterator to all messages must be retrieved and passed to the associated callback function.
If the sortKey argument is null or undefined the default value is the representation of the SORT_BY_DATE as specified in Sort By Constants.
If the sortOrder argument is null or undefined the default value is the representation of the SORT_ASCENDING as specified in Sort Order Constants.

The send() takes two or three arguments. When called it must immediately return a unique transactionId and asynchronously send the message. The MessageData object contains the message to be sent. The messageId argument is used to forward the existing message.

The use of messageId argument in the send() method must be specified.

The setNotifier() method takes a callback argument. When called it must immediately return a unique transactionId. The associated callback function is asynchronously invoked each time a new incoming message is received with transactionId, status and messageId of the incoming message as arguments. If the callback has already been registered the new handler will replace it. Invoking the cancelNotifier() method must stop the notifications.

The dummy transactionId returned by this method should not be used in cancel() method to stop further notifications from the requested channel, instead user must invoke the cancelNotifier() method.

The cancelNotifier() method unregisters the callback function registered with the setNotifier() method and stops incoming message notifications.

The getMessage() method takes a messageId of an existing message and must retrieve associated MessageInfo object synchronously.

The deleteMessage() method takes messageId of an existing message.This method must remove the the associated message from the device messaging store.

The setStatus() method takes two arguments. The method must change the state of an existing message identified by a messageId in the messaging store to the status as specified in Message Status Constants.

The cancel() method takes a unique transactionId of the ongoing asynchronous request and cancels it.

MatchCriteria interface

MatchCriteria objects are regular ECMAScript objects that have the following properties:

  interface MatchCriteria { 
     attribute sequence<DOMString>      type;
     attribute sequence<DOMString>      senders;
     attribute DOMString                subject; 
     attribute DOMTimeStamp             start;
     attribute DOMTimeStamp             end; 
  };
  

All the attributes in MatchCriteria object are optional.

The type attribute represents an array of specified message types to be searched as specified in Message Type Constants. If this is undefined or null then all the message types must be considered.

The senders attribute represents an array of senders to be searched. The search is case-insensitive and must support substring searching. If this is undefined or null then messages from all the senders must be considered.

The substring search algorithm must be specified.

The subject attribute represents the text to be searched in a subject field of a MessageInfo object. The search is case-insensitive and must support substring searching.

The start attribute specifies the start date for the search, that is the lower bound.

The end attribute specifies the end date data for the search, that is the upper bound.

AttachmentData interface

AttachmentData objects are regular ECMAScript objects that have the following properties:

  interface AttachmentData { 
     attribute DOMString       uri; 
  };
  

The uri attribute specifies a path to the attachment file as a Uniform Resource Identifier (URI) conforming to [RFC3986].

MessageData interface

MessageData objects are regular ECMAScript objects that have the following properties:

  interface MessageData { 
     attribute DOMString                type;
     attribute sequence<DOMString>      to;
     attribute DOMString                body;
     attribute DOMString                subject;
     attribute sequence<DOMString>      cc;
     attribute sequence<AttachmentData> attachments;
  };
  

All the attributes except type and to in a MessageData object are optional for send() and startEditor() methods.

The type attribute represents the type of the message. All implementations must support the message types defined in Message Type Constants.

For compliancy with non-mobile User Agents the requirement for supporting mobile-specific message types must be relaxed.

The to attribute represents an array of message recipients' phone numbers.

The body attribute represents the message, that is the actual textual message body.

The subject attribute represents the subject of the message. The attribute is only applicable if the type of the message is mms.

The cc attribute represents an array of secondary message recipients' phone numbers.

The attachments contains an array of AttachmentData objects to be added to the message.

MessageInfo interface

MessageInfo objects are regular ECMAScript objects that have the following properties:

  interface MessageInfo { 
     attribute DOMString        id;
     attribute MessageData      message;
     attribute DOMString        sender;
     attribute DOMTimeStamp     time;
     attribute boolean          unread;
  };
  

The id attribute represents the unique identifier of a message in the device message store.

The message attribute represents the MessageData object.

The sender attribute contains the sender contact phone number of the message.

The time attribute represents the creation date and time of the message.

The unread attribute represents the status of the message. The value is true if the message is unread and false if it has been read, ie. opened.

MessageIterator interface

MessageIterator objects are regular ECMAScript objects that have the following properties:

  interface MessageIterator {
     MessageInfo    next();
     boolean        hasNext();
  };
  

The next() method returns the next MessageInfo object in the list. If the last message information in the list is reached the method will return null.

The hasNext() method returns true if the next MessageInfo object exists, otherwise it returns false.

Exception handling

On error, the APIs throw DeviceException with an informative error code. The DeviceException interface and error constants are defined in Appendix A.

Defined Constants

Message Status Constants

MESSAGE_STATUS must take these constant values of type unsigned short int.

STATUS_READ
value 0 represents a read message.
STATUS_UNREAD
value 1 represents an unread message.

Sort By Constants

SORT_BY must take these constant values of type unsigned short int.

SORT_BY_DATE
value 0 represents message sorting by date.
SORT_BY_SENDER
value 1 represents message sorting by sender.

Sort Order Constants

SORT_ORDER must take these constant values of type unsigned short int.

SORT_ASCENDING
The value of 0 represents ascending sort order.
SORT_DESCENDING
The value of 1 represents descending sort order.

Message Type Constants

The type attribute in MessageData and MatchCriteria must take these case insensitive constant values of type DOMString.

sms
Represents an SMS message.
mms
Represents an MMS messsage.

References

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels.
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax.
[WebIDL]
Web IDL.