Samsung Web API: Messaging

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

The errorCallback is launched with these error types:

• InvalidValuesError - If any of the input parameters contain an invalid value, the encoding is not valid or onsuccess is null. Please note that to allow developers to ignore errors, errorCallback accepts null as a valid value.
• UnknownError - In any other error case.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The errorCallback is launched with these error types:

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

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

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

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

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

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

The errorCallback is launched with these error types:

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

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

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

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

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

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

The errorCallback is launched with these error types:

• InvalidValuesError - If any of the input parameters contains an invalid value.
• AbortError - If the operation has been stopped.
• UnknownError - If any other error occurs.

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

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

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

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

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

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

• message header details
• whole message body

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

The errorCallback is launched with these error types:

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

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

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

void stopSync(long opId);

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

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

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

The errorCallback is launched with these error types:

• InvalidValuesError: If any of the input parameters contain an invalid value.
• UnknownError: In any other error case.

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

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

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

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

The errorCallback is launched with these error types:

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

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

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

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

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

The errorCallback is launched with these error types:

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

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

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

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

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

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

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

The errorCallback is launched with these error types:

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

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

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

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

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

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

 

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

The errorCallback is launched with these error types:

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

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

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

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

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

The errorCallback is launched with these error types:

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

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

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

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

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

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

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

The errorCallback is launched with these error types:

• InvalidValuesError: If any of the input parameters contains an invalid value.
• UnknownError: In any other error case.

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

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

The errorCallback is launched with these error types:

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

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

 messageStorage.addMessagesChangeListener(messageChangeCallback);
 

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

The errorCallback is launched with these error types:

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

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

 messageStorage.addConversationsChangeListener(conversationChangeCB);
 

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

The errorCallback is launched with these error types:

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

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

 messageStorage.addFoldersChangeListener(folderChangeCB);
 

void removeChangeListener(long watchId);

The errorCallback is launched with these error types:

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

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

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

 watchId = messageStorage.addFoldersChangeListener(folderChangeCB);