Messaging API

The Messaging 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

Remark: In order to access files, a proper privilege has to be defined additionally:

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

Since: 1.0

Table of Contents


Summary of Interfaces and Methods

Interface Method
MessageManagerObject
Message
MessageInit
MessageBody
MessageAttachment
Messaging
void getMessageServices (MessageServiceTag messageServiceType, MessageServiceArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
MessageServiceArraySuccessCallback
void onsuccess (MessageService[] services)
MessageService
void sendMessage (Message message, optional MessageRecipientsCallback? successCallback, optional ErrorCallback? errorCallback, optional long? simIndex)
void loadMessageBody (Message message, MessageBodySuccessCallback successCallback, optional ErrorCallback? errorCallback)
void loadMessageAttachment (MessageAttachment attachment, MessageAttachmentSuccessCallback successCallback, optional ErrorCallback? errorCallback)
long sync (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional unsigned long? limit)
long syncFolder (MessageFolder folder, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional 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, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void findMessages (AbstractFilter filter, MessageArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional SortMode? sort, optional unsigned long? limit, optional unsigned long? offset)
void removeMessages (Message[] messages, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void updateMessages (Message[] messages, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void findConversations (AbstractFilter filter, MessageConversationArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional SortMode? sort, optional unsigned long? limit, optional unsigned long? offset)
void removeConversations (MessageConversation[] conversations, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void findFolders (AbstractFilter filter, MessageFolderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback)
long addMessagesChangeListener (MessagesChangeCallback messagesChangeCallback, optional AbstractFilter? filter)
long addConversationsChangeListener (MessageConversationsChangeCallback conversationsChangeCallback, optional AbstractFilter? filter)
long addFoldersChangeListener (MessageFoldersChangeCallback foldersChangeCallback, optional 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

Specifies the Messaging service tags. The following values are supported in this release:
  enum MessageServiceTag { "messaging.sms", "messaging.mms", "messaging.email" };

Since: 1.0

  • messaging.sms, for SMS services
  • messaging.mms, for MMS services
  • messaging.email, for email services

1.2. MessageId

The Message identifier.
  typedef DOMString MessageId;

Since: 1.0

1.3. MessageAttachmentId

The MessageAttachment identifier within a message.
  typedef DOMString MessageAttachmentId;

Since: 1.0

1.4. MessageConvId

The MessageConversation identifier.
  typedef DOMString MessageConvId;

Since: 1.0

1.5. MessageFolderId

The identifier of an email folder.
  typedef DOMString MessageFolderId;

Since: 1.0

2. Interfaces

2.1. MessageManagerObject

The MessageManagerObject interface defines what is instantiated by the Tizen object.
  [NoInterfaceObject] interface MessageManagerObject {
    readonly attribute Messaging messaging;
  };
  Tizen implements MessageManagerObject;

Since: 1.0

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

Attributes

  • readonly Messaging messaging
    Object representing a messaging manager.

    Since: 1.0

2.2. Message

The Message interface 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;
    attribute DOMString[] cc;
    attribute DOMString[] bcc;
    attribute MessageBody body;
    attribute boolean isRead;
    readonly attribute boolean hasAttachment;
    attribute boolean isHighPriority;
    attribute DOMString subject;
    readonly attribute MessageId? inResponseTo;
    readonly attribute DOMString messageStatus;
    attribute MessageAttachment[] attachments;
  };

Since: 1.0

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:

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

/* Defines the error callback. */
function errorCallback(err)
{
  console.log(err.name + " error: " + err.message);
}

function serviceListCB(services)
{
  if (services.length > 0)
  {
    var msg = new tizen.Message("messaging.sms", {plainBody: "Tizen first SMS message."});
    services[0].sendMessage(msg, messageSentCallback, errorCallback);
  }
}

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

Constructors

Constructor (MessageServiceTag, MessageInit?)
Message(MessageServiceTag type, optional MessageInit? messageInitDict);

Attributes

  • readonly MessageId id [nullable]
    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.

    Since: 1.0

  • readonly MessageConvId conversationId [nullable]
    The identifier of the conversation to which the message belongs.

    By default, this attribute is set to null.

    Since: 1.0

  • readonly MessageFolderId folderId [nullable]
    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

    Since: 1.0

  • readonly MessageServiceTag type
    The type of a given message.

    Since: 1.0

  • readonly Date timestamp [nullable]
    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. For a draft message, the timestamp indicates the time at which a message is added. By default, this attribute is set to null.

    Since: 1.0

  • readonly DOMString from [nullable]
    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.

    Since: 1.0

  • DOMString[] to
    The destination of a message.

    Since: 1.0

  • DOMString[] cc
    The carbon copy address of a message.

    This property is used only for email messages.

    Since: 1.0

  • DOMString[] bcc
    The blind carbon copy (bcc) address of a message.

    This property is used only with email messages.

    Since: 1.0

  • MessageBody body
    The body of a message.

    Since: 1.0

  • boolean isRead
    The flag indicating the read state for a message.

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

    Since: 1.0

  • readonly boolean hasAttachment
    The flag indicating whether an attachment(s) exists.

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

    This property is used only with email and MMS messages.(It is valid when body is loaded)

    Since: 1.0

  • boolean isHighPriority
    The flag indicating 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.

    Since: 1.0

  • DOMString subject
    The subject of a message.

    This property is used only with email and MMS messages.

    Since: 1.0

  • readonly MessageId inResponseTo [nullable]
    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.

    Since: 1.0

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

    Since: 1.0

  • 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 after loading message body).

    Since: 1.0

    Code example:

    /* Defines the success callback. */
    function serviceListCB(services)
    {
      if (services.length > 0)
      {
        var msg = new tizen.Message("messaging.email");
        msg.attachments = [
          new tizen.MessageAttachment("images/myimage.png", "image/png"),
          new tizen.MessageAttachment("documents/mydoc.pdf", "text/pdf")
        ];
      }
    }
    
    tizen.messaging.getMessageServices("messaging.email", serviceListCB);
    

2.3. MessageInit

The dictionary providing specific message attributes for message creation.
  dictionary MessageInit {
    DOMString subject;
    DOMString[] to;
    DOMString[] cc;
    DOMString[] bcc;
    DOMString plainBody;
    DOMString htmlBody;
    boolean isHighPriority;
  };

Since: 1.0

This dictionary 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.

Since: 1.0

DOMString[] to
The destination addresses (or phone numbers) of a message.

Since: 1.0

DOMString[] cc
The carbon copy addresses of a message.

This property is used only with email messages.

Since: 1.0

DOMString[] bcc
The blind carbon copy addresses of a message.

This property is used only with email messages.

Since: 1.0

DOMString plainBody
The plain text representation of a message body.

Since: 1.0

DOMString htmlBody
The HTML representation of a message body.

This property is used only with email messages.

Since: 1.0

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.

Since: 1.0

2.4. MessageBody

The MessageBody interface describes a message body.
  [NoInterfaceObject] interface MessageBody {
    readonly attribute MessageId messageId;
    readonly attribute boolean loaded;
    attribute DOMString plainBody;
    attribute DOMString htmlBody;
    attribute MessageAttachment[] inlineAttachments;
  };

Since: 1.0

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.

    Since: 1.0

  • readonly boolean loaded
    The flag indicating whether the message body has been loaded.

    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.

    Since: 1.0

  • DOMString plainBody
    The plain text representation of a message body.

    Since: 1.0

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

    Since: 1.0

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

    Since: 1.0

    Code example:

    /* Defines the success callback. */
    function serviceListCB(services)
    {
      if (services.length > 0)
      {
        var msg = new tizen.Message("messaging.email");
        msg.body.htmlBody = "<html><body><img src='myimage.png'></body></html>";
        msg.body.inlineAttachments = [new tizen.MessageAttachment("images/myimage.png")];
      }
    }
    
    tizen.messaging.getMessageServices("messaging.email", serviceListCB);
    

2.5. MessageAttachment

The MessageAttachment 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;
  };

Since: 1.0

Constructors

Constructor (DOMString, DOMString?)
MessageAttachment(DOMString filePath, optional DOMString? mimeType);

Attributes

  • readonly MessageAttachmentId id [nullable]
    The ID of an attachment.

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

    By default, this attribute is set to null.

    Since: 1.0

  • readonly MessageId messageId [nullable]
    The ID of a parent message.

    By default, this attribute is set to null.

    Since: 1.0

  • readonly DOMString mimeType [nullable]
    The attachment MIME type.

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

    By default, this attribute is set to null.

    Since: 1.0

  • readonly DOMString filePath [nullable]
    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 server.

    Since: 1.0

2.6. Messaging

The Messaging interface retrieves messaging services.
  [NoInterfaceObject] interface Messaging {
    void getMessageServices(MessageServiceTag messageServiceType, MessageServiceArraySuccessCallback successCallback,
                            optional ErrorCallback? errorCallback) raises(WebAPIException);
  };

Since: 1.0

This interface fetches all existing messaging services by type or a messaging service of a given type for concrete account.

Code example:

/* Defines the success callback. */
function serviceListCB(services)
{
  if (services.length > 0)
  {
    var msg = new tizen.Message("messaging.sms");
  }
}

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

tizen.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.
void getMessageServices(MessageServiceTag messageServiceType, MessageServiceArraySuccessCallback successCallback,
                        optional ErrorCallback? errorCallback);

Since: 1.0

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: Type of the services to be retrieved.
  • successCallback: Callback function that is called when the services are successfully retrieved.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

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

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

Code example:

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

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

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

2.7. MessageServiceArraySuccessCallback

The MessageServiceArraySuccessCallback interface defines callback(s) for retrieving message services.
  [Callback=FunctionOnly, NoInterfaceObject] interface MessageServiceArraySuccessCallback {
    void onsuccess(MessageService[] services);
  };

Since: 1.0

Methods

onsuccess
Called when finding message services is successful.
void onsuccess(MessageService[] services);

Since: 1.0

Parameters:

  • services: Array of available MessageService objects on the device.

2.8. MessageService

The MessageService 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;
    readonly attribute MessageStorage messageStorage getraises(WebAPIException);
    void sendMessage(Message message, optional MessageRecipientsCallback? successCallback, optional ErrorCallback? errorCallback,
                     optional long? simIndex) 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);
  };

Since: 1.0

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:

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

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

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

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

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

Attributes

  • readonly DOMString id
    The unique identifier of this Messaging service.

    Since: 1.0.

  • readonly MessageServiceTag type
    The tag supported by this messaging service.

    Since: 1.0

  • readonly DOMString name
    The messaging service name taken from the messaging service.

    Since: 1.0.

  • readonly MessageStorage messageStorage
    The MessageStorage for this messaging service.

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

    Since: 1.0

Methods

sendMessage
Sends a specified message.
void sendMessage(Message message, optional MessageRecipientsCallback? successCallback, optional ErrorCallback? errorCallback,
                 optional long? simIndex);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Remark: simIndex is added for sending the SMS message through the specified SIM since Tizen 2.3.

Remark: Regarding the simIndex, you can find more information (e.g. operator name, phone number) about SIM card through tizen.systeminfo.getPropertyValueArray("SIM",..).
The feasible use case would be showing all available SIM information and then the user selects the SIM to send a message.

Parameters:

  • message: Message to be sent.
  • successCallback [optional] [nullable]: Callback function that is called when the message is successfully sent.
  • errorCallback [optional] [nullable]: Callback function that is called when the sending request has failed.
  • simIndex [optional] [nullable]: The index of SIM card used to send an SMS message. simIndex value of the first SIM card is 1.
    If the given message is not SMS message type, the simIndex is ignored. If simIndex is not set, the SMS message is sent through the currently enabled SIM. The possible simIndex values should be retrieved through the System Info API.
    If simIndex value is not valid, InvalidValuesError will be returned through ErrorCallback.

Exceptions:

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

    • with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.

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

Code example:

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

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

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

Code example:

/* ********************************************************************************** */
/* *  This sample code works on a device which supports Tizen 2.3 Web Device API.   * */
/* ********************************************************************************** */

/* To get how many SIM cards are available in a device. */
var count = tizen.systeminfo.getCount("SIM");
console.log("There is (are) " + count + " SIM card(s) available.");

/* To send a message via the last SIM. */
services[0].sendMessage(msg, messageSent, messageFailed, count);
loadMessageBody
Loads the body for a specified message.
void loadMessageBody(Message message, MessageBodySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • message: Message with the body to be loaded.
  • successCallback: Callback function that is called when the message body is successfully loaded.
  • errorCallback [optional] [nullable]: Callback function that is called when the loading request fails.

Exceptions:

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

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

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

Code example:

/* Assumes messaging service is initialized. */
var service;

/* Defines the success body loaded callback. */
function successCallback(message)
{
  console.log("Body for message: " + message.subject + " from: " + message.from + " loaded.");
}

/* Defines the 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 tizen.AttributeFilter("type", "EXACTLY", "messaging.email"), messageQueryCallback);
loadMessageAttachment
Loads a specified message attachment.
void loadMessageAttachment(MessageAttachment attachment, MessageAttachmentSuccessCallback successCallback,
                           optional ErrorCallback? errorCallback);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • attachment: Message attachment to be loaded.
  • successCallback: Callback function that is called when the message attachment is successfully loaded.
  • errorCallback [optional] [nullable]: Callback function that is called when the loading request fails.

Exceptions:

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

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

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

Code example:

/* Assumes messaging service is initialized. */
var service;

/* Defines the success body loaded callback. */
function successCallback(attachment)
{
  console.log("Attachment " + attachment.id + " is loaded to: " + attachment.filePath);
}

/* Defines the 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 tizen.AttributeFilter("hasAttachment", "EXACTLY", true), messagesFoundCB);
sync
Synchronizes the service content with an external mail server.
long sync(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback, optional unsigned long? limit);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • successCallback [optional] [nullable]: Callback function that is called when the operation is completed successfully.
  • errorCallback [optional] [nullable]: Callback function that is called when the request fails.
  • limit [optional] [nullable]: Maximum amount of messages retrieved within each folder.

Return value:

    long: Identifier which can be used to stop initiated sync operation.

Exceptions:

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

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

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

Code example:

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

/* Defines the success callback. */
function servicesListSuccessCB(services)
{
  services[0].sync(serviceSynced, null, 30);
  /* Subscribes to MessageStorage notification. */
}
tizen.messaging.getMessageServices("messaging.email", servicesListSuccessCB);
syncFolder
Synchronizes the folder content with an external mail server.
long syncFolder(MessageFolder folder, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback,
                optional unsigned long? limit);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • folder: Folder to be synchronized.
  • successCallback [optional] [nullable]: Callback function that is called when the operation is completed successfully.
  • errorCallback [optional] [nullable]: Callback function that is called when the request fails.
  • limit [optional] [nullable]: The maximum amount of messages retrieved within a given folder.

Return value:

    long: Identifier which can be used to stop initiated sync operation.

Exceptions:

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

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

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

Code example:

var emailService;  /* Assumes email service is initialized. */

/* Defines the error callback. */
function errorCallback(err)
{
  console.log(err.name + " error: " + err.message);
}

function serviceCallback(services)
{
  emailService = services[0];
  var filter = new tizen.AttributeFilter("serviceId", "EXACTLY", emailService.id);

  emailService.messageStorage.findFolders(filter, folderQueryCallback);
}

/* Defines 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);
  }
}

tizen.messaging.getMessageServices("messaging.email", serviceCallback, errorCallback);
stopSync
Stops sync() and syncFoler() operation.
void stopSync(long opId);

Since: 1.0

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: Service operation identifier.

Exceptions:

  • WebAPIException
    • with error type UnknownError, if the method cannot be completed because of an unknown error.

2.9. MessageRecipientsCallback

The MessageRecipientsCallback interface specifies the methods to be called for the sendMessage() operation.
  [Callback=FunctionOnly, NoInterfaceObject] interface MessageRecipientsCallback {
    void onsuccess(DOMString[] recipients);
  };

Since: 1.0

Methods

onsuccess
Called when the message sending is finished.
void onsuccess(DOMString[] recipients);

Since: 1.0

Parameters:

  • recipients: Recipients of the message.

2.10. MessageBodySuccessCallback

The MessageBodySuccessCallback 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);
  };

Since: 1.0

Methods

onsuccess
Called when the asynchronous query completes successfully.
void onsuccess(Message message);

Since: 1.0

Parameters:

  • message: Message containing the loaded body.

2.11. MessageAttachmentSuccessCallback

The MessageAttachmentSuccessCallback callback interface specifies a success callback function that takes the loaded attachment as the input argument. It is used in the loadMessageAttachment() asynchronous operation.
  [Callback=FunctionOnly, NoInterfaceObject] interface MessageAttachmentSuccessCallback {
    void onsuccess(MessageAttachment attachment);
  };

Since: 1.0

Methods

onsuccess
Called when the asynchronous query completes successfully.
void onsuccess(MessageAttachment attachment);

Since: 1.0

Parameters:

  • attachment: Loaded attachment.

2.12. MessageStorage

The MessageStorage interface allows management capabilities using a web application to query, update, and delete messages, and subscribe to MessageStorage changes.
  [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);
  };

Since: 1.0

In addition to simple message queries, the MessageStorage interface provides functionality to find conversations and folders.

Methods

addDraftMessage
Adds a draft message to MessageStorage and these messages are stored in the Drafts folder.
void addDraftMessage(Message message, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • message: Draft message to add to the storage.
  • successCallback [optional] [nullable]: Callback function that is called when draft messages are successfully added.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

  • WebAPIException
    • 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 a received message.

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

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

Code example:

/* Defines the success callback. */
function successCallback()
{
  console.log("Draft message added");
}

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("Cannot add draft message: " + error.message);
}

/* Defines the service query success callback. */
function serviceListCB(services)
{
  if (services.length > 0)
  {
    var msg = new tizen.Message("messaging.sms", {plainBody: "Tizen draft SMS message."});
    services[0].messageStorage.addDraftMessage(msg, successCallback, errorCallback);
  }
}
tizen.messaging.getMessageServices("messaging.sms", serviceListCB);
findMessages
Finds messages from MessageStorage.
void findMessages(AbstractFilter filter, MessageArraySuccessCallback successCallback, optional ErrorCallback? errorCallback,
                  optional SortMode? sort, optional unsigned long? limit, optional unsigned long? offset);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.read

Parameters:

  • filter: Criteria to be used when filtering.
  • successCallback: Callback function that is called when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.
  • sort [optional] [nullable]: Sorting mode for the query.
  • limit [optional] [nullable]: The maximum number of messages to retrieve (It has the same meaning as SQL LIMIT)
    Defaults to 0, meaning that there is no limit
  • offset [optional] [nullable]: Offset in the result set, from where the results are listed (It is the same semantics as SQL OFFSET)
    Defaults to 0, meaning no offset.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes 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);
  }
}

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("Cannot query messages: " + error.message);
}

