Samsung Electronics logo

Samsung Web API: Messaging


Introduction

This API provides interfaces and methods for managing SMS, MMS, and Email messages.

The messaging API provides access to these capabilities:

  • Sending messages through different technologies: SMS, MMS, and Email messages.
  • Retrieving available message services.
  • Searching for messages.
  • Managing messages: update, delete, and add.
  • Subscribing to receive notifications of message storage modifications.
  • Fetching conversations and subscribing to conversation updates.

For more information on the Messaging features, see Messaging Guide.


Table of Contents


Summary of Interfaces and Methods

Interface Method
MessageManagerObject
Message
MessageInit
MessageBody
MessageAttachment
Messaging void getMessageServices(MessageServiceTag messageServiceType, MessageServiceArraySuccessCallback successCallback, ErrorCallback? errorCallback)
MessageServiceArraySuccessCallback void onsuccess(MessageService[] services)
MessageService void sendMessage(Message message, MessageRecipientsCallback successCallback, ErrorCallback? errorCallback)
void loadMessageBody(Message message, MessageBodySuccessCallback successCallback, ErrorCallback? errorCallback)
void loadMessageAttachment(MessageAttachment attachment, MessageAttachmentSuccessCallback successCallback, ErrorCallback? errorCallback)
long sync(SuccessCallback? successCallback, ErrorCallback? errorCallback, unsigned long? limit)
long syncFolder(MessageFolder folder, SuccessCallback? successCallback, ErrorCallback? errorCallback, unsigned long? limit)
void stopSync(long opId)
MessageRecipientsCallback void onsuccess(DOMString[] recipients)
MessageBodySuccessCallback void onsuccess(Message message)
MessageAttachmentSuccessCallback void onsuccess(MessageAttachment attachment)
MessageStorage void addDraftMessage(Message message, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void findMessages(AbstractFilter filter, MessageArraySuccessCallback successCallback, ErrorCallback? errorCallback, SortMode? sort, unsigned long? limit, unsigned long? offset)
void removeMessages(Message[] messages, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void updateMessages(Message[] messages, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void findConversations(AbstractFilter filter, MessageConversationArraySuccessCallback successCallback, ErrorCallback? errorCallback, SortMode? sort, unsigned long? limit, unsigned long? offset)
void removeConversations(MessageConversation[] conversations, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void findFolders(AbstractFilter filter, MessageFolderArraySuccessCallback successCallback, ErrorCallback? errorCallback)
long addMessagesChangeListener(MessagesChangeCallback messagesChangeCallback, AbstractFilter? filter)
long addConversationsChangeListener(MessageConversationsChangeCallback conversationsChangeCallback, AbstractFilter? filter)
long addFoldersChangeListener(MessageFoldersChangeCallback foldersChangeCallback, AbstractFilter? filter)
void removeChangeListener(long watchId)
MessageArraySuccessCallback void onsuccess(Message[] messages)
MessageConversationArraySuccessCallback void onsuccess(MessageConversation[] conversations)
MessageFolderArraySuccessCallback void onsuccess(MessageFolder[] folders)
MessagesChangeCallback void messagesadded(Message[] addedMessages)
void messagesupdated(Message[] updatedMessages)
void messagesremoved(Message[] removedMessages)
MessageConversationsChangeCallback void conversationsadded(MessageConversation[] addedConversations)
void conversationsupdated(MessageConversation[] updatedConversations)
void conversationsremoved(MessageConversation[] removedConversations)
MessageFoldersChangeCallback void foldersadded(MessageFolder[] addedFolders)
void foldersupdated(MessageFolder[] updatedFolders)
void foldersremoved(MessageFolder[] removedFolders)
MessageConversation
MessageFolder

1. Type Definitions

1.1. MessageServiceTag

The supported Messaging service tags. The following values are supported in this release:

  enum MessageServiceTag {"messaging.sms", "messaging.mms", "messaging.email" };
  • messaging.sms, for SMS services
  • messaging.mms, for MMS services
  • messaging.email, for email services

1.2. MessageId

The Message identifier.

  typedef DOMString MessageId;

1.3. MessageAttachmentId

The MessageAttachment identifier within a message.

  typedef DOMString MessageAttachmentId;

1.4. MessageConvId

The MessageConversation identifier.

  typedef DOMString MessageConvId;

1.5. MessageFolderId

The identifier of an email folder .

  typedef DOMString MessageFolderId;

2. Interfaces

2.1. MessageManagerObject

Defines what is instantiated in the webapis object.

  [NoInterfaceObject] interface MessageManagerObject {
    readonly attribute Messaging messaging;
  };
  WebAPIs implements MessageManagerObject;

There is a webapis.messaging object that allows access to the messaging API.

2.2. Message

Defines the content and attributes of a message.

  [Constructor(MessageServiceTag type, optional MessageInit? messageInitDict)]
  interface Message {

    readonly attribute MessageId? id;

    readonly attribute MessageConvId? conversationId;

    readonly attribute MessageFolderId? folderId;

    readonly attribute MessageServiceTag type;

    readonly attribute Date? timestamp;

    readonly attribute DOMString? from;

    attribute DOMString[] to setraises(WebAPIException);

    attribute DOMString[] cc setraises(WebAPIException);

    attribute DOMString[] bcc setraises(WebAPIException);

    attribute MessageBody body setraises(WebAPIException);

    attribute boolean isRead setraises(WebAPIException);

    readonly attribute boolean hasAttachment;

    attribute boolean isHighPriority setraises(WebAPIException);

    attribute DOMString subject setraises(WebAPIException);

    readonly attribute MessageId? inResponseTo setraises(WebAPIException);

    readonly attribute DOMString messageStatus;

    attribute MessageAttachment[] attachments setraises(WebAPIException);
  };

This interface allows a web application to define the set of properties linked to a message.

It also allows an application to retrieve the content of a message through MessageStorage methods. In these cases, the implementation can return, in some situations, only the meta-information of a message without the loaded body. In such situations, the method MessageService.loadMessageBody() should be used.

Code example
 // Define the success callback.
 var messageSentCallback = function(recipients) {
   console.log("Message sent successfully to " + recipients.length + " recipients.");
 }

 // Define the error callback.
 function errorCallback(err) {
   console.log(err.name + " error: " + err.message);
 }
 
 function serviceListCB(services) {
   if (services.length > 0) {
      var msg = new webapis.Message("messaging.sms", {plainBody: "WebAPIs first SMS message."});
      services[0].sendMessage(msg, messageSentCallback, errorCallback);
   }
 }

 webapis.messaging.getMessageServices("messaging.sms",
                                    serviceListCB,
                                    errorCallback);
 

ATTRIBUTES

readonly MessageId? id

The message identifier.

The ID is locally unique and persistent property, assigned by the device or the Web runtime (WRT). For new messages created using the Message constructor, the ID is assigned on the first occasion when a message is processed by the underlying platform, such as a call to MessageService.send(). Before the ID is assigned, it is set to null.

By default, this attribute is set to null.

This attribute is read-only.

readonly MessageConvId? conversationId

The identifier of the conversation to which the message belongs.

By default, this attribute is set to null.

This attribute is read-only.

readonly MessageFolderId? folderId

The identifier of the folder to which the message belongs.

By default, this attribute is set to null.

For SMS and MMS, folderId can be one of these values:

  • INBOX = 1,
  • OUTBOX = 2,
  • DRAFTS = 3,
  • SENTBOX = 4
This attribute is read-only.

readonly MessageServiceTag type

The type of a given message.

This attribute is read-only.

readonly Date? timestamp

The timestamp of a message.

For a received message, the timestamps indicates the time at which a message is received. For a sent message, the timestamp indicates the time at which a message is sent. By default, this attribute is set to null.

This attribute is read-only.

readonly DOMString? from

The source address (or source phone number) of a message.

This property is set up by the device or the web runtime environment. By default, this attribute is set to null.

This attribute is read-only.

DOMString[] to

The destination of a message.

DOMString[] cc

The carbon copy address of a message.

This property is used only for email messages.

DOMString[] bcc

The blind carbon copy (bcc) address of a message.

This property is used only with email messages.

MessageBody body

An attribute to store the body of a message.

boolean isRead

An attribute to indicate the read state for a message.

This property is set to true if the message has been read. Else it is set to false.

readonly boolean hasAttachment

An attribute to indicate whether an attachment(s) exists or not.

It is set to true if a message has one or more attachments.

This property is used only with email and MMS messages.

This attribute is read-only.

boolean isHighPriority

An attribute to indicate the priority of a message.

It is set to true if the message has a high priority. Else it is set to false, if the message has a normal or low priority.

This property is used only with email messages.

DOMString subject

An attribute to store the subject of a message.

This property is used only with email and MMS messages.

readonly MessageId? inResponseTo

The identifier of the original message.

If the message was replied to or forwarded, this property contains the ID of the original message, otherwise it is set to null.

This attribute is read-only.

readonly DOMString messageStatus

The status of a given message.

It can be one of these values:

  • SENT
  • SENDING
  • FAILED
  • DRAFT

If the status of the current message does not correspond to any item from the list, an empty value is returned.

This attribute is read-only.

MessageAttachment[] attachments

The list of the message attachments.

This array is empty if the message does not have attachments or the message body is not loaded and the attachment info is inaccessible (in this case, the hasAttachment attribute is checked).

Code example
 // Define the success callback.
 function serviceListCB(services) {
     if (services.length > 0) {
         var msg = new webapis.Message("messaging.email");    
         msg.attachments = [new webapis.MessageAttachment("images/myimage.png", "image/png"),
                         new webapis.MessageAttachment("docs/mydoc.pdf", "text/pdf")];
     }
 }

 webapis.messaging.getMessageServices("messaging.email", serviceListCB);

     

2.3. MessageInit

Provides specific message attributes upon message creation.

  dictionary MessageInit
  {

    DOMString subject;

    DOMString[] to;

    DOMString[] cc;

    DOMString[] bcc;

    DOMString plainBody;

    DOMString htmlBody;

    boolean isHighPriority;
  };

This interface is used to input parameters when messages are created using the Message constructor.

All the attributes are optional and are undefined by default, unless otherwise stated in the parameter description.

Dictionary members

DOMString subject

The subject of a message.

This property is used only with email and MMS messages.

DOMString[] to

The destination addresses (or phone numbers) of a message.

DOMString[] cc

The carbon copy addresses of a message.

This property is used only with email messages.

DOMString[] bcc

The blind carbon copy addresses of a message.

This property is used only with email messages.

DOMString plainBody

The plain text representation of a message body.

DOMString htmlBody

The HTML representation of a message body.

This property is used only with email messages.

boolean isHighPriority

The priority of a message.

This property is set to true if the message has a high priority. Else it is set to false if the message has a normal or low priority.

This property is used only with email messages.

2.4. MessageBody

This interface describes a message body.

  [NoInterfaceObject] interface MessageBody {

    readonly attribute MessageId messageId;

    readonly attribute boolean loaded;

    attribute DOMString plainBody setraises(WebAPIException);

    attribute DOMString htmlBody setraises(WebAPIException);

    attribute MessageAttachment[] inlineAttachments setraises(WebAPIException);
  };

Message body is comprised of a plain text, an HTML, and inline attachments.

ATTRIBUTES

readonly MessageId messageId

The ID of a parent message.

It holds the ID of the message containing this body.

This attribute is read-only.

readonly boolean loaded

An attribute to indicate whether the message body has been loaded or not.

It is set to true if the message body is loaded, else it is set to false if the object is not loaded. The default value is false.

This attribute is read-only.

DOMString plainBody

The plain text representation of a message body.

DOMString htmlBody

The HTML representation of a message body.

This attribute holds an empty string if the message does not have any HTML body content. This property is used only with email messages.

MessageAttachment[] inlineAttachments

The list of the inline attachments.

This array is empty, if the message does not have inline attachment or the message body is not loaded and attachments info is inaccessible (in this case the loaded attribute is checked).

To indicate where to show an inline attachment within the HTML body, a link of the following format should be provided: "<img src="The file name of a inline attachment">" This property is used only with email messages.

Code example
 // Define the success callback.
 function serviceListCB(services) {
     if (services.length > 0) {
         var msg = new webapis.Message("messaging.email");
         msg.body.htmlBody = "...<img src="images/myimage.png">...";     
         msg.body.inlineAttachments = [new webapis.MessageAttachment("images/myimage.png")];
     }
 }

 webapis.messaging.getMessageServices("messaging.email", serviceListCB);

 

2.5. MessageAttachment

This interface defines the content and attributes of a message attachment.

  [Constructor(DOMString filePath, optional DOMString? mimeType)]
  interface MessageAttachment {
    
    readonly attribute MessageAttachmentId? id;
    
    readonly attribute MessageId? messageId;
    
    readonly attribute DOMString? mimeType;
    
    readonly attribute DOMString? filePath;
  };

ATTRIBUTES

readonly MessageAttachmentId? id

The ID of an attachment.

It holds the identifier of the attachment within its parent message.

By default, this attribute is set to null.

This attribute is read-only.

readonly MessageId? messageId

The ID of a parent message.

By default, this attribute is set to null.

This attribute is read-only.

readonly DOMString? mimeType

The attachment MIME type.

It describes the MIME type of an attachment, for example; "text/html".

By default, this attribute is set to null.

This attribute is read-only.

readonly DOMString? filePath

The location path to a loaded attachment file.

It holds the location path to a loaded attachment file, appropriate for the Filesystem API. It is set to null if the attachment is not loaded from the remote servaer.

This attribute is read-only.

2.6. Messaging

This interface retrieves messaging services.

  [NoInterfaceObject] interface Messaging {

    void getMessageServices(MessageServiceTag messageServiceType,
                            MessageServiceArraySuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

Fetches all existing messaging services by type or a messaging service of a given type for concrete account.

Code example
 // Define the success callback.
 function serviceListCB(services) {
   if (services.length > 0) {
     var msg = new webapis.Message("messaging.sms");
   }
 }

 // Define error callback.
 function errorCallback(error) {
   console.log("Cannot get messaging service " + error.message);
 }

 webapis.messaging.getMessageServices("messaging.sms", serviceListCB,
                                     errorCallback);
 

METHODS

getMessageServices

Gets the messaging service of a given type for a given account, or all existing services supporting the given type, if serviceId is not given.

Signature
void getMessageServices(MessageServiceTag messageServiceType, MessageServiceArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contain an invalid value, the encoding is not valid or onsuccess is null. Please note that to allow developers to ignore errors, errorCallback accepts null as a valid value.
  • UnknownError - In any other error case.
Parameters
  • messageServiceType
    • Optional: No.
    • Nullable: No.
    • Type: MessageServiceTag.
    • Description: Type of the services to be retrieved.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageServiceArraySuccessCallback.
    • Description: Invoked if the services are successfully retrieved.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Function called when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 // Define the error callback.
 function errorCallback(error) {
   console.log("Cannot get messaging service " + error.message);
 }

 // Define the success callback.
 function serviceListCB(services) {
   console.log("Found " + services.length + "email services");
 }

 webapis.messaging.getMessageServices("messaging.email", serviceListCB,
                                      errorCallback);
 

2.7. MessageServiceArraySuccessCallback

Defines callback(s) for retrieving message services.

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageServiceArraySuccessCallback {

    void onsuccess(MessageService[] services);

  };

METHODS

onsuccess

Called when finding message services is successful.

Signature
void onsuccess(MessageService[] services);
Parameters
  • services
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of available MessageService objects on the device.

2.8. MessageService

This interface allows a web application to manipulate and send messages and supports the message creating, sending, and fetching capabilities.

  [NoInterfaceObject] interface MessageService {

    readonly attribute DOMString id;

    readonly attribute MessageServiceTag type;

    readonly attribute DOMString name;
                    
    void sendMessage(Message message,
                     optional MessageRecipientsCallback successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void loadMessageBody(Message message,
                         MessageBodySuccessCallback successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);

    void loadMessageAttachment(MessageAttachment attachment,
                               MessageAttachmentSuccessCallback successCallback,
                               optional ErrorCallback? errorCallback) raises(WebAPIException);

    long sync(optional SuccessCallback? successCallback,
              optional ErrorCallback? errorCallback,
              optional unsigned long? limit) raises(WebAPIException);

    long syncFolder(MessageFolder folder,
                    optional SuccessCallback? successCallback,
                    optional ErrorCallback? errorCallback,
                    optional unsigned long? limit) raises(WebAPIException);

    void stopSync(long opId) raises(WebAPIException);

    readonly attribute MessageStorage messageStorage getraises(WebAPIException);
  };

Messages created through this API are not persistent in device memory until the implementation attempts to send the message using the sendMessage() method. On performing the sendMessage() method, the message is available in the relevant folder (such as sent and drafts), depending on the result of the operation.

The interface allows fetching of messages for all folders belonging to one account, with synchronizable flag set, using the sync() method, or for a given folder using the syncFolder() method.

The interface allows fetching of the message body for a given message using loadMessageBody() method.

Code example
 // Define the success callback.
 function messageSent(recipients) {
   console.log("The SMS has been sent");
 }

 // Define the error callback.
 function messageFailed(error) {
   console.log("The SMS could not be sent " + error.message);
 }

 // Define service error callback.
 function serviceErrorCB(error) {
   console.log("Cannot get messaging service " + error.message);
 }

 // Define the success callback.
 function serviceListCB(services) {
   if (services.length > 0) {
     // SMS sending example
     var msg = new webapis.Message("messaging.sms", {plainBody:"I will arrive in 10 minutes.",
                                  to:["+34666666666"]});
     // Send request
     services[0].sendMessage(msg, messageSent, messageFailed);
   }
 }

 webapis.messaging.getMessageServices("messaging.sms",
                                    serviceListCB,
                                    serviceErrorCB);
 

ATTRIBUTES

readonly DOMString id

The unique identifier of this Messaging service.

This attribute is read-only.

readonly MessageServiceTag type

The tag supported by this messaging service.

This attribute is read-only.

readonly DOMString name

The messaging service name taken from the messaging service

This attribute is read-only.

readonly MessageStorage messageStorage

An attribute to access MessageStorage for this messaging service.

If the backend does not support MessageStorage for this messaging service, a WebAPIException is raised with error type NotSupportedError.

This attribute is read-only.

METHODS

sendMessage

Sends a specified message.

Signature
void sendMessage(Message message, optional MessageRecipientsCallback successCallback, optional ErrorCallback? errorCallback);

For messaging technologies in which the message is sent individually to every recipient(such as SMS), individual notification must be supported as follows:

For every individual recipient in the destination list, if the message cannot be sent to that recipient, the onerror() method of the errorCallback argument must be invoked with the corresponding error type as input parameter. These error types may be passed, depending on the error conditions:

  • NetworkError - If the network connection is not accessible.
  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.

The error message contains the name of the recipient who has failed to receive the sent message.

When the operation is fully completed (that is, the implementation has the result of the send operation for all recipients), the onsuccess() method of the successCallback will be invoked with an array of recipients who received the sent message, as input parameter.

Parameters
  • message
    • Optional: No.
    • Nullable: No.
    • Type: Message.
    • Description: The message to be sent.
  • successCallback
    • Optional: Yes.
    • Nullable: No.
    • Type: MessageRecipientsCallback.
    • Description: To be invoked if the message is successfully sent.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked if the sending request fails.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 // Define the success callback
 function messageSent(recipients) {
   for (var i = 0; i < recipients.length; i++) {
     console.log("The SMS has been sent to " + recipients[i]);
   }
 }

 // Define the error callback.
 function messageFailed(error) {
   console.log("The SMS could not be sent " + error.message);
 }

 // Define the success callback.
 function serviceListCB(services) {
   if (services.length > 0) {
     // SMS sending example
     var msg = new webapis.Message("messaging.sms", {plainBody: "I will arrive in 10 minutes.",
                                 to: ["+34666666666", "+34888888888"]);
     // Send request
     services[0].sendMessage(msg, messageSent, messageFailed);
   }
 }
 webapis.messaging.getMessageServices("messaging.sms", serviceListCB);
 

loadMessageBody

Loads the body for a specified message.

Signature
void loadMessageBody(Message message, MessageBodySuccessCallback successCallback, optional ErrorCallback? errorCallback);

It is the back end's responsibility to detect which MIME parts of the message are related to the message body and should be loaded. If the message body is already loaded, the onsuccess() method of the successCallback will be invoked immediately.

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • message
    • Optional: No.
    • Nullable: No.
    • Type: Message.
    • Description: Message with the body to be loaded.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageBodySuccessCallback.
    • Description: Function to be invoked if the message body is successfully loaded.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Function to be invoked if the loading request fails.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 // Define the success body loaded callback.
 function successCallback(message) {
   console.log ("body for message: " + message.subject + "from: " + message.from + "loaded.");
 }
 // Define error callback.
 function errorCallback(error) {
   console.log("Cannot load message body" + error.message);
 }

 function messageQueryCallback(messages) {
   for (var i = 0; i < messages.length; i++) {
     var message = messages[i];
     if (!message.body.loaded) {
        service.loadMessageBody(message, successCallback, errorCallback);
     }
   }
 }

 service.messageStorage.findMessages(new webapis.AttributeFilter("type", "EXACTLY", "messaging.email"), messageQueryCallback),
 

loadMessageAttachment

Loads a specified message attachment.

Signature
void loadMessageAttachment(MessageAttachment attachment, MessageAttachmentSuccessCallback successCallback, optional ErrorCallback? errorCallback);

This method is used only for email services. If the message attachment is already loaded, the onsuccess() method of the successCallback is invoked immediately.

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • attachment
    • Optional: No.
    • Nullable: No.
    • Type: MessageAttachment.
    • Description: Message attachment to be loaded.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageAttachmentSuccessCallback.
    • Description: Function to be invoked if the message attachment is successfully loaded.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: Function to be invoked if the loading request fails.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 // Define success body loaded callback
 function successCallback(attachment) {
   console.log("attachment" + attachment.id + "is loaded to:" + attachment.filePath);
 }
 // Define error callback
 function errorCallback(error) {
   console.log("Cannot load message attachment" + error.message);
 }

 function messagesFoundCB(messages) {
   for (var i = 0; i < messages.length; i++) {
     var message = messages[i];
     if (!message.attachments[0].loaded) {
        service.loadMessageAttachment(message.attachments[0], successCallback, errorCallback);
     }
   }
 }

 service.messageStorage.findMessages(new webapis.AttributeFilter("hasAttachment", "EXACTLY", true), messagesFoundCB);
 

sync

Synchronizes the service content with an external mail server.

Signature
long sync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional unsigned long? limit);

This method is used only for email services. This method performs the same actions as syncFolder for every folder with Synchronizable flag set within the current Messaging service.

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • AbortError - If the operation has been stopped.
  • UnknownError - If any other error occurs.
Parameters
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: To be invoked if all the actions are completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: To be invoked if the request fails.
  • limit
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: The maximum amount of messages retrieved within each folder.
Return value
long Identifier which can be used to stop this service operation.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 // Define the success callback.
 function serviceSynced() {
   console.log("New messages are fetched!");
 }

 // Define the success callback.
 function servicesListSuccessCB(services) {
   services[0].sync(serviceSynced, null, 30);
   // Subscribe to MessageStorage notification
 }
 webapis.messaging.getMessageServices("messaging.email", servicesListSuccessCB);
 

syncFolder

Synchronizes the folder content with an external mail server.

Signature
long syncFolder(MessageFolder folder, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional unsigned long? limit);

This method is used only for email services. This method performs the following actions:

  • Exports local changes within a given folder from device to server.
  • Retrieves the list of available messages from within the given folder.

Messages that are retrieved from a given folder, even if synchronizable flag for this folder is not set. The backend is responsible in deciding which data is retrieved for every message. It can be:

  • message header details
  • whole message body

The limit of latest messages for the given folder must be retrieved and put into MessageStorage. If the limit is not set, the entire folder must be retrieved.

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • AbortError - If the operation is stopped.
  • UnknownError - If any other error occurs.
Parameters
  • folder
    • Optional: No.
    • Nullable: No.
    • Type: MessageFolder.
    • Description: The folder to be synchronized.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method to be invoked when all actions are completed successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to be invoked when the request fails.
  • limit
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: The maximum amount of messages retrieved within a given folder.
Return value
long The identifier which can be used to stop this service operation.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var emailService; // Assume email service is initialized
  // Define the error callback.
 function errorCallback(err) {
   console.log(err.name + " error: " + err.message);
 }
 function serviceCallback(services) {
   emailService = services[0];
   var filter = new webapis.AttributeFilter("serviceId", "EXACTLY", emailService.id);

   emailService.messageStorage.findFolders(filter, folderQueryCallback);
 }
  
 // Define the success callback.
 function folderSynced() {
   console.log("New messages are fetched!");
 }
 function folderQueryCallback(folders) {
   console.log(folders.length + " folders(s) found!");
   for (var i = 0; i < folders.length; i++) {
     emailService.syncFolder (folders[i], folderSynced, null, 30);
   }
 }
 
 webapis.messaging.getMessageServices("messaging.email", serviceCallback, errorCallback);
 

stopSync

Stops sync() and syncFoler() operation.

Signature
void stopSync(long opId);

If the operationId argument is valid and corresponds to a service operation already in progress, the operation must be stopped and its error callback must be invoked with error type AbortError.

If the operationId argument is not valid or does not correspond to a valid service operation, the method will return without any further action.

Parameters
  • opId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: Service operation identifier.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type InvalidValuesError, If any of the input parameters contains an invalid value..

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

2.9. MessageRecipientsCallback

This interface specifies the methods to be called for the sendMessage() operation.

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageRecipientsCallback {

    void onsuccess(DOMString[] recipients);

   };

METHODS

onsuccess

Called when the message sending is finished.

Signature
void onsuccess(DOMString[] recipients);
Parameters
  • recipients
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: The recipients of the message.

2.10. MessageBodySuccessCallback

This interface specifies a success callback function that takes a message as the input argument. It is used in the loadMessageBody() asynchronous operation.

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageBodySuccessCallback {

     void onsuccess(Message message);
  };

METHODS

onsuccess

Called when the asynchronous query completes successfully.

Signature
void onsuccess(Message message);
Parameters
  • message
    • Optional: No.
    • Nullable: No.
    • Type: Message.
    • Description: The Message containing the loaded body.

2.11. MessageAttachmentSuccessCallback

This callback interface specifies a success callback function that takes the loaded attachment as the input argument.

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageAttachmentSuccessCallback {

     void onsuccess(MessageAttachment attachment);
   };

It is used in the loadMessageAttachment() asynchronous operation.

METHODS

onsuccess

Called when the asynchronous query completes successfully.

Signature
void onsuccess(MessageAttachment attachment);
Parameters
  • attachment
    • Optional: No.
    • Nullable: No.
    • Type: MessageAttachment.
    • Description: The loaded attachment.

2.12. MessageStorage

This interface allows management capabilities using a web application to query, update, and delete messages, and subscribe to MessageStorage changes. In addition to simple message queries, the MessageStorage interface provides functionality to find conversations and folders.

  [NoInterfaceObject] interface MessageStorage {

    void addDraftMessage(Message message,
                         optional SuccessCallback? successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);

    void findMessages(AbstractFilter filter,
                      MessageArraySuccessCallback successCallback,
                      optional ErrorCallback? errorCallback,
                      optional SortMode? sort,
                      optional unsigned long? limit,
                      optional unsigned long? offset) raises(WebAPIException);

    void removeMessages(Message[] messages,
                        optional SuccessCallback? successCallback,
                        optional ErrorCallback? errorCallback) raises(WebAPIException);

    void updateMessages(Message[] messages,
                        optional SuccessCallback? successCallback,
                        optional ErrorCallback? errorCallback) raises(WebAPIException);

    void findConversations(AbstractFilter filter,
                           MessageConversationArraySuccessCallback successCallback,
                           optional ErrorCallback? errorCallback,
                           optional SortMode? sort,
                           optional unsigned long? limit,
                           optional unsigned long? offset) raises(WebAPIException);

    void removeConversations(MessageConversation[] conversations,
                             optional SuccessCallback? successCallback,
                             optional ErrorCallback? errorCallback) raises(WebAPIException);


    void findFolders(AbstractFilter filter,
                     MessageFolderArraySuccessCallback successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    long addMessagesChangeListener(MessagesChangeCallback messagesChangeCallback,
                                   optional AbstractFilter? filter) raises(WebAPIException);

    long addConversationsChangeListener(MessageConversationsChangeCallback conversationsChangeCallback,
                                        optional AbstractFilter? filter) raises(WebAPIException);

    long addFoldersChangeListener(MessageFoldersChangeCallback foldersChangeCallback,
                                  optional AbstractFilter? filter) raises(WebAPIException);

    void removeChangeListener(long watchId) raises(WebAPIException);
  };

The conversation object represents a group of messages combined by the set of message fields. Email conversations are grouped by subject, while chat messages are grouped by sender and recipient fields.

METHODS

addDraftMessage

Adds a draft message to MessageStorage and these messages are stored in the Drafts folder.

Signature
void addDraftMessage(Message message, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The errorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contain an invalid value.
  • UnknownError: In any other error case.
Parameters
  • message
    • Optional: No.
    • Nullable: No.
    • Type: Message.
    • Description: The draft message to add to the storage.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method called when draft messages successfully added.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method called when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter or if the method is invoked for an incoming message.

Code example
 // Define success callback
 function successCallback() {
   console.log("Draft message added");
 }

 // Define error callback
 function errorCallback(error) {
   console.log("Cannot add draft message " + error.message);
 }

 // Define service query success callback.
 function serviceListCB(services) {
   if (services.length > 0) {
     var msg = new webapis.Message("messaging.sms", {plainBody: "WebAPIs draft SMS message."});
     services[0].messageStorage.addDraftMessage(msg,
                                                successCallback,
                                                errorCallback);
   }
 }
 webapis.messaging.getMessageServices("messaging.sms", serviceListCB);
 

findMessages

Queries messages from MessageStorage.

Signature
void findMessages(AbstractFilter filter, MessageArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional SortMode? sort, optional unsigned long? limit, optional unsigned long? offset);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • filter
    • Optional: No.
    • Nullable: No.
    • Type: AbstractFilter.
    • Description: The criteria to be used when filtering.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageArraySuccessCallback.
    • Description: The method called when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method called when an error occurs.
  • sort
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SortMode.
    • Description: The sorting mode for the query.
  • limit
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: The maximum limit the query result is set to as specified by the parameter (It is the same meaning as SQL LIMIT). If 0, there is no limit set.
  • offset
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: The offset in the result set, from where the results are listed (It is the same semantics as SQL OFFSET).
      The number of results listed is maximum the specified limit parameter. Defaults to 0, meaning no offset.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 function messageArrayCB(messages) {
   console.log(messages.length + " message(s) fetched!");
   for (var i = 0; i < messages.length; i++) {
     console.log(i + ". message from " + messages[i].from);
   }
 }

 // Define error callback
 function errorCallback(error) {
   console.log("Cannot query messages" + error.message);
 }

 var filter = new webapis.AttributeFilter("from", "CONTAINS", "me");
 messageStorage.findMessages(filter, messageArrayCB, errorCallback);
 

removeMessages

Removes messages from MessageStorage.

Signature
void removeMessages(Message[] messages, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contain an invalid value
  • UnknownError - If any other error occurs.
Parameters
  • messages
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of messages to delete.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method called when messages are successfully deleted.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method called when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 // Define success callback
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 function successCallback() {
   console.log("Messages were deleted");
 }

 // Define error callback
 function errorCallback(error) {
   console.log("Cannot delete messages " + error.message);
 }

 function messageArrayCB(messages) {
   if (messages.length > 0) {
     messageStorage.removeMessages(messages, successCallback, errorCallback);
   } else {
     console.log("No messages found");
   }
 }

 var filter = new webapis.AttributeFilter("from", "CONTAINS", "me");
 messageStorage.findMessages(filter, messageArrayCB);
 

updateMessages

Updates messages in MessageStorage.

Signature
void updateMessages(Message[] messages, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The backend must check whether the required updates can be applied and invoke the errorCallback method, if they cannot be checked. Depending on the backend synchronization settings, the local changes in MessageStorage can be rewritten as a result of invoking the sync() or syncFolder() methods of the related message service.

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • messages
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array to update
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method called when messages are successfully updated.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method called when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 

 // Define success callback
 function successCallback() {
   console.log("Messages were updated");
 }

 // Define error callback
 function errorCallback(error) {
   console.log("Cannot update messages " + error.message);
 }

 function messageArrayCB(messages) {
   if (messages.length > 0) {
     messages[0].isRead = true;
     messageStorage.updateMessages([messages[0]], successCallback, errorCallback);
   } else {
     console.log("No messages found");
   }
 }

 var filter = new webapis.AttributeFilter('isRead', 'EXACTLY', false);
 messageStorage.findMessages(filter, messageArrayCB);

 

findConversations

Finds conversations from MessageStorage.

Signature
void findConversations(AbstractFilter filter, MessageConversationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional SortMode? sort, optional unsigned long? limit, optional unsigned long? offset);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • filter
    • Optional: No.
    • Nullable: No.
    • Type: AbstractFilter.
    • Description: The criteria to be used when filtering.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageConversationArraySuccessCallback.
    • Description: The method called when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method called when an error occurs.
  • sort
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SortMode.
    • Description: The sorting rules for the query.
  • limit
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: The maximum limit the query result is set to as specified by the parameter (It is the same meaning as SQL LIMIT). If set to 0, there is no limit set.
  • offset
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: The offset in the result set, from where the results are listed (It is the same semantics as SQL OFFSET).
      The number of results listed is maximum the specified limit parameter. Defaults to 0, meaning no offset.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 function conversationsArrayCB(conversations) {
   console.log(conversations.length + " conversation(s) found!");
   for (var i = 0; i < conversations.length; i++) {
     console.log(i + ". conversation preview " + conversations[i].preview);
   }
 }

 // Define error callback.
 function errorCallback(error) {
  console.log("Cannot query conversations" + error.message);
 }

 var filter = new webapis.AttributeFilter('from', 'CONTAINS', 'John');
 messageStorage.findConversations(filter, conversationsArrayCB, errorCallback);
 

removeConversations

Removes conversations from MessageStorage.

Signature
void removeConversations(MessageConversation[] conversations, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • conversations
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of conversations to delete.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: The method called when conversations are successfully deleted.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method called when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 // Define success callback.
 function successCallback() {
   console.log("Conversations deleted");
 }

 // Define error callback.
 function errorCallback(error) {
   console.log("Cannot delete conversations " + error.message);
 }

 function conversationsArrayCB(conversations) {
   if (conversations.length > 0) {
     messageStorage.removeConversations(conversations, successCallback,
                                                       errorCallback);
   } else {
     console.log("No conversations found");
   }
   console.log("Deleted " + conversations.length + " conversation(s)");
 }

 // Define error callback.
 function queryErrorCB(error) {
   console.log("Cannot query conversations" + error.message);
 }

 var filter = new webapis.AttributeFilter('from', 'CONTAINS', 'John');
 messageStorage.findConversations(filter, conversationsArrayCB,
                                          queryErrorCB);
 

findFolders

Queries folders from MessageStorage.

Signature
void findFolders(AbstractFilter filter, MessageFolderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

The errorCallback is launched with these error types:

  • InvalidValuesError: If any of the input parameters contains an invalid value.
  • UnknownError: In any other error case.
Parameters
  • filter
    • Optional: No.
    • Nullable: No.
    • Type: AbstractFilter.
    • Description: The criteria used when filtering.
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageFolderArraySuccessCallback.
    • Description: The method called when the invocation ends successfully.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method called when an error occurs.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 function folderArrayCB(folders) {
   console.log(folders.length + " folders(s) found!");
   for (var i = 0; i < folders.length; i++) {
     console.log(i + ", folder: " + folders[i].name);
   }
 }
 var filter = new webapis.AttributeFilter("serviceId", "EXACTLY", service.id);
 messageStorage.findFolders(filter, folderArrayCB);
 

addMessagesChangeListener

Adds a listener to subscribe to notification for MessageStorage changes.

Signature
long addMessagesChangeListener(MessagesChangeCallback messagesChangeCallback, optional AbstractFilter? filter);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • messagesChangeCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessagesChangeCallback.
    • Description: Callback that is called when the MessageStorage is changed.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: The criteria to be used when filtering.
Return value
long The subscription identifier.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 var messageChangeCallback = {
       messagesupdated: function(messages) {
         console.log(messages.length + " message(s) updated");},
       messagesadded: function(messages) {
         console.log(messages.length + " message(s) added");},
       messagesremoved: function(messages) {
         console.log(messages.length + " message(s) removed");}
 };

 messageStorage.addMessagesChangeListener(messageChangeCallback);
 

addConversationsChangeListener

Adds a listener to subscribe to notifications for MessageConversation changes.

Signature
long addConversationsChangeListener(MessageConversationsChangeCallback conversationsChangeCallback, optional AbstractFilter? filter);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • conversationsChangeCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageConversationsChangeCallback.
    • Description: Callback that is called when the MessageStorage is changed.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: The criteria to be used when filtering.
Return value
long The subscription identifier.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 var conversationChangeCB = {
       conversationsupdated: function(conversations) {
         console.log(conversations.length + " conversations(s) updated");},
       conversationsadded: function(conversations) {
         console.log(conversations.length + " conversations(s) added");},
       conversationsremoved: function(conversations) {
         console.log(conversations.length + " conversations(s) removed");}
 };

 messageStorage.addConversationsChangeListener(conversationChangeCB);
 

addFoldersChangeListener

Adds a listener to subscribe to notifications for MessageFolder changes.

Signature
long addFoldersChangeListener(MessageFoldersChangeCallback foldersChangeCallback, optional AbstractFilter? filter);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.
Parameters
  • foldersChangeCallback
    • Optional: No.
    • Nullable: No.
    • Type: MessageFoldersChangeCallback.
    • Description: Callback that is called when the MessageStorage is changed.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: The criteria to be used when filtering.
Return value
long The subscription identifier.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 var folderChangeCB = {
       foldersupdated: function(folders) {
         console.log(folders.length + " folders(s) updated");},
       foldersadded: function(folders) {
         console.log(folders.length + " folders(s) added");},
       foldersremoved: function(folders) {
         console.log(folders.length + " folders(s) removed");}
 };

 messageStorage.addFoldersChangeListener(folderChangeCB);
 

removeChangeListener

Removes a listener to unsubscribe from receiving message notifications.

Signature
void removeChangeListener(long watchId);

The errorCallback is launched with these error types:

  • InvalidValuesError - If any of the input parameters contains an invalid value.
  • UnknownError - If any other error occurs.

If the subscriptionId argument is valid and corresponds to a subscription already in place, the subscription process must stop immediately and further MessagingStorage change notifications must not be invoked. If the subscriptionId argument does not correspond to a valid subscription, the method will return without any further action.

Parameters
  • watchId
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: An identifier of the subscription returned by addMessagesChangeListener, addConversationsChangeListener or addFoldersChangeListener methods.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the application does not have the privilege to call this method.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 var watchId;
 var service; // Assume messaging service is initialized
 var messageStorage = service.messageStorage; 
 var folderChangeCB = {
       foldersupdated: function(folders) {
         console.log(folders.length + " folders(s) updated. Cancel watching.");
         messageStorage.removeChangeListener(watchId); },
       foldersadded: function(folders) {
         console.log(folders.length + " folders(s) added. Cancel watching.");
         messageStorage.removeChangeListener(watchId); },
       foldersremoved: function(folders) {
         console.log(folders.length + " folders(s) removed. Cancel watching.");
         messageStorage.removeChangeListener(watchId);}
 };

 watchId = messageStorage.addFoldersChangeListener(folderChangeCB);

 

2.13. MessageArraySuccessCallback

findMessages specific success callback.

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageArraySuccessCallback {

    void onsuccess(Message[] messages);
  };

This callback interface specifies a success callback function, taking a list of messages that satisfy the filtering criteria as the input argument. It is used in the findMessages asynchronous operation.

METHODS

onsuccess

Method invoked when an asynchronous query completes successfully.

Signature
void onsuccess(Message[] messages);
Parameters
  • messages
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of messages that satisfy the query.

2.14. MessageConversationArraySuccessCallback

findConversations specific success callback.

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageConversationArraySuccessCallback {

    void onsuccess(MessageConversation[] conversations);
  };

This callback interface specifies a success callback function, taking a list of conversations that satisfy the filtering criteria as the input argument. It is used in the findConversations asynchronous operation.

METHODS

onsuccess

Method invoked when an asynchronous query completes successfully.

Signature
void onsuccess(MessageConversation[] conversations);
Parameters
  • conversations
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of conversations that satisfy the query.

2.15. MessageFolderArraySuccessCallback

findFolders specific success callback.

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageFolderArraySuccessCallback {

    void onsuccess(MessageFolder[] folders);
  };

This callback interface specifies a success callback function, taking a list of folders that satisfy the filtering criteria as the input argument. It is used in the findFolders asynchronous operation.

METHODS

onsuccess

Method invoked when an asynchronous query completes successfully.

Signature
void onsuccess(MessageFolder[] folders);
Parameters
  • folders
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of folders that satisfy the query.

2.16. MessagesChangeCallback

watchMessagesChanges callback.

  [Callback, NoInterfaceObject] interface MessagesChangeCallback {

    void messagesadded(Message[] addedMessages);

    void messagesupdated(Message[] updatedMessages);

    void messagesremoved(Message[] removedMessages);
  };

This callback interface specifies a callback as a set of functions that will be invoked when messages from MessageStorage change. Each function takes a list of messages as the input argument.

METHODS

messagesadded

Method invoked when messages are added to the MessageStorage.

Signature
void messagesadded(Message[] addedMessages);
Parameters
  • addedMessages
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of added messages.

messagesupdated

Method invoked when messages are updated in MessageStorage.

Signature
void messagesupdated(Message[] updatedMessages);
Parameters
  • updatedMessages
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of updated messages.

messagesremoved

Method invoked when messages are removed from MessageStorage.

Signature
void messagesremoved(Message[] removedMessages);
Parameters
  • removedMessages
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of removed messages. It contains only MessageId attribute.

2.17. MessageConversationsChangeCallback

watchConversationsChanges callback.

  [Callback, NoInterfaceObject] interface MessageConversationsChangeCallback {

    void conversationsadded(MessageConversation[] addedConversations);

    void conversationsupdated(MessageConversation[] updatedConversations);

    void conversationsremoved(MessageConversation[] removedConversations);
  };

This callback interface specifies a callback as a set of functions that will be invoked when conversations from MessageStorage change. Each function takes a list of conversations as the input argument.

METHODS

conversationsadded

Method invoked when conversations are added to MessageStorage.

Signature
void conversationsadded(MessageConversation[] addedConversations);
Parameters
  • addedConversations
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of added conversations.

conversationsupdated

Method invoked when conversations are updated in MessageStorage.

Signature
void conversationsupdated(MessageConversation[] updatedConversations);
Parameters
  • updatedConversations
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of updated conversations.

conversationsremoved

Method invoked when conversations are removed from MessageStorage.

Signature
void conversationsremoved(MessageConversation[] removedConversations);
Parameters
  • removedConversations
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of removed conversations. It contains only MessageConvId attribute.

2.18. MessageFoldersChangeCallback

This callback interface specifies a callback as a set of functions that are invoked when message folders from MessageStorage change. Each function takes a list of folders as the input argument.

  [Callback, NoInterfaceObject] interface MessageFoldersChangeCallback {
 
    void foldersadded(MessageFolder[] addedFolders);

    void foldersupdated(MessageFolder[] updatedFolders);

    void foldersremoved(MessageFolder[] removedFolders);
  };

METHODS

foldersadded

Called when folders are added to MessageStorage.

Signature
void foldersadded(MessageFolder[] addedFolders);
Parameters
  • addedFolders
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of added folders.

foldersupdated

Called when folders are updated in MessageStorage.

Signature
void foldersupdated(MessageFolder[] updatedFolders);
Parameters
  • updatedFolders
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of updated folders.

foldersremoved

Called when folders are removed from MessageStorage.

Signature
void foldersremoved(MessageFolder[] removedFolders);
Parameters
  • removedFolders
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: Array of removed folders. It contains only MessageFolderId attribute.

2.19. MessageConversation

This interface defines the message conversation (also known as the thread of messages).

  [NoInterfaceObject] interface MessageConversation {

    readonly attribute MessageConvId id;

    readonly attribute MessageServiceTag type;

    readonly attribute Date timestamp;
     
    readonly attribute unsigned long messageCount;

    readonly attribute unsigned long unreadMessages;

    readonly attribute DOMString preview;

    readonly attribute DOMString subject;

    readonly attribute boolean isRead;

    readonly attribute DOMString from;

    readonly attribute DOMString[] to;

    readonly attribute DOMString[] cc;

    readonly attribute DOMString[] bcc;

    readonly attribute MessageId lastMessageId;
  };

This interface allows a web application to get the set of properties linked to a conversation. This interface provides only read-only attributes.

ATTRIBUTES

readonly MessageConvId id

The conversation identifier.

The ID is locally unique and persistent property, assigned by the device or the Web runtime (WRT).

This attribute is read-only.

readonly MessageServiceTag type

The type of a given conversation.

This attribute is read-only.

readonly Date timestamp

The timestamp of the latest message in a conversation.

This property is set up by the device or the Web runtime environment.

This attribute is read-only.

readonly unsigned long messageCount

The count of messages in a conversation.

This attribute is read-only.

readonly unsigned long unreadMessages

The count of unread messages in a conversation.

This attribute is read-only.

readonly DOMString preview

A preview of the latest message in a conversation.

This attribute is read-only.

readonly DOMString subject

The subject of a conversation (applicable for group chats, MMS, email).

This attribute is read-only.

readonly boolean isRead

An attribute to indicate whether the latest message in a conversation has been read or not.

This property is set to true if the message has been read, else it is set to false.

This attribute is read-only.

readonly DOMString from

The source address (or source phone number) of the latest message in the conversation.

This property is set up by the device or the Web runtime environment.

This attribute is read-only.

readonly DOMString[] to

The destination of the latest message in a conversation.

This attribute is read-only.

readonly DOMString[] cc

The carbon copy (cc) address of the latest message in a conversation.

This property is used only for email.

This attribute is read-only.

readonly DOMString[] bcc

The blind carbon copy (bcc) address of the latest message in a conversation.

This property is used only for email.

This attribute is read-only.

readonly MessageId lastMessageId

The identifier of a latest message in a conversation.

This property is set up by the device or the Web runtime environment.

This attribute is read-only.

2.20. MessageFolder

This interface defines the email folder.

  [NoInterfaceObject] interface MessageFolder {

    readonly attribute MessageFolderId id;

    readonly attribute MessageFolderId parentId;

    readonly attribute DOMString serviceId;

    readonly attribute MessageServiceTag contentType;

    attribute DOMString name setraises(WebAPIException);

    readonly attribute DOMString path;

    readonly attribute DOMString type;

    attribute boolean synchronizable setraises(WebAPIException);
  };

This interface allows a web application to get the set of properties that are linked to an email folder.

The concept of folders is present in several email protocols, such as IMAP, Mail For Exchange.

If the Messaging service does not represent email or an email protocol supporting the concept of folders on a server, this service has one folder which is the standard INBOX folder.

ATTRIBUTES

readonly MessageFolderId id

The folder identifier. The ID is locally unique and persistent property, assigned by the device or the Web runtime (WRT).

This attribute is read-only.

readonly MessageFolderId parentId

The identifier for the parent folder of a specified folder.

If this folder is a root folder, the parent folder ID is null.

This attribute is read-only.

readonly DOMString serviceId

The identifier of the service to which a specified folder belongs.

This attribute is read-only.

readonly MessageServiceTag contentType

The type of the messages contained within a folder.

This attribute is read-only.

DOMString name

The visible name of a folder.

Can be modified. By default, it contains the folder name from the server.

In case the current Messaging service does not support remote folders on the server (and this folder is the only one that the current service has), this attribute contains the service name, by default.

readonly DOMString path

The whole path of a remote folder on the server.

If the current Messaging service does not support remote folders on the server, this attribute will be empty.

This attribute is read-only.

readonly DOMString type

The standard type of a folder.

It can be one of the following values:

  • INBOX
  • OUTBOX
  • DRAFTS
  • SENTBOX

If this folder is not a standard folder, an empty value must be returned.

This property is unique for each type within one Messaging service.

This attribute is read-only.

boolean synchronizable

An attribute to show whether this folder should be synchronized or not.

This attribute affects the behavior of the MessageService.sync() method.

3. Full WebIDL

module Messaging {

  [NoInterfaceObject] interface MessageManagerObject {
    readonly attribute Messaging messaging;
  };
  WebAPIs implements MessageManagerObject;

  enum MessageServiceTag {"messaging.sms", "messaging.mms", "messaging.email" };
  
  typedef DOMString MessageId;
  
  typedef DOMString MessageAttachmentId;

  typedef DOMString MessageConvId;

  typedef DOMString MessageFolderId;  

  [Constructor(MessageServiceTag type, optional MessageInit? messageInitDict)]
  interface Message {

    readonly attribute MessageId? id;

    readonly attribute MessageConvId? conversationId;

    readonly attribute MessageFolderId? folderId;

    readonly attribute MessageServiceTag type;

    readonly attribute Date? timestamp;

    readonly attribute DOMString? from;

    attribute DOMString[] to setraises(WebAPIException);

    attribute DOMString[] cc setraises(WebAPIException);

    attribute DOMString[] bcc setraises(WebAPIException);

    attribute MessageBody body setraises(WebAPIException);

    attribute boolean isRead setraises(WebAPIException);

    readonly attribute boolean hasAttachment;

    attribute boolean isHighPriority setraises(WebAPIException);

    attribute DOMString subject setraises(WebAPIException);

    readonly attribute MessageId? inResponseTo setraises(WebAPIException);

    readonly attribute DOMString messageStatus;

    attribute MessageAttachment[] attachments setraises(WebAPIException);
  };
  dictionary MessageInit
  {

    DOMString subject;

    DOMString[] to;

    DOMString[] cc;

    DOMString[] bcc;

    DOMString plainBody;

    DOMString htmlBody;

    boolean isHighPriority;
  };

  [NoInterfaceObject] interface MessageBody {

    readonly attribute MessageId messageId;

    readonly attribute boolean loaded;

    attribute DOMString plainBody setraises(WebAPIException);

    attribute DOMString htmlBody setraises(WebAPIException);

    attribute MessageAttachment[] inlineAttachments setraises(WebAPIException);
  };

  [Constructor(DOMString filePath, optional DOMString? mimeType)]
  interface MessageAttachment {
    
    readonly attribute MessageAttachmentId? id;
    
    readonly attribute MessageId? messageId;
    
    readonly attribute DOMString? mimeType;
    
    readonly attribute DOMString? filePath;
  };

  [NoInterfaceObject] interface Messaging {

    void getMessageServices(MessageServiceTag messageServiceType,
                            MessageServiceArraySuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageServiceArraySuccessCallback {

    void onsuccess(MessageService[] services);

  };


  [NoInterfaceObject] interface MessageService {

    readonly attribute DOMString id;

    readonly attribute MessageServiceTag type;

    readonly attribute DOMString name;
                    
    void sendMessage(Message message,
                     optional MessageRecipientsCallback successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    void loadMessageBody(Message message,
                         MessageBodySuccessCallback successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);

    void loadMessageAttachment(MessageAttachment attachment,
                               MessageAttachmentSuccessCallback successCallback,
                               optional ErrorCallback? errorCallback) raises(WebAPIException);

    long sync(optional SuccessCallback? successCallback,
              optional ErrorCallback? errorCallback,
              optional unsigned long? limit) raises(WebAPIException);

    long syncFolder(MessageFolder folder,
                    optional SuccessCallback? successCallback,
                    optional ErrorCallback? errorCallback,
                    optional unsigned long? limit) raises(WebAPIException);

    void stopSync(long opId) raises(WebAPIException);

    readonly attribute MessageStorage messageStorage getraises(WebAPIException);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageRecipientsCallback {

    void onsuccess(DOMString[] recipients);

   };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageBodySuccessCallback {

     void onsuccess(Message message);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageAttachmentSuccessCallback {

     void onsuccess(MessageAttachment attachment);
   };

  [NoInterfaceObject] interface MessageStorage {

    void addDraftMessage(Message message,
                         optional SuccessCallback? successCallback,
                         optional ErrorCallback? errorCallback) raises(WebAPIException);

    void findMessages(AbstractFilter filter,
                      MessageArraySuccessCallback successCallback,
                      optional ErrorCallback? errorCallback,
                      optional SortMode? sort,
                      optional unsigned long? limit,
                      optional unsigned long? offset) raises(WebAPIException);

    void removeMessages(Message[] messages,
                        optional SuccessCallback? successCallback,
                        optional ErrorCallback? errorCallback) raises(WebAPIException);

    void updateMessages(Message[] messages,
                        optional SuccessCallback? successCallback,
                        optional ErrorCallback? errorCallback) raises(WebAPIException);

    void findConversations(AbstractFilter filter,
                           MessageConversationArraySuccessCallback successCallback,
                           optional ErrorCallback? errorCallback,
                           optional SortMode? sort,
                           optional unsigned long? limit,
                           optional unsigned long? offset) raises(WebAPIException);

    void removeConversations(MessageConversation[] conversations,
                             optional SuccessCallback? successCallback,
                             optional ErrorCallback? errorCallback) raises(WebAPIException);


    void findFolders(AbstractFilter filter,
                     MessageFolderArraySuccessCallback successCallback,
                     optional ErrorCallback? errorCallback) raises(WebAPIException);

    long addMessagesChangeListener(MessagesChangeCallback messagesChangeCallback,
                                   optional AbstractFilter? filter) raises(WebAPIException);

    long addConversationsChangeListener(MessageConversationsChangeCallback conversationsChangeCallback,
                                        optional AbstractFilter? filter) raises(WebAPIException);

    long addFoldersChangeListener(MessageFoldersChangeCallback foldersChangeCallback,
                                  optional AbstractFilter? filter) raises(WebAPIException);

    void removeChangeListener(long watchId) raises(WebAPIException);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageArraySuccessCallback {

    void onsuccess(Message[] messages);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageConversationArraySuccessCallback {

    void onsuccess(MessageConversation[] conversations);
  };

  [Callback=FunctionOnly, NoInterfaceObject] interface MessageFolderArraySuccessCallback {

    void onsuccess(MessageFolder[] folders);
  };

  [Callback, NoInterfaceObject] interface MessagesChangeCallback {

    void messagesadded(Message[] addedMessages);

    void messagesupdated(Message[] updatedMessages);

    void messagesremoved(Message[] removedMessages);
  };

  [Callback, NoInterfaceObject] interface MessageConversationsChangeCallback {

    void conversationsadded(MessageConversation[] addedConversations);

    void conversationsupdated(MessageConversation[] updatedConversations);

    void conversationsremoved(MessageConversation[] removedConversations);
  };

  [Callback, NoInterfaceObject] interface MessageFoldersChangeCallback {
 
    void foldersadded(MessageFolder[] addedFolders);

    void foldersupdated(MessageFolder[] updatedFolders);

    void foldersremoved(MessageFolder[] removedFolders);
  };

  [NoInterfaceObject] interface MessageConversation {

    readonly attribute MessageConvId id;

    readonly attribute MessageServiceTag type;

    readonly attribute Date timestamp;
     
    readonly attribute unsigned long messageCount;

    readonly attribute unsigned long unreadMessages;

    readonly attribute DOMString preview;

    readonly attribute DOMString subject;

    readonly attribute boolean isRead;

    readonly attribute DOMString from;

    readonly attribute DOMString[] to;

    readonly attribute DOMString[] cc;

    readonly attribute DOMString[] bcc;

    readonly attribute MessageId lastMessageId;
  };

  [NoInterfaceObject] interface MessageFolder {

    readonly attribute MessageFolderId id;

    readonly attribute MessageFolderId parentId;

    readonly attribute DOMString serviceId;

    readonly attribute MessageServiceTag contentType;

    attribute DOMString name setraises(WebAPIException);

    readonly attribute DOMString path;

    readonly attribute DOMString type;

    attribute boolean synchronizable setraises(WebAPIException);
  };

};