Bondi logo

The Bondi messaging Module - Version 1.1

12 May 2009

Authors

© 2009 OMTP Ltd. All rights reserved. OMTP and OMTP BONDI are registered trademarks of OMTP Ltd.

Abstract

Send text- and multimedia-messages via Email, SMS, and MMS.

Table of Contents

Summary of Methods

InterfaceMethod
EmailAccountsSuccessCallbackvoid onSuccess(StringArray obj)
OnIncomingSMSvoid onEvent(SMS message)
OnIncomingMMSvoid onEvent(MMS message)
OnIncomingEmailvoid onEvent(Email message)
MessagingError
MessagingManagerSMS createSMS(SMSOptions smsParams)
MMS createMMS(MMSOptions mmsParams)
Email createEmail(EmailOptions emailParams)
PendingOperation sendSMS(SuccessCallback successCallback, ErrorCallback errorCallback, SMS sms)
PendingOperation sendMMS(SuccessCallback successCallback, ErrorCallback errorCallback, MMS mms)
PendingOperation sendEmail(SuccessCallback successCallback, ErrorCallback errorCallback, Email email)
BinaryMessage createBinaryMessage(BinaryMessageOptions binaryParams)
PendingOperation sendBinaryMessage(SuccessCallback successCallback, ErrorCallback errorCallback, BinaryMessage binary)
PendingOperation getAvailableEmailAccounts(EmailAccountsSuccessCallback successCallback, ErrorCallback errorCallback)
unsigned long subscribeToSMS(OnIncomingSMS listener, IncomingSMSEventFilter filter, boolean exclusive)
void unsubscribeFromSMS(unsigned long subscribeHandler)
unsigned long subscribeToMMS(OnIncomingMMS listener, IncomingMMSEventFilter filter, boolean exclusive)
void unsubscribeFromMMS(unsigned long subscribeHandler)
unsigned long subscribeToEmail(OnIncomingEmail listener, IncomingEmailEventFilter filter, boolean exclusive)
void unsubscribeFromEmail(unsigned long subscribeHandler)
SMSObject getProperty(DOMString propertyName)
void setProperty(DOMString propertyName, DOMString propertyValue)
StringArray getRecipients()
DOMString getRecipient(unsigned short index)
void appendRecipient(DOMString phoneNumber)
void clearRecipients()
MMSSlide
MMSObject getProperty(DOMString propertyName)
void setProperty(DOMString propertyName, Object propertyValue)
StringArray getRecipients()
DOMString getRecipient(unsigned long index)
void appendRecipient(DOMString phoneNumber)
void clearRecipients()
StringArray getAttachments()
DOMString getAttachment(unsigned short index)
void appendAttachment(DOMString myAttachment)
void clearAttachments()
EmailDOMString getProperty(DOMString propertyName)
void setProperty(DOMString propertyName, DOMString propertyValue)
StringArray getToList()
StringArray getCCList()
StringArray getBCCList()
void appendTo(DOMString emailAddress)
void clearTo()
void appendCC(DOMString emailAddress)
void clearCC()
void appendBCC(DOMString emailAddress)
void clearBCC()
StringArray getAttachments()
DOMString getAttachment(unsigned short index)
void appendAttachment(DOMString myAttachment)
void clearAttachments()
SMSOptions
MMSOptions
EmailOptions
BinaryMessageOptions
BinaryMessageObject getProperty(DOMString propertyName)
void setProperty(DOMString propertyName, DOMString propertyValue)
StringArray getRecipients()
DOMString getRecipient(unsigned short index)
void appendRecipient(DOMString phoneNumber)
void clearRecipients()
IncomingSMSEventFilter
IncomingMMSEventFilter
IncomingEmailEventFilter
MessagingManagerObject

1. Introduction

The BONDI messaging API provides access to the message sending device system and allows to create and send text-based and multimedia messages. The messages are sent via SMS, MMS, or EMail.

The differentiation of message types is explicitly implemented through the whole API, i.e., each message transmission service (e.g. SMS) is represented by a concrete data type. Thus, the application must first define what type of service should be used for message transmission before the actual message is prepared. For example, the application needs to send a short text message and decides to use SMS as the transmission mechanism. Then, the application will create a message object of type SMSMessage, fill it with the text content and send it out to one or multiple receivers. In order to change the message type, a new object of that type has to be created, filled with the previous content and then send via a specific method (e.g. sendSMS).

Multimedia messages can be composed by attaching files to certain message types (e.g. MMS and EMail). The possibility to define a flow for MMS also exists, following an OAA proposal.

This API also supports notifications about successful delivered messages.

Since the BONDI messaging API is only responsible for sending messages from the device to a single or multiple recipients, reading messages from the different inboxes must be handled using the BONDI commlog API.

1.1. Feature set

This is the URI used to declare this API's feature set, for use in bondi.requestFeature. For the URL, the list of features included by the feature set is provided.

http://bondi.omtp.org/api/messaging

All the Messaging features

Includes API features:

  • http://bondi.omtp.org/api/messaging.email.send
  • http://bondi.omtp.org/api/messaging.mms.send
  • http://bondi.omtp.org/api/messaging.sms.send
  • http://bondi.omtp.org/api/messaging.email.subscribe
  • http://bondi.omtp.org/api/messaging.mms.subscribe
  • http://bondi.omtp.org/api/messaging.sms.subscribe
  • http://bondi.omtp.org/api/messaging.binary.send
  • http://bondi.omtp.org/api/messaging.email.getAccounts
  • http://bondi.omtp.org/api/messaging.email.attach
  • http://bondi.omtp.org/api/messaging.mms.attach

1.2. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions covered is provided.

When any of the features

is successfully requested, the interface MessagingManager is instantiated, and the resulting object appears in the global namespace as Bondi.messagingManager.

http://bondi.omtp.org/api/messaging.email.send

Call to the sendEmail in the messagingManager

Device capabilities:

  • messaging.email.send
http://bondi.omtp.org/api/messaging.mms.send

Call to the sendMMS in the messagingManager

Device capabilities:

  • messaging.mms.send
http://bondi.omtp.org/api/messaging.sms.send

Call to the sendSMS method in the messagingManager

Device capabilities:

  • messaging.sms.send
http://bondi.omtp.org/api/messaging.binary.send

Call to the sendBinary method in the messagingManager

Device capabilities:

  • messaging.binary.send
http://bondi.omtp.org/api/messaging.email.getAccounts

Call to the getAvailableEmailAccounts method in the messagingManager

Device capabilities:

  • messaging.email.getAccounts
http://bondi.omtp.org/api/messaging.email.attach

Call to the appendAttachments in the email object

Device capabilities:

  • messaging.email.attach
http://bondi.omtp.org/api/messaging.mms.attach

Call to the appendAttachments in the mms object

Device capabilities:

  • messaging.mms.attach
http://bondi.omtp.org/api/messaging.sms.subscribe

Call to the subscribeToSMS method

Device capabilities:

  • messaging.mms.subscribe
http://bondi.omtp.org/api/messaging.mms.subscribe

Call to the subscribeToMMS method

Device capabilities:

  • messaging.mms.subscribe
http://bondi.omtp.org/api/messaging.email.subscribe

Call to the subscribeToEmail method

Device capabilities:

  • messaging.email.subscribe

1.3. Device capabilities