var filter = new tizen.AttributeFilter("from", "CONTAINS", "2593");
messageStorage.findMessages(filter, messageArrayCB, errorCallback);
removeMessages
Removes messages from MessageStorage.
void removeMessages(Message[] messages, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • messages: Array of messages to delete.
  • successCallback [optional] [nullable]: Callback function that is called when messages are successfully deleted.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes messaging service is initialized. */
var messageStorage = service.messageStorage;

/* Defines the success callback. */
function successCallback()
{
  console.log("Messages were deleted");
}

/* Defines the 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 tizen.AttributeFilter("from", "CONTAINS", "2593");
messageStorage.findMessages(filter, messageArrayCB);
updateMessages
Updates messages in MessageStorage.
void updateMessages(Message[] messages, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

The backend must check whether the required updates can be applied and invoke the errorCallback, 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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • messages: Array listing messages to update.
  • successCallback [optional] [nullable]: Callback function that is called when messages are successfully updated.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes messaging service is initialized. */
var messageStorage = service.messageStorage;

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

/* Defines the 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 tizen.AttributeFilter("isRead", "EXACTLY", false);
messageStorage.findMessages(filter, messageArrayCB);
findConversations
Finds conversations from MessageStorage.
void findConversations(AbstractFilter filter, MessageConversationArraySuccessCallback successCallback,
                       optional ErrorCallback? errorCallback, optional SortMode? sort, optional unsigned long? limit,
                       optional unsigned long? offset);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.read

Parameters:

  • filter: Criteria to be used when filtering.
  • successCallback: Callback function that is called when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.
  • sort [optional] [nullable]: Sorting mode for the query.
  • limit [optional] [nullable]: The maximum number of messages to retrieve (It has the same meaning as SQL LIMIT)
    If set to 0 or omitted, then the number of records is not limited.
  • offset [optional] [nullable]: Offset in the result set, from where the results are listed (It is the same semantics as SQL OFFSET)
    Defaults to 0, meaning no offset.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes 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);
  }
}

/* Defines the error callback. */
function errorCallback(error)
{
  console.log("Cannot query conversations: " + error.message);
}

var filter = new tizen.AttributeFilter("from", "CONTAINS", "2593");
messageStorage.findConversations(filter, conversationsArrayCB, errorCallback);
removeConversations
Removes conversations from MessageStorage.
void removeConversations(MessageConversation[] conversations, optional SuccessCallback? successCallback,
                         optional ErrorCallback? errorCallback);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.write

Parameters:

  • conversations: Array of conversations to delete.
  • successCallback [optional] [nullable]: Callback function that is called when conversations are successfully deleted.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes messaging service is initialized. */
var messageStorage = service.messageStorage;

/* Defines the success callback. */
function successCallback()
{
  console.log("Conversations deleted");
}

/* Defines the 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)");
}

/* Defines the error callback. */
function queryErrorCB(error)
{
  console.log("Cannot query conversations: " + error.message);
}

var filter = new tizen.AttributeFilter("from", "CONTAINS", "2593");
messageStorage.findConversations(filter, conversationsArrayCB, queryErrorCB);
findFolders
Queries folders from MessageStorage.
void findFolders(AbstractFilter filter, MessageFolderArraySuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 1.0

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.read

Parameters:

  • filter: Criteria used when filtering.
  • successCallback: Callback function that is called when the invocation ends successfully.
  • errorCallback [optional] [nullable]: Callback function that is called when an error occurs.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes 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 tizen.AttributeFilter("serviceId", "EXACTLY", service.id);
messageStorage.findFolders(filter, folderArrayCB);
addMessagesChangeListener
Adds a listener to subscribe to notification for MessageStorage changes.
long addMessagesChangeListener(MessagesChangeCallback messagesChangeCallback, optional AbstractFilter? filter);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.read

Parameters:

  • messagesChangeCallback: Callback function that is called when the MessageStorage is changed.
  • filter [optional] [nullable]: Criteria to be used when filtering (Message filter).

Return value:

    long: Subscription identifier.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes 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.
long addConversationsChangeListener(MessageConversationsChangeCallback conversationsChangeCallback,
                                    optional AbstractFilter? filter);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.read

Parameters:

  • conversationsChangeCallback: Callback function that is called when the MessageConversation is changed.
  • filter [optional] [nullable]: Criteria to be used when filtering (MessageConversation filter).

Return value:

    long: Subscription identifier.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes 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.
long addFoldersChangeListener(MessageFoldersChangeCallback foldersChangeCallback, optional AbstractFilter? filter);

Since: 1.0

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.read

Parameters:

  • foldersChangeCallback: Callback function that is called when the MessageFolder is changed.
  • filter [optional] [nullable]: Criteria to be used when filtering (MessageFolder filter).

Return value:

    long: Subscription identifier.

Exceptions:

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

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

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

Code example:

var service;  /* Assumes 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.
void removeChangeListener(long watchId);

Since: 1.0

Calling this function has no effect if there is no listener with given id.

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.

Privilege level: public

Privilege: http://tizen.org/privilege/messaging.read

Parameters:

  • watchId: Identifier of the subscription returned by addMessagesChangeListener(), addConversationsChangeListener() or addFoldersChangeListener() methods

Exceptions:

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

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

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

Code example:

var watchId;
var service;  /* Assumes 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

The MessageArraySuccessCallback defines findMessages specific success callback.
  [Callback=FunctionOnly, NoInterfaceObject] interface MessageArraySuccessCallback {
    void onsuccess(Message[] messages);
  };

Since: 1.0

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
Called when an asynchronous query completes successfully.
void onsuccess(Message[] messages);

Since: 1.0

Parameters:

  • messages: Array of messages that satisfy the query.

2.14. MessageConversationArraySuccessCallback

The MessageConversationArraySuccessCallback interface defines findConversations specific success callback.
  [Callback=FunctionOnly, NoInterfaceObject] interface MessageConversationArraySuccessCallback {
    void onsuccess(MessageConversation[] conversations);
  };

Since: 1.0

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
Called when an asynchronous query completes successfully.
void onsuccess(MessageConversation[] conversations);

Since: 1.0

Parameters:

  • conversations: Array of conversations that satisfy the query.

2.15. MessageFolderArraySuccessCallback

The MessageFolderArraySuccessCallback interface defines findFolders specific success callback.
  [Callback=FunctionOnly, NoInterfaceObject] interface MessageFolderArraySuccessCallback {
    void onsuccess(MessageFolder[] folders);
  };

Since: 1.0

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
Called when an asynchronous query completes successfully.
void onsuccess(MessageFolder[] folders);

Since: 1.0

Parameters:

  • folders: Array of folders that satisfy the query.

2.16. MessagesChangeCallback

The MessagesChangeCallback defines addMessagesChangeListener callback.
  [Callback, NoInterfaceObject] interface MessagesChangeCallback {
    void messagesadded(Message[] addedMessages);
    void messagesupdated(Message[] updatedMessages);
    void messagesremoved(Message[] removedMessages);
  };

Since: 1.0

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
Called when messages are added to the MessageStorage.
void messagesadded(Message[] addedMessages);

Since: 1.0

Parameters:

  • addedMessages: Array of added messages.
messagesupdated
Called when messages are updated in MessageStorage.
void messagesupdated(Message[] updatedMessages);

Since: 1.0

Parameters:

  • updatedMessages: Array of updated messages.
messagesremoved
Called when messages are removed from MessageStorage.
void messagesremoved(Message[] removedMessages);

Since: 1.0

Parameters:

  • removedMessages: Array of removed messages. It contains only MessageId attribute.

2.17. MessageConversationsChangeCallback

The MessageConversationsChangeCallback interface defines addConversationsChangeListener callback.
  [Callback, NoInterfaceObject] interface MessageConversationsChangeCallback {
    void conversationsadded(MessageConversation[] addedConversations);
    void conversationsupdated(MessageConversation[] updatedConversations);
    void conversationsremoved(MessageConversation[] removedConversations);
  };

Since: 1.0

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
Called when conversations are added to MessageStorage.
void conversationsadded(MessageConversation[] addedConversations);

Since: 1.0

Parameters:

  • addedConversations: Array of added conversations.
conversationsupdated
Called when conversations are updated in MessageStorage.
void conversationsupdated(MessageConversation[] updatedConversations);

Since: 1.0

Parameters:

  • updatedConversations: Array of updated conversations.
conversationsremoved
Called when conversations are removed from MessageStorage.
void conversationsremoved(MessageConversation[] removedConversations);

Since: 1.0

Parameters:

  • removedConversations: Array of removed conversations. Every element contains only MessageConvId attribute.

2.18. MessageFoldersChangeCallback

The MessageFoldersChangeCallback 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);
  };

Since: 1.0

Methods

foldersadded
Called when folders are added to MessageStorage.
void foldersadded(MessageFolder[] addedFolders);

Since: 1.0

Parameters:

  • addedFolders: Array of added folders.
foldersupdated
Called when folders are updated in MessageStorage.
void foldersupdated(MessageFolder[] updatedFolders);

Since: 1.0

Parameters:

  • updatedFolders: Array of updated folders.
foldersremoved
Called when folders are removed from MessageStorage.
void foldersremoved(MessageFolder[] removedFolders);

Since: 1.0

Parameters:

  • removedFolders: Array of removed folders. Each element contains only MessageFolderId attribute.

2.19. MessageConversation

The MessageConversation 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;
  };

Since: 1.0

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

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.

Attributes

  • readonly MessageConvId id
    The conversation identifier.

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

    Since: 1.0

  • readonly MessageServiceTag type
    The type of a given conversation.

    Since: 1.0

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

    Since: 1.0

  • readonly unsigned long messageCount
    The count of messages in a conversation.

    Since: 1.0

  • readonly unsigned long unreadMessages
    The count of unread messages in a conversation.

    Since: 1.0

  • readonly DOMString preview
    A preview of the latest message in a conversation.

    Since: 1.0

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

    Since: 1.0

  • readonly boolean isRead
    The flag indicating whether the latest message in a conversation has been read.

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

    Since: 1.0

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

    Since: 1.0

  • readonly DOMString[] to
    The destination of the latest message in a conversation.

    Since: 1.0

  • readonly DOMString[] cc
    The carbon copy (cc) address of the latest message in a conversation.

    This property is used only for email.

    Since: 1.0

  • readonly DOMString[] bcc
    The blind carbon copy (bcc) address of the latest message in a conversation.

    This property is used only for email.

    Since: 1.0

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

    Since: 1.0

2.20. MessageFolder

The MessageFolder 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;
    readonly attribute DOMString path;
    readonly attribute DOMString type;
    attribute boolean synchronizable;
  };

Since: 1.0

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

    Since: 1.0

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

    Since: 1.0

  • readonly DOMString serviceId
    The identifier of the service to which a specified folder belongs.

    Since: 1.0.

  • readonly MessageServiceTag contentType
    The type of the messages contained within a folder.

    Since: 1.0

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

    Since: 1.0

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

    Since: 1.0

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

    Since: 1.0

  • boolean synchronizable
    The flag indicating whether this folder should be synchronized.

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

    Since: 1.0

3. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee that the sms application runs on a device with telephony(SMS) feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/network.telephony
  • To guarantee that the mms application runs on a device with MMS feature, define below in the config file:

  • http://tizen.org/feature/network.telephony.mms
  • For more information, see Application Filtering.

    4. Full WebIDL

    module Messaging {
      typedef DOMString MessageId;
      typedef DOMString MessageAttachmentId;
      typedef DOMString MessageConvId;
      typedef DOMString MessageFolderId;
      enum MessageServiceTag { "messaging.sms", "messaging.mms", "messaging.email" };
      dictionary MessageInit {
        DOMString subject;
        DOMString[] to;
        DOMString[] cc;
        DOMString[] bcc;
        DOMString plainBody;
        DOMString htmlBody;
        boolean isHighPriority;
      };
      Tizen implements MessageManagerObject;
      [NoInterfaceObject] interface MessageManagerObject {
        readonly attribute Messaging messaging;
      };
      [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;
        attribute DOMString[] cc;
        attribute DOMString[] bcc;
        attribute MessageBody body;
        attribute boolean isRead;
        readonly attribute boolean hasAttachment;
        attribute boolean isHighPriority;
        attribute DOMString subject;
        readonly attribute MessageId? inResponseTo;
        readonly attribute DOMString messageStatus;
        attribute MessageAttachment[] attachments;
      };
      [NoInterfaceObject] interface MessageBody {
        readonly attribute MessageId messageId;
        readonly attribute boolean loaded;
        attribute DOMString plainBody;
        attribute DOMString htmlBody;
        attribute MessageAttachment[] inlineAttachments;
      };
      [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;
        readonly attribute MessageStorage messageStorage getraises(WebAPIException);
        void sendMessage(Message message, optional MessageRecipientsCallback? successCallback, optional ErrorCallback? errorCallback,
                         optional long? simIndex) 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);
      };
      [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;
        readonly attribute DOMString path;
        readonly attribute DOMString type;
        attribute boolean synchronizable;
      };
    };