Messaging API
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.
Since: 1.0
Table of Contents
- 1. Type Definitions
- 1.1. MessageServiceTag
- 1.2. MessageId
- 1.3. MessageAttachmentId
- 1.4. MessageConvId
- 1.5. MessageFolderId
- 2. Interfaces
- 2.1. MessageManagerObject
- 2.2. Message
- 2.3. MessageInit
- 2.4. MessageBody
- 2.5. MessageAttachment
- 2.6. Messaging
- 2.7. MessageServiceArraySuccessCallback
- 2.8. MessageService
- 2.9. MessageRecipientsCallback
- 2.10. MessageBodySuccessCallback
- 2.11. MessageAttachmentSuccessCallback
- 2.12. MessageStorage
- 2.13. MessageArraySuccessCallback
- 2.14. MessageConversationArraySuccessCallback
- 2.15. MessageFolderArraySuccessCallback
- 2.16. MessagesChangeCallback
- 2.17. MessageConversationsChangeCallback
- 2.18. MessageFoldersChangeCallback
- 2.19. MessageConversation
- 2.20. MessageFolder
- 3. Related Feature
- 4. Full WebIDL
Summary of Interfaces and Methods
1. Type Definitions
1.1. MessageServiceTag
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
2. Interfaces
2.1. MessageManagerObject
[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 messagingObject representing a messaging manager.
Since: 1.0
2.2. 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 typeThe 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[]
toThe destination of a message.
Since: 1.0
-
DOMString[]
ccThe carbon copy address of a message.
This property is used only for email messages.
Since: 1.0
-
DOMString[]
bccThe blind carbon copy (bcc) address of a message.
This property is used only with email messages.
Since: 1.0
-
MessageBody bodyThe body of a message.
Since: 1.0
-
boolean isReadThe 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 hasAttachmentThe 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 isHighPriorityThe 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 subjectThe 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 messageStatusThe 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[]
attachmentsThe 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
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
[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 messageIdThe ID of a parent message.
It holds the ID of the message containing this body.
Since: 1.0
-
readonly
boolean loadedThe 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 plainBodyThe plain text representation of a message body.
Since: 1.0
-
DOMString htmlBodyThe 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[]
inlineAttachmentsThe 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
[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
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
[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
[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
[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 idThe unique identifier of this Messaging service.
Since: 1.0.
-
readonly
MessageServiceTag typeThe tag supported by this messaging service.
Since: 1.0
-
readonly
DOMString nameThe messaging service name taken from the messaging service.
Since: 1.0.
-
readonly
MessageStorage messageStorageThe 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.
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
[Callback=FunctionOnly, NoInterfaceObject] interface MessageRecipientsCallback { void onsuccess(DOMString[] recipients); };
Since: 1.0
2.10. MessageBodySuccessCallback
[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
[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
[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
[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
[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
[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
[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
[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
[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
[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 idThe conversation identifier.
The ID is locally unique and persistent property, assigned by the device or the Web runtime (WRT).
Since: 1.0
-
readonly
MessageServiceTag typeThe type of a given conversation.
Since: 1.0
-
readonly
Date timestampThe 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 messageCountThe count of messages in a conversation.
Since: 1.0
-
readonly
unsigned long unreadMessagesThe count of unread messages in a conversation.
Since: 1.0
-
readonly
DOMString previewA preview of the latest message in a conversation.
Since: 1.0
-
readonly
DOMString subjectThe subject of a conversation (applicable for group chats, MMS, email).
Since: 1.0
-
readonly
boolean isReadThe 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 fromThe 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[]
toThe destination of the latest message in a conversation.
Since: 1.0
-
readonly
DOMString[]
ccThe carbon copy (cc) address of the latest message in a conversation.
This property is used only for email.
Since: 1.0
-
readonly
DOMString[]
bccThe blind carbon copy (bcc) address of the latest message in a conversation.
This property is used only for email.
Since: 1.0
-
readonly
MessageId lastMessageIdThe 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
[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 idThe folder identifier. The ID is locally unique and persistent property, assigned by the device or the Web runtime (WRT).
Since: 1.0
-
readonly
MessageFolderId parentIdThe 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 serviceIdThe identifier of the service to which a specified folder belongs.
Since: 1.0.
-
readonly
MessageServiceTag contentTypeThe type of the messages contained within a folder.
Since: 1.0
-
DOMString nameThe 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 pathThe 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 typeThe 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 synchronizableThe flag indicating whether this folder should be synchronized.
This attribute affects the behavior of the MessageService.sync() method.
Since: 1.0
3. Related Feature
To guarantee that the sms application runs on a device with telephony(SMS) feature, declare the following feature requirements in the config file:
To guarantee that the mms application runs on a device with MMS feature, define below in the config file:
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; }; };