messaging.email.attach

Add/change attachment on an email

messaging.mms.attach

Add/change attachment on an MMS

messaging.email.getAccounts

Get email accounts

messaging.email.send

Sends an email message

Security parameters:

  • recipients: Space-separated list of recipient email addresses.
  • inContacts: yes or undefined value depending on whether all recipients are in contacts list
messaging.mms.send

Sends an mms message

Security parameters:

  • recipients: Space-separated list of recipient phone numbers. Any international phone number must start with a U+002B PLUS SIGN.
  • inContacts: yes or undefined value depending on whether all recipients are in contacts list
messaging.sms.send

Sends an sms message

Security parameters:

  • recipients: Space-separated list of recipient phone numbers. Any international phone number must start with a U+002B PLUS SIGN.
  • inContacts: yes or undefined value depending on whether all recipients are in contacts list
messaging.binary.send

Sends a binary message

Security parameters:

  • recipients: Space-separated list of recipient phone numbers. Any international phone number must start with a U+002B PLUS SIGN.
  • inContacts: yes or undefined value depending on whether all recipients are in contacts list
messaging.mms.subscribe

Subscribe to mms message notifications

Security parameters:

  • sender: Sender of the message
messaging.sms.subscribe

Subscribe to sms message notifications

Security parameters:

  • sender: Sender of the message
messaging.binary.subscribe

Subscribe to email message notifications

Security parameters:

  • sender: Sender of the message

2. Type Definitions

2.1. MMSSlideArray

Array of slides 

        typedef sequence<MMSSlide> MMSSlideArray;

3. Interfaces

3.1. EmailAccountsSuccessCallback

Success callback for retrieving a list of email accounts. 

        [Callback=FunctionOnly, NoInterfaceObject] interface EmailAccountsSuccessCallback {
                void onSuccess(in StringArray obj);
        };

Success callback that is used in the asynchronous operation to get the list of Available email accounts.

Methods

onSuccess

Method invoked when the list of available email accounts is retrieved succesfully

Signature
void onSuccess(in StringArray obj);
Parameters
  • obj: Array of strings containing the list of email accounts

3.2. OnIncomingSMS

To be invoked when an application must be notified on an incoming SMS event 

    [Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingSMS {
            void onEvent(in SMS message);
    };

Methods

onEvent

To be invoked when an application must be notified on an incoming SMS event

Signature
void onEvent(in SMS message);
Parameters
  • message: Reference to the incoming SMS

3.3. OnIncomingMMS

To be invoked when an application must be notified on an incoming MMS event 

    [Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingMMS {
            void onEvent(in MMS message);
    };

Methods

onEvent

To be invoked when an application must be notified on an incoming MMS event

Signature
void onEvent(in MMS message);
Parameters
  • message: Reference to the incoming MMS

3.4. OnIncomingEmail

To be invoked when an application must be notified on an incoming e-mail event 

    [Callback=FunctionOnly, NoInterfaceObject] interface OnIncomingEmail {
            void onEvent(in Email message);
    };

Methods

onEvent

To be invoked when an application must be notified on an incoming Email event

Signature
void onEvent(in Email message);
Parameters
  • message: Reference to the incoming Email

3.5. MessagingError

Messaging Errors 

        interface MessagingError : GenericError {

                const unsigned short OUT_OF_COVERAGE_ERROR = 1;

                const unsigned short MMS_VIDEO_SLIDE_ERROR = 2;

                const unsigned short MMS_MESSAGE_SIZE_EXCEEDED_ERROR = 3;
        };

Constants

unsigned short OUT_OF_COVERAGE_ERROR

There is no coverage

unsigned short MMS_VIDEO_SLIDE_ERROR

Media addition is not possible, since the slide already includes a media file that cannot coexist with the others.

unsigned short MMS_MESSAGE_SIZE_EXCEEDED_ERROR

Message size would be exceeded by the given operation.

3.6. MessagingManager

class for managing all messaging functions 

        interface MessagingManager {

                const unsigned short INBOX_FOLDER = 0;

                const unsigned short OUTBOX_FOLDER = 1;

                const unsigned short SENT_FOLDER = 2;

                const unsigned short DRAFTS_FOLDER = 3;

                SMS createSMS([Optional] in SMSOptions smsParams)
                        raises(DeviceAPIError);

                MMS createMMS([Optional] in MMSOptions mmsParams)
                        raises(DeviceAPIError);

                Email createEmail([Optional] in EmailOptions emailParams)
                        raises(DeviceAPIError);

                PendingOperation sendSMS(in SuccessCallback successCallback,
                                              in ErrorCallback errorCallback,
                                              in SMS sms)
                        raises(SecurityError, DeviceAPIError, MessagingError);

                PendingOperation sendMMS(in SuccessCallback successCallback,
                                              in ErrorCallback errorCallback,
                                              in MMS mms)
                        raises(SecurityError, DeviceAPIError, MessagingError);

                PendingOperation sendEmail(in SuccessCallback successCallback,
                                                in ErrorCallback errorCallback,
                                                in Email email)
                        raises(SecurityError, DeviceAPIError, MessagingError);

                BinaryMessage createBinaryMessage([Optional] in BinaryMessageOptions binaryParams)
                        raises(DeviceAPIError);
                        
                PendingOperation sendBinaryMessage(in SuccessCallback successCallback,
                                              in ErrorCallback errorCallback,
                                              in BinaryMessage binary)
                        raises(SecurityError, DeviceAPIError, MessagingError);

                PendingOperation getAvailableEmailAccounts(in EmailAccountsSuccessCallback successCallback,
                                                           in ErrorCallback errorCallback)
                        raises(SecurityError, DeviceAPIError);
                        
                unsigned long subscribeToSMS (in OnIncomingSMS listener,
                                                          in IncomingSMSEventFilter filter,
                                                              in boolean exclusive)
                  raises(SecurityError, DeviceAPIError);

     void unsubscribeFromSMS  (in unsigned long subscribeHandler)
                   raises(SecurityError, DeviceAPIError);
                        
                unsigned long subscribeToMMS (in OnIncomingMMS listener,
                                                                in IncomingMMSEventFilter filter,
                                                                      in boolean exclusive)
                  raises(SecurityError, DeviceAPIError);

        void unsubscribeFromMMS  (in unsigned long subscribeHandler)
                  raises(SecurityError, DeviceAPIError);
                        
            unsigned long subscribeToEmail (in OnIncomingEmail listener,
                                                            in IncomingEmailEventFilter filter,
                                                                in boolean exclusive)
                  raises(SecurityError, DeviceAPIError);

        void unsubscribeFromEmail  (in unsigned long subscribeHandler)
                  raises(SecurityError, DeviceAPIError);
                        
        };

The messaging manager interface provides methods to create and send messages.

Code example
        bondi.requestFeature(successCB, errorCB, "messaging");

Constants

unsigned short INBOX_FOLDER

Constant used to identify the INBOX folder.

unsigned short OUTBOX_FOLDER

Constant used to identify the OUTBOX folder.

unsigned short SENT_FOLDER

Constant used to identify the SENT folder.

unsigned short DRAFTS_FOLDER

Constant used to identify the DRAFTS folder.

Methods

createSMS

Creation of an SMS object

Signature
SMS createSMS(in SMSOptions smsParams);

Creates an SMS object and stores it in the Drafts folder.

Parameters
  • smsParams: SMS content
Return value
SMS object.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if smsParams is not a valid SMSOptions object

Code example
        //This method creates a message in the Drafts folder with the values passed as parameters
        bondi.messaging.createSMS({recipients:"+34666666666",body:"Hello from Huesca",store:false});
createMMS

Creates an MMS object and stores it in the Drafts folder.

Signature
MMS createMMS(in MMSOptions mmsParams);
Parameters
  • mmsParams: MMS content
Return value
MMS object.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if smsParams is not a valid MMSOptions object

Code example
        var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", store:false});
createEmail

Creates an Email object and stores it in the Drafts folder.

Signature
Email createEmail(in EmailOptions emailParams);
Parameters
  • emailParams: Email content
Return value
Email object.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if smsParams is not a valid EmailOptions object

Code example
        var myEmail = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?",store:false});
sendSMS

Sends an SMS This method sends an SMS object that has been created in Drafts folder. When the message has been sent it is stored in the Sent message folder (if the store property is true). It is an asynchronous method. The success method is executed when the sms has been marked to be sent and stored in the Outgoing messaging folders. After this the OS is forced to sync mail folders.

Signature
PendingOperation sendSMS(in SuccessCallback successCallback, in ErrorCallback errorCallback, in SMS sms);
Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs, the input parameter "response" is an Error object with string properties "name" and "message" giving information about the type of error that occurred.
  • sms: an SMS object containing the message to be sent
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

  • MessagingError:

    OUT_OF_COVERAGE_ERROR when the device is out of network coverage

API features
http://bondi.omtp.org/api/messaging.sms.send
Code example
        //This method creates a messaging in the Drafts folder with the values passed as parameters
        var sms = bondi.messaging.createSMS({body:"Just arrived in Huesca",recipients:"+34666666666"});

        // Define the success callback.
        function successCallback(response) {
                alert("Sent");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error code: " +  response.code);
        }

        //This method sends the prevoius created message
        bondi.messaging.sendSMS(successCallback, errorCallback,sms);
sendMMS

Sends an MMS

Signature
PendingOperation sendMMS(in SuccessCallback successCallback, in ErrorCallback errorCallback, in MMS mms);

This method sends an MMS object that has been created in the Drafts folder. When the message has been sent it is stored in the Sent message folder (if the store property is true). It is an asynchronous method. The success method is executed when the mms has been marked to be sent and stored in the Outgoing messaging folders. After this the OS is forced to sync mail folders.

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs, the input parameter "response" is an Error object with string properties "name" and "message" giving information about the type of error that occurred.
  • mms: an MMS object containing the message to be sent
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

  • MessagingError:

    OUT_OF_COVERAGE_ERROR when the device is out of network coverage

API features
http://bondi.omtp.org/api/messaging.mms.send
Code example
        var mms = bondi.messaging.createMMS(null);
        mms.setProperty("body", "Just arrived today at...");
        mms.subject = "In Huesca!";
        mms.appendRecipient ("+34666666666");

        // Define the success callback.
        function successCallback(response) {
                alert("Sent");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error code: " +  response.code);
        }

        // Send the MMS.
        bondi.messaging.sendMMS(successCallback, errorCallback,mms);
sendEmail

Sends and e-mail

Signature
PendingOperation sendEmail(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Email email);

This method sends an Email object that has been created in the Drafts folder. When the message has been sent it is stored in the Sent message folder (if the store property is true). It is an asynchronous method. The success method is executed when the mms has been marked to be sent and stored in the Outgoing messaging folders. After this the OS is forced to sync mail folders.

Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs, the input parameter "response" is an Error object with string properties "name" and "message" giving information about the type of error that occurred.
  • email: an Email object containing the message to be sent
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

  • MessagingError:

    OUT_OF_COVERAGE_ERROR when the device is out of network coverage

API features
http://bondi.omtp.org/api/messaging.email.send
Code example
        var email = bondi.messaging.createEmail();
        email.setProperty("body", "Just arrived today at...");
        email.subject = "In Huesca!";
        email.appendTo("ester@vodafone.com");

        // Define the success callback.
        function successCallback(response) {
                alert("Sent");
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error code: " +  response.code);
        }

        // Send the e-mail.
        bondi.messaging.sendEmail(successCallback, errorCallback,email);
createBinaryMessage

Creation of an Binary object

Signature
BinaryMessage createBinaryMessage(in BinaryMessageOptions binaryParams);

Creates an Binary object.

Parameters
  • binaryParams: Binary message content
Return value
Binary object.
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if smsParams is not a valid BinaryMessageOptions object

Code example
        // reads all the bytes from a file
        var image = bondi.filesystem.resolve("image.jpg");
        var stream = image.open("r", "UTF-8");
        var raw = stream.readBytes(0);

        //This method creates a binary message with the values passed as parameters              
        bondi.messaging.createBinaryMessage({recipients:"+34666666666",port:25657,payload:raw});
sendBinaryMessage

Sends a Binary message This method sends a Binary object that has been created. It is an asynchronous method. The success method is executed when the Binary has been marked to be sent and stored in the Outgoing messaging folders. After this the OS is forced to sync mail folders.

Signature
PendingOperation sendBinaryMessage(in SuccessCallback successCallback, in ErrorCallback errorCallback, in BinaryMessage binary);
Parameters
  • successCallback: function called when the invocation ends successfully.
  • errorCallback: function called when an error occurs, the input parameter "response" is an Error object with string properties "name" and "message" giving information about the type of error that occurred.
  • binary: an Binary object containing the bytes to be sent
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

  • MessagingError:

    OUT_OF_COVERAGE_ERROR when the device is out of network coverage

API features
http://bondi.omtp.org/api/messaging.binary.send
Code example
        // reads all the bytes from a file
        var image = bondi.filesystem.resolve("image.jpg");
        var stream = image.open("r", "UTF-8");
        var raw = stream.readBytes(0);

        //This method creates a binary message with the values passed as parameters              
        bondi.messaging.createBinary({recipients:"+34666666666",port:25657,payload:raw});
        //This method sends the prevoiusly created message
        bondi.messaging.sendBinary(successCallback, errorCallback,binary);

        function successCallback(response) {
                alert("Sent");
        }

        function errorCallback(response) {
                alert( "The following error code: " +  response.code);
        }
getAvailableEmailAccounts

Retrieves available e-mail accounts

Signature
PendingOperation getAvailableEmailAccounts(in EmailAccountsSuccessCallback successCallback, in ErrorCallback errorCallback);

This method gets available email accounts that can be used (to be included in the From field). These addresses are separated by semicoloms(";"). This is an asyncronous method. Returns null if no email accounts are configured in the terminal.

Parameters
  • successCallback: function called when the invocation ends successfully, use response object to retrieve the array of Strings containing accounts.
  • errorCallback: function called when an error occurs, the input parameter "response" is an Error object with string properties "name" and "message" giving information about the type of error that occurred.
Return value
PendingOperation enabling the requester to cancel this request.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

API features
http://bondi.omtp.org/api/messaging.email.getAccounts
Code example
        // Define the success callback.
        function successCallback(response) {
                var email = bondi.messaging.createEmail({from:response[0]});
        }

        // Define the error callback.
        function errorCallback(response) {
                alert( "The following error code: " +  response.code)
        }

        // Get the available e-mail accounts.
        var accounts = bondi.messaging.getAvailableEmailAccounts(successCallback, errorCallback);
subscribeToSMS

Subscribes to receive notifications on incoming SMS

Signature
unsigned long subscribeToSMS(in OnIncomingSMS listener, in IncomingSMSEventFilter filter, in boolean exclusive);

Allows applications to be notified whenever an incoming SMS meets a set of conditions specified by the filter. It is possible for applications to request exclusive notifications. The returned identifier may be used to unsubscribe from these events using the unsubscribe method.

Parameters
  • listener: Function to be invoked when an SMS is received
  • filter: Allows to select some conditions to be met by the SMS. If the conditions are not met, the application will not be notified.
  • exclusive: Allows a widget for requesting exclusive register for the notifications. If set to true no other application could register to these notifications.
Return value
the subscription identifier.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

Code example
        var id = bondi.messaging.subscribeToSMS(
         {onSMS:function(sms) {alert("Incoming SMS: "+ sms.body);}}, 
         {sender:666666666},
         true);
unsubscribeFromSMS

Unsubscribe from SMS notifications

Signature
void unsubscribeFromSMS(in unsigned long subscribeHandler);
Parameters
  • subscribeHandler: Subscription identifier
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

Code example
        var id = bondi.messaging.subscribeToSMS(
         {onSMS:function(sms) {alert("Incoming SMS: "+ sms.body);}}, 
         {sender:666666666},
         true);

  bondi.messaging.unsubscribeFromSMS(id);
subscribeToMMS

Subscribes to receive notifications on incoming MMS

Signature
unsigned long subscribeToMMS(in OnIncomingMMS listener, in IncomingMMSEventFilter filter, in boolean exclusive);

Allows applications to be notified whenever an incoming MMS meets a set of conditions specified by the filter. It is possible for applications to request exclusive notifications. The returned identifier may be used to unsubscribe from these events using the unsubscribe method.

Parameters
  • listener: Function to be invoked when an MMS is received
  • filter: Allows to select some conditions to be met by the MMS. If the conditions are not met, the application will not be notified.
  • exclusive: Allows a widget for requesting exclusive register for the notifications. If set to true no other application could register to these notifications.
Return value
the subscription identifier.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

Code example
        var id = bondi.messaging.subscribeToMMS(
         {onMMS:function(mms) {alert("Incoming MMS: "+ mms.body);}}, 
         {sender:666666666},
         true);
unsubscribeFromMMS

Unsubscribe from MMS notifications

Signature
void unsubscribeFromMMS(in unsigned long subscribeHandler);
Parameters
  • subscribeHandler: Subscription identifier
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

Code example
        var id = bondi.messaging.subscribeToMMS(
         {onMMS:function(mms) {alert("Incoming MMS: "+ mms.body);}}, 
         {sender:666666666},
         true);

  bondi.messaging.unsubscribeFromMMS(id);
subscribeToEmail

Subscribes to receive notifications on incoming e-mail

Signature
unsigned long subscribeToEmail(in OnIncomingEmail listener, in IncomingEmailEventFilter filter, in boolean exclusive);

Allows applications to be notified whenever an incoming e-mail meets a set of conditions specified by the filter. It is possible for applications to request exclusive notifications. The returned identifier may be used to unsubscribe from these events using the unsubscribe method.

Parameters
  • listener: Function to be invoked when an e-mail is received
  • filter: Allows to select some conditions to be met by the e-mail. If the conditions are not met, the application will not be notified.
  • exclusive: Allows a widget for requesting exclusive register for the notifications. If set to true no other application could register to these notifications.
Return value
the subscription identifier.
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

Code example
        var id = bondi.messaging.subscribeToEmail(
         {onEmail:function(email) {alert("Incoming E-mail: "+ email.body);}}, 
         {subject:test},
         true);
unsubscribeFromEmail

Unsubscribe from e-mail notifications

Signature
void unsubscribeFromEmail(in unsigned long subscribeHandler);
Parameters
  • subscribeHandler: Subscription identifier
Exceptions
  • SecurityError:

    PERMISSION_DENIED_ERROR when access is denied by the security policy.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

Code example
        var id = bondi.messaging.subscribeToEmail(
         {onEmail:function(email) {alert("Incoming E-mail: "+ email.body);}}, 
         {subject:test},
         true);

  bondi.messaging.unsubscribeFromEmail(id);

3.7. SMS

SMS Message API 

        interface SMS {

                Object getProperty(in DOMString propertyName)
                        raises(DeviceAPIError);

                void setProperty(in DOMString propertyName, in DOMString propertyValue)
                        raises(DeviceAPIError);

                readonly attribute DOMString id;

                readonly attribute Date datetime;

                 attribute DOMString body
                        setraises(DeviceAPIError);

                 attribute boolean store
                        setraises(DeviceAPIError);

                readonly attribute unsigned short folder;

                readonly attribute boolean read;

                StringArray getRecipients();

                DOMString getRecipient(in unsigned short index)
                        raises(DeviceAPIError);

                void appendRecipient(in DOMString phoneNumber)
                        raises(DeviceAPIError);

                void clearRecipients();
        };

The SMS Message interface provides methods to populate and send a message.

Code example
        bondi.requestFeature(successCB, errorCB, "messaging");

Attributes

readonly DOMString id

Integer that contains the unique identifier assigned to the message in the platform.

This is a readonly property

Code example
        var sms = bondi.messaging.createSMS();
        var id = sms.id;
readonly Date datetime

Object that contains the datetime where the sms was sent or received or created in draft, depending the storage folder.

Code example
        var sms = bondi.messaging.createSMS(null);
        var dateTime = sms.datetime;
DOMString body

String that contains the body of the SMS.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if invalid value is given to body

    • Code example
            var sms = bondi.messaging.createSMS({recipients:"+34666666666",body:"Hello from Huesca",store:false});
        // ...
        alert(sms.body);
    boolean store

    Boolean that indicates whether the message is going to be stored in the SENT folder once sent.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if invalid store value is given

    • Code example
            var sms =bondi.messaging.createSMS({recipients:"+34666666666",body:"Hello from Huesca",store:false});
        // ...
        alert(sms.store);
    readonly unsigned short folder

    Integer that indicates the folder in which the message is stored.

    T

    Code example
            var sms = bondi.messaging.createSMS({recipients:"+34666666666",body:"Hello from Huesca",store:false});
        alert(sms.folder);
    readonly boolean read

    Value that indicates if the message has been already read

    Code example
            var sms = bondi.messaging.createSMS(null);
        var isRead = sms.read;

    Methods

    getProperty

    Returns the value of any of the SMS message object properties.

    Signature
    Object getProperty(in DOMString propertyName);

    Supported properties
    body: String. This represents the body of the sms
    recipients: String. Semicolom(;) separated string containing the recipients list
    store: Boolean. Indicates if the sms will be stored in the sent messages folder. True -> Stored
    id: Integer. Identificator of the SMS
    read: Boolean. It indicates if the SMS has been readen (true) or not (false).
    folder: Integer. It indicates the folder where the sms is stored (must be one of INBOX_FOLDER, OUTBOX_FOLDER, SENT_FOLDER, DRAFTS_FOLDER defined in MessagingManager).
    dateTime: Date. Date object with info about the sms creation or reception date.

    Parameters
    • propertyName: DOMString containing the name of the property to be queried.
    Return value
    Int containing the value of that property when property is id or folder. Date containing the value of that property when property is dateTime. Boolean containing the value of that property when properties are store or read. Object containing the value of that property when properties are body or recipients.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

    Code example
            var sms = bondi.messaging.createSMS();
  sms.folder = bondi.messaging.DRAFTS_FOLDER;
        sms.body="Hello!!";
        var body = sms.getProperty("body");
    setProperty

    n Sets the value of any of the SMS message object properties. (body, store).

    Signature
    void setProperty(in DOMString propertyName, in DOMString propertyValue);
    Parameters
    • propertyName: DOMString containing the name of the property to be set.
    • propertyValue: DOMString ('body') or Boolean ('store') containing the value of the property to be set.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

    Code example
            var sms = bondi.messaging.createSMS();
        sms.setProperty("body", "Just arrived in Huesca");
    getRecipients

    This method returns the list of recipients added to the SMS

    Signature
    StringArray getRecipients();
    Return value
    Array of String containing each one of the recipients for this message (telephone numbers).
    Code example
            var sms =  bondi.messaging.createSMS({recipients:"+34666666666",body:"Hello from Huesca",store:true});
        var recipients = sms.getRecipients();
        alert(recipients.count + " recipients";
    getRecipient

    Gets a recipient from the list of recipients.

    Signature
    DOMString getRecipient(in unsigned short index);
    Parameters
    • index: an integer pointing the position of the recipient to be retrieved.
    Return value
    a DOMString containing the telephone number (telephone numbers).
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var sms = bondi.messaging.createSMS({recipients:"+34666666666",body:"Hello from Huesca",store:true});
        alert(sms.getRecipient(0));
    appendRecipient

    Adds (appends) a new recipient to the list. This recipient must be a phone number format.

    Signature
    void appendRecipient(in DOMString phoneNumber);
    Parameters
    • phoneNumber: a DOMString containing the phone number of the recipient to be added.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided (e.g. if the parameter provided represents an invalid destination or if the phone number provided is larger than the max available size

    Code example
            var sms = bondi.messaging.createSMS(null);
        sms.appendRecipient("+34666666666");
    clearRecipients

    Removes the entire recipients list.

    Signature
    void clearRecipients();
    Code example
            var sms = bondi.messaging.createSMS({recipients:"+34666666666",body:"Hello from Huesca",store:true});
        sms.clearRecipients();

    3.8. MMSSlide

    MMS Slide is a triplet of an image, audio and text. Optionally it can include a video as a replacement for image and audio. 

            interface MMSSlide {

                attribute unsigned long duration;

                attribute DOMString image
                        setraises(MessagingError);

                attribute unsigned long imageBegin;

                attribute unsigned long imageEnd;

                attribute DOMString audio
                        setraises(MessagingError);

                attribute unsigned long audioBegin;

                attribute unsigned long audioEnd;

                attribute DOMString text
                        setraises(MessagingError);

                attribute unsigned long textBegin;

                attribute unsigned long textEnd;

                attribute DOMString video
                        setraises(MessagingError);

                attribute unsigned long videoBegin;

                attribute unsigned long videoEnd;
        };

    http://www.openmobilealliance.org/Technical/release_program/docs/MMS/V1_3-20080128-C/OMA-TS-MMS-CONF-V1_3-20080128-C.pdf section 8: "A slide that contains video SHALL contain only video and text components."

    Attributes

    unsigned long duration

    Duration of the slide presentation, in milliseconds.

    DOMString image

    Image

    File containing the image

  • MessagingError:

    MMS_MESSAGE_SIZE_EXCEEDED_ERROR if the message size would be exceeded by the adding operation

    MMS_VIDEO_SLIDE_ERROR if the slide already includes video part.

    • unsigned long imageBegin

    Beginning of image presentation within a slide, in milliseconds.

    unsigned long imageEnd

    End of image presentation within a slide, in milliseconds.

    DOMString audio

    Audio

    File containing the audio

  • MessagingError:

    MMS_MESSAGE_SIZE_EXCEEDED_ERROR if the message size would be exceeded by the adding operation

    MMS_VIDEO_SLIDE_ERROR if the slide already includes video part.

    • unsigned long audioBegin

    Beginning of audio playback within a slide, in milliseconds.

    unsigned long audioEnd

    End of audio playback within a slide, in milliseconds.

    DOMString text

    Audio

  • MessagingError:

    MMS_MESSAGE_SIZE_EXCEEDED_ERROR if the message size would be exceeded by the adding operation

    • unsigned long textBegin

    Beginning of text presentation within a slide, in milliseconds.

    unsigned long textEnd

    End of text presentation within a slide, in milliseconds.

    DOMString video

    Video

    File containing the video

  • MessagingError:

    MMS_MESSAGE_SIZE_EXCEEDED_ERROR if the message size would be exceeded by the adding operation

    MMS_VIDEO_SLIDE_ERROR if the slide already includes image or audio part.

    • unsigned long videoBegin

    Beginning of video presentation within a slide, in milliseconds.

    unsigned long videoEnd

    End of video presentation within a slide, in milliseconds.

    3.9. MMS

    MMS Message API 

            interface MMS {

                Object getProperty(in DOMString propertyName)
                        raises(DeviceAPIError);


                void setProperty(in DOMString propertyName, in Object propertyValue)
                        raises(DeviceAPIError);

                readonly attribute DOMString id;

                readonly attribute Date datetime;

                attribute DOMString body
                        setraises(DeviceAPIError);

                attribute boolean store
                        setraises(DeviceAPIError);

                readonly attribute unsigned long folder;

                attribute DOMString subject
                        setraises(DeviceAPIError);

                readonly attribute boolean read;

                StringArray getRecipients();

                DOMString getRecipient(in unsigned long index)
                        raises(DeviceAPIError);

                void appendRecipient(in DOMString phoneNumber)
                        raises(DeviceAPIError);

                void clearRecipients();



                StringArray getAttachments();


                DOMString getAttachment(in unsigned short index)
                        raises(DeviceAPIError);


                void appendAttachment(in DOMString myAttachment)
                        raises(SecurityError, DeviceAPIError);


                void clearAttachments()
                        raises(DeviceAPIError);

                const unsigned short MULTIPART_MIXED = 0;

                const unsigned short MULTIPART_RELATED = 1;

                attribute unsigned short messageType;

                attribute MMSSlideArray slides;
        };

    The MMS Message interface provides methods to populate and send a multimedia message.

    Code example
            bondi.requestFeature(successFunc,failureFunc,'messaging');

    Constants

    unsigned short MULTIPART_MIXED

    Constant used to identify the type of MMS Message as multipart/mixed.

    Constant used to identify the type of MMS Message as multipart/related.

    Attributes

    readonly DOMString id

    Unique identifier assigned to the message in the platform.

    Code example
            var MMS = bondi.messaging.createMMS(null);
        var id = MMS.id;
    readonly Date datetime

    String that contains the datetime where the MMS was sent or received or created in draft, depending the storage folder.

    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        var dateTime = mms.datetime;
    DOMString body

    String that contains the message body.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid value is given to the body

    • Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        alert(mms.body);
    boolean store

    Property that indicates whether the message is going to be stored in the SENT folder once sent.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid value is given to the store (eg: not boolean).

    • Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        alert(mms.store);
    readonly unsigned long folder

    Folder where the message is stored.

    This value will be one of INBOX_FOLDER, OUTBOX_FOLDER, SENT_FOLDER, DRAFTS_FOLDER defined in MessagingManager.

    Code example
      // Create the message in the Drafts folder.
        var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        alert(mms.folder);
    DOMString subject

    String with the subject of the MMS

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if an invalid value is given to the subject

    • Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        alert(mms.subject);
    readonly boolean read

    Value that indicates if the message has been already read

    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        var isRead = mms.read;
    unsigned short messageType

    Type of message: multipart/mixed or multipart/related

    MMSSlideArray slides

    Actual slides

    Methods

    getProperty

    Returns the value of any of the MMS message object properties.

    Signature
    Object getProperty(in DOMString propertyName);

    Supported properties
    body: String. This represents the body of the multipart/mixed mms
    subject: String. This represents a resume of the mms
    recipients: String. Semicolom(;) separated string containing the recipients list
    store: Boolean. Indicates if the mms will be stored in the sent messages folder. True -> Stored
    id: Integer. Identificator of the MMS
    read: Boolean. It indicates if the MMS has been readen (true) or not (false).
    folder: Integer. It indicates the folder where the mms is stored.
    datetime: Date. Date object with info about the mms creation or reception date.
    attachment: DOMString. File with info about the mms attachment.

    Parameters
    • propertyName: DOMString containing the name of the property to be queried.
    Return value
    Boolean containing the value of that property (store, read) integer containing the value of that property ( folder) Date containing the value of the creation or reception date of the MMS (datetime). DOMString containing the value of that property (body,recipients,id,attachment).
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        var body = mms.getProperty("body");
    setProperty

    Sets the value of any of the MMS message object properties. (body, subject, store, attachment, recipients).

    Signature
    void setProperty(in DOMString propertyName, in Object propertyValue);
    Parameters
    • propertyName: DOMString containing the name of the property to be set.
    • propertyValue: DOMString (body, subject, recipients, attachment), Boolean (store), containing the value of the property to be set.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid property is introduced like a param

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var MMS = bondi.messaging.createMMS(null);
        MMS.setProperty("body", "Just arrived in Huesca");
    getRecipients

    Gets the list of recipients added to this message.

    Signature
    StringArray getRecipients();
    Return value
    StringArray of String containing each one of the recipients for this message (telephone numbers).
    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        var recipients = mms.getRecipients();
        alert(recipients.count + " recipients";
    getRecipient

    Gets a recipient from the list of recienpients.

    Signature
    DOMString getRecipient(in unsigned long index);
    Parameters
    • index: an unsigned long integer pointing the position of the recipient to be retrieved.
    Return value
    DOMString containing the telephone number (telephone numbers).
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided (e.g. the requested recipient index is out of bounds

    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        alert(MMS.getRecipient(0));
    appendRecipient

    Adds (appends) a new recipient to the list.

    Signature
    void appendRecipient(in DOMString phoneNumber);
    Parameters
    • phoneNumber: a DOMString containing the phone number of the recipient to be added.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided (e.g. if the parameter provided represents an invalid destination or if the phone number provided is larger than the max available size

    Code example
            var MMS = bondi.messaging.createMMS(null);
        MMS.appendRecipient("+34666666666");
    clearRecipients

    Removes the entire recipients list

    Signature
    void clearRecipients();
    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        mms.clearRecipients();
    getAttachments

    Gets the list of attachments added to this message.

    Signature
    StringArray getAttachments();
    Return value
    StringArray an array of files containing the path for each one of the files attached concatenated with the mime type and separated by ;.
    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        var attachments = getAttachments();
        alert(attachments[0]);
    getAttachment

    Gets an attachment from the list of added attachments.

    Signature
    DOMString getAttachment(in unsigned short index);
    Parameters
    • index: an integer pointing to the position of the attachment to be retrieved.
    Return value
    DOMString containing the path for the file attached concatenated with the mime type and separated by ;.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided (e.g. the requested recipient index is out of bounds)

    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        alert(getAttachment(0));
    appendAttachment

    Adds a file to the attachment list of the message.

    Signature
    void appendAttachment(in DOMString myAttachment);
    Parameters
    • myAttachment: a String containing the path of the file to be attached.
    Exceptions
    • SecurityError:

      PERMISSION_DENIED_ERROR when access is denied by the security policy.

    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    API features
    http://bondi.omtp.org/api/messaging.mms.attach
    Code example
            var mms = bondi.messaging.createMMS();
        mms.appendAttachment("\Huesca.jpg");
    clearAttachments

    Removes the entire attachments list

    Signature
    void clearAttachments();
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var mms =bondi.messaging.createMMS({recipients:"+34666666666", subject:"Hello from Huesca", body:"How Are You?", attachments:"\Huesca.jpg", store:false});
        mms.clearAttachments();

    3.10. Email

    Email Message API 

            interface Email {

                DOMString getProperty(in DOMString propertyName)
                        raises(DeviceAPIError);



                void setProperty(in DOMString propertyName, in DOMString propertyValue)
                        raises(DeviceAPIError);

                readonly attribute DOMString id;

                readonly attribute Date datetime;

                attribute DOMString from
                        setraises(DeviceAPIError);

                StringArray getToList();


                StringArray getCCList();


                StringArray getBCCList();


                 attribute DOMString body
                        setraises(DeviceAPIError);

                attribute boolean store
                        setraises(DeviceAPIError);

                readonly attribute unsigned short folder;

                attribute DOMString subject
                        setraises(DeviceAPIError);

                readonly attribute boolean read;

                void appendTo(in DOMString emailAddress)
                        raises(DeviceAPIError);


                void clearTo();


                void appendCC(in DOMString emailAddress)
                        raises(DeviceAPIError);



                void clearCC();


                void appendBCC(in DOMString emailAddress)
                        raises(DeviceAPIError);

                void clearBCC();


                StringArray getAttachments();


                DOMString getAttachment(in unsigned short index)
                        raises(DeviceAPIError);


                void appendAttachment(in DOMString myAttachment)
                        raises(SecurityError, DeviceAPIError);

                void clearAttachments();

        };

    The Email Message interface provides methods to populate and send an email message.

    Code example
             bondi.requestFeature(successFunc,failureFunc, 'messaging');

    Attributes

    readonly DOMString id

    Unique identifier assigned to the message in the platform.

    Code example
            var email = bondi.messaging.createEmail(null);
        var id = email.id;
    readonly Date datetime

    String that contains the datetime where the Email was sent or received or created in draft, depending the storage folder.

    Code example
            var email = bondi.messaging.createEmail(null);
        var dateTime = email.datetime;
    DOMString from

    Email account that is being used to send the message.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if the value isn't an email address

    • Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?", store:true});
        var account = email.from;
    DOMString body

    Gets the body of the email

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if body value isn't a string

    • Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        alert(email.body);
    boolean store

    Property that indicates whether the message is going to be stored in the SENT folder once sent.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if store value isn't a boolean

    • Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        alert(email.store);
    readonly unsigned short folder

    Folder where the message is stored.

    This attribute will be one of INBOX_FOLDER, OUTBOX_FOLDER, SENT_FOLDER, DRAFTS_FOLDER defined in MessagingManager.

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        alert(email.folder);
    DOMString subject

    Message subject.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if subject value isn't a string

    • Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        alert(email.subject);
    readonly boolean read

    Value that indicates if the message has already been read

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        var isRead = email.read;

    Methods

    getProperty

    Gets the value of the Email message object properties.

    Signature
    DOMString getProperty(in DOMString propertyName);


    Supported properties
    from: String. It's the address used to send the email. It must be configured on the default messaging application of the phone. Addresses look like xxx@yyy.zzz
    recipients: String. Semicolom(;) separated string containing the recipients list. Addresses look like xxx@yyy.zzz
    cc: String. Semicolom(;) separated string containing the cc recipients list. Addresses look like xxx@yyy.zzz
    bcc: String. Semicolom(;) separated string containing the bcc recipients list. Addresses look like xxx@yyy.zzz
    subject: String. Resume of the email content.
    body: String. Email text.
    store: Boolean. Indicates if the email will be stored in the sent messages folder. True -> Stored
    read: Boolean. Indicates if the email has been readen(true) or not(false)
    id: String. Identification of the email
    datetime: Date object which stores the date when the email was created
    folder: Integer. It indicates the folder where the email is stored (must be one of INBOX_FOLDER, OUTBOX_FOLDER, SENT_FOLDER, DRAFTS_FOLDER defined in MessagingManager).

    Parameters
    • propertyName: DOMString containing the name of the property to be queried.
    Return value
    DOMString containing the value of that property.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid property is introduced like a param.

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?",attachments:"\Huesca.jpg",store:true});
        var body = email.getProperty("body");
    setProperty

    Sets the value of any of the Email message object properties.

    Signature
    void setProperty(in DOMString propertyName, in DOMString propertyValue);
    Parameters
    • propertyName: DOMString containing the name of the property to be set.
    • propertyValue: DOMString (recipients, cc, bcc, subject, body, from) or Boolean (store)containing the value of the property to be set.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?",attachments:"\Huesca.jpg",store:true});
        email.setProperty("body", "Just arrived in Huesca");
    getToList

    Gets the list of recipients added to this message in the To field.

    Signature
    StringArray getToList();
    Return value
    StringArray an array of DOMString containing each one of the recipients in the To field for this message (email addresses).
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?", store:true});
        var recipients = email.getToList();
        alert(recipients[0]);
    getCCList

    Gets the list of recipients added to this message in the CC field.

    Signature
    StringArray getCCList();
    Return value
    StringArray array of DOMString containing each one of the recipients in the CC field for this message (email addresses).
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?", store:true});
        var recipients = email.getCCList();
        alert(recipients[0]);
    getBCCList

    Gets the list of recipients added to this message in the BCC field.

    Signature
    StringArray getBCCList();
    Return value
    StringArray an array of String containing each one of the recipients in the BCC field for this message (email addresses).
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?", store:true});
        var recipients = email.getBCCList();
        alert(recipients[0]);
    appendTo

    Adds (appends) a new recipient to the list.

    Signature
    void appendTo(in DOMString emailAddress);
    Parameters
    • emailAddress: a DOMString containing the email address of the recipient to be added.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided (e.g. if destination hasn't an email address format)

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        email.appendTo("guillermo.caudevilla@vodafone.com");
    clearTo

    Removes the entire To's list

    Signature
    void clearTo();
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        email.clearTo();
    appendCC

    Adds (appends) a new recipient to the CC list.

    Signature
    void appendCC(in DOMString emailAddress);
    Parameters
    • emailAddress: a DOMString containing the email address of the recipient to be added.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",cc:"ester@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        email.appendCC("guillermo.caudevilla@vodafone.com");
    clearCC

    Removes the entire CCs list

    Signature
    void clearCC();
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",cc:"ester@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        email.clearCC();
    appendBCC

    Adds (appends) a new recipient to the BCC list.

    Signature
    void appendBCC(in DOMString emailAddress);
    Parameters
    • emailAddress: a String containing the email address of the recipient to be added.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",bcc:"ester@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        email.appendBCC("guillermo.caudevilla@vodafone.com");
    clearBCC

    Removes the entire BCCs list

    Signature
    void clearBCC();
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com",bcc:"ester@gmail.com",subject:"Hello from Huesca",body:"How Are You?",store:true});
        email.clearBCC();
    getAttachments

    Gets the list of attachments added to this message.

    Signature
    StringArray getAttachments();
    Return value
    StringArray an array of Files containing the email attachments.
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?",attachments:"\Huesca.jpg",store:true});
        var attachments = email.getAttachments();
        alert(attachments[0]);
    getAttachment

    Gets an attachment from the list of added attachments.

    Signature
    DOMString getAttachment(in unsigned short index);
    Parameters
    • index: an integer pointing to the position of the attachment to be retrieved.
    Return value
    String containing the file path.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?",attachments:"\Huesca.jpg",store:true});
        alert(getAttachment(0));
    appendAttachment

    Adds a file to the attachment list of the message.

    Signature
    void appendAttachment(in DOMString myAttachment);
    Parameters
    • myAttachment: The file to be attached.
    Exceptions
    • SecurityError:

      PERMISSION_DENIED_ERROR when access is denied by the security policy.

    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    API features
    http://bondi.omtp.org/api/messaging.email.attach
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?",attachments:"\Huesca.jpg",store:true});
        email.appendAttachment("\Walqa.jpg");
    clearAttachments

    Removes the entire attachments list

    Signature
    void clearAttachments();
    Code example
            var email = bondi.messaging.createEmail({from:"pfracat@corp.vodafone.es",to:"pedro@gmail.com", cc:"pabasa1@corp.vodafone.es",bcc:"guillermo.caudevilla@vodafone.com",subject:"Hello from Huesca",body:"How Are You?",attachments:"\Huesca.jpg",store:true});
        email.clearAttachments();

    3.11. SMSOptions

    Options for SMS creation 

            [NoInterfaceObject, Callback] interface SMSOptions{
       
        attribute DOMString body;

        attribute DOMString recipients;

        attribute boolean store;
    };

    All the attributes are by default, undefined

    Attributes

    DOMString body

    SMS body

    DOMString recipients

    SMS recipients

    Semicolom(;) separated string containing the recipient list

    boolean store

    SMS storage configuration

    If set to true indicates that the message must be stored in the SENT folder once sent.

    3.12. MMSOptions

    Options for MMS creation 

        [NoInterfaceObject, Callback] interface MMSOptions {
       
        attribute DOMString body;
       
        attribute DOMString recipients;
       
        attribute StringArray attachments;

        attribute boolean   store;
    };

    All the attributes are by default, undefined

    Attributes

    DOMString body

    MMS body

    DOMString recipients

    MMS recipients

    Semicolom(;) separated string containing the recipient list

    StringArray attachments

    List of MMS attachments

    boolean store

    MMS storage configuration

    If set to true indicates that the message must be stored in the SENT folder once sent.

    3.13. EmailOptions

    Options for Email creation 

        [NoInterfaceObject, Callback] interface EmailOptions {
        attribute DOMString from;

        attribute DOMString to;

        attribute DOMString cc;

        attribute DOMString bcc;

        attribute DOMString subject;

        attribute DOMString body;

        attribute StringArray attachments;

        attribute boolean   store;
    };

    All the attributes are by default, undefined

    Attributes

    DOMString from

    Origin address for the e-mail

    DOMString to

    E-mail addresses to be included in the TO field

    Semicolom(;) separated string containing the e-mail addresses

    DOMString cc

    E-mail addresses to be included in the CC field

    Semicolom(;) separated string containing the e-mail addresses

    DOMString bcc

    E-mail addresses to be included in the BCC field

    Semicolom(;) separated string containing the e-mail addresses

    DOMString subject

    E-mail's subject

    DOMString body

    E-mail's body

    StringArray attachments

    List of E-mail attachments

    boolean store

    E-mail storage configuration

    If set to true indicates that the message must be stored in the SENT folder once sent.

    3.14. BinaryMessageOptions

    Options for Binary Message creation 

        [NoInterfaceObject, Callback] interface BinaryMessageOptions {
         attribute DOMString recipients;

         attribute unsigned short port;

         attribute ByteArray payload;
     };

    Attributes

    DOMString recipients

    Semicolom (;) separated string containing the recipient addresses

    unsigned short port

    Port to which the binary message will be sent

    ByteArray payload

    Message payload

    3.15. BinaryMessage

    Binary Message API 

            interface BinaryMessage {

                Object getProperty(in DOMString propertyName)
                        raises(DeviceAPIError);

                void setProperty(in DOMString propertyName, in DOMString propertyValue)
                        raises(DeviceAPIError);

                 attribute ByteArray payload
                        setraises(DeviceAPIError);

                readonly attribute unsigned short port;


                StringArray getRecipients();

                DOMString getRecipient(in unsigned short index)
                        raises(DeviceAPIError);

                void appendRecipient(in DOMString phoneNumber)
                        raises(DeviceAPIError);

                void clearRecipients();
        };

    The Binary Message interface provides methods to populate and send a binary message.

    Code example
            bondi.requestFeature(successCB, errorCB, "bondi.messaging");

    Attributes

    ByteArray payload

    String that contains the payload of the Binary message.

  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if invalid value is given to body

    • Code example
            var binary = bondi.messaging.createBinaryMessage({recipients:"+34666666666",payload:bytes,port:25678});
        ...
        file.write(binary.payload);
    readonly unsigned short port

    Integer that indicates the port to which the Binary message is to be addressed.

    Code example
            var binary = bondi.messaging.createBinaryMessage({recipients:"+34666666666",payload:bytes,port:25678});
        alert(binary.port);

    Methods

    getProperty

    Returns the value of any of the Binary message object properties.

    Signature
    Object getProperty(in DOMString propertyName);

    Supported properties
    payload: ByteArray. This represents the payload of the binary message
    recipients: String. Semicolom(;) separated string containing the recipients list
    port: integer. Port to which the binary message is to be addressed.

    Parameters
    • propertyName: DOMString containing the name of the property to be queried.
    Return value
    Int containing the value of that property when property is port. ByteArray containing the value of that property when property is payload. Object containing the value of that property when properties are recipients.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

    Code example
            var binary = bondi.messaging.createBinary();
        binary.port = 25678;
        var port = binary.getProperty("port");
    setProperty

    n Sets the value of any of the Binary message object properties. (payload, port).

    Signature
    void setProperty(in DOMString propertyName, in DOMString propertyValue);
    Parameters
    • propertyName: DOMString containing the name of the property to be set.
    • propertyValue: Integer ('port') or ByteArray ('payload') containing the value of the property to be set.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter is provided to this function

    Code example
            var binary = bondi.messaging.createBinary();
        binary.setProperty("port", 25678);
    getRecipients

    This method returns the list of recipients added to the Binary message

    Signature
    StringArray getRecipients();
    Return value
    Array of String containing each one of the recipients for this message (telephone numbers).
    Code example
            var binary =  bondi.messaging.createBinaryMessage({recipients:"+34666666666",payload:bytes,port:25678});
        var recipients = binary.getRecipients();
        alert(recipients.count + " recipients";
    getRecipient

    Gets a recipient from the list of recipients.

    Signature
    DOMString getRecipient(in unsigned short index);
    Parameters
    • index: an integer pointing the position of the recipient to be retrieved.
    Return value
    a DOMString containing the telephone number (telephone numbers).
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided

    Code example
            var binary =  bondi.messaging.createBinaryMessage({recipients:"+34666666666",payload:bytes,port:25678});
        alert(binary.getRecipient(0));
    appendRecipient

    Adds (appends) a new recipient to the list. This recipient must be a phone number format.

    Signature
    void appendRecipient(in DOMString phoneNumber);
    Parameters
    • phoneNumber: a DOMString containing the phone number of the recipient to be added.
    Exceptions
    • DeviceAPIError:

      INVALID_ARGUMENT_ERROR if an invalid parameter has been provided (e.g. if the parameter provided represents an invalid destination or if the phone number provided is larger than the max available size

    Code example
            var binary = bondi.messaging.createBinaryMessage(null);
        binary.appendRecipient("+34666666666");
    clearRecipients

    Removes the entire recipients list.

    Signature
    void clearRecipients();
    Code example
            var binary =  bondi.messaging.createBinary({recipients:"+34666666666",payload:bytes,port:25678});
        binary.clearRecipients();

    3.16. IncomingSMSEventFilter

    Defines the parameters used to filter incoming SMS notifications 

        [Callback, NoInterfaceObject] interface IncomingSMSEventFilter {

           attribute unsigned long port;

           attribute DOMString sender;
    };
    Code example
            var id = bondi.messaging.subscribeToSMS(
         {onSMS:function(sms) {alert("Incoming SMS: "+ sms.body);}}, 
         {sender:666666666},
         true);

  bondi.messaging.unsubscribeFromSMS(id);

    Attributes

    unsigned long port

    Port in which the SMS was received

    DOMString sender

    SMS Sender

    3.17. IncomingMMSEventFilter

    Defines the parameters used to filter incoming MMS notifications 

        [Callback, NoInterfaceObject] interface IncomingMMSEventFilter {

           attribute DOMString sender;

           attribute DOMString body;
    };
    Code example
            var id = bondi.messaging.subscribeToSMS(
         {onSMS:function(sms) {alert("Incoming SMS: "+ sms.body);}}, 
         {sender:666666666},
         true);

  bondi.messaging.unsubscribeFromSMS(id);

    Attributes

    DOMString sender

    SMS sender

    DOMString body

    String to be found in the MMS Body

    3.18. IncomingEmailEventFilter

    Defines the parameters used to filter incoming email notifications 

        [Callback, NoInterfaceObject] interface IncomingEmailEventFilter {

           attribute DOMString sender;

           attribute DOMString subject;
    };
    Code example
            var id = bondi.messaging.subscribeToEmail(
         {onEmail:function(email) {alert("Incoming E-mail: "+ email.body);}}, 
         {subject:test},
         true);

  bondi.messaging.unsubscribeFromEmail(id);

    Attributes

    DOMString sender

    Sender of the e-mail

    DOMString subject

    Subject of the e-mail

    3.19. MessagingManagerObject

    Specifies what is instantiated at feature request 

            interface MessagingManagerObject {
                readonly attribute MessagingManager messagingManager; 
        };
            Bondi implements MessagingManagerObject;