Bondi logo

The Bondi Communication Log Module: bondi.commlog - Version 1.01

27 July 2009

Authors


Abstract

List message- and call-logs on the device and access their content and meta-information.

Table of Contents


Summary of Methods

InterfaceMethod
CommLogSMSSuccessCallbackvoid onSuccess(SMSArray obj)
CommLogMMSSuccessCallbackvoid onSuccess(MMSArray obj)
CommLogEmailSuccessCallbackvoid onSuccess(EmailArray obj)
CommLogCallSuccessCallbackvoid onSuccess(CallArray obj)
CommLogManagerPendingOperation getSMSLog(CommLogSMSSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray messageFolders, Map filter)
PendingOperation getMMSLog(CommLogMMSSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray messageFolders, Map filter)
PendingOperation getEmailLog(CommLogEmailSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray messageFolders, Map filter)
PendingOperation getCallLog(CommLogCallSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray callFolder, Map filter)
StringArray getSMSSupportedPropertyKeys()
StringArray getMMSSupportedPropertyKeys()
StringArray getEmailSupportedPropertyKeys()
StringArray getCallSupportedPropertyKeys()
Call

1. Introduction

This API provides access to information on recent calls (missed, received, and initiated) and messages (sent, received, drafts, and outbox). The information contain all meta-information related to the according message and call, respectively. These meta-information may include the title and recipients of a message or the telephone number and date of a call.

This API does not provide event notifications for incoming messages or incoming calls. Thus, the application is not able to subscribe for a callback in the event of an incoming message or call, but rather has the possibility to request the current list of calls and messages. In order to react on incoming messages, the application may request the commlog on a short periodical basis.

However, the listing of messages/calls can be filtered in order to reduce the effort for the using application and to fasten the identification of relevant entries (i.e. messages and calls).

As this API is a read-only API with no possibility to send messages or to establish a call, the BONDI messaging API (and later telephony API, respectively) should be used to create new messages (and calls, respectively) and send them to single or multiple receivers.

1.1. 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 provided is provided.

http://bondi.omtp.org/api/commlog.sms.get

Call to CommLogManager.getSMSLog

Device capabilities: commlog.sms.get

http://bondi.omtp.org/api/commlog.mms.get

Call to CommLogManager.getMMSLog

Device capabilities: commlog.mms.get

http://bondi.omtp.org/api/commlog.email.get

Call to CommLogManager.getEmailLog

Device capabilities: commlog.email.get

http://bondi.omtp.org/api/commlog.call.get

Call to CommLogManager.getCallLog

Device capabilities: commlog.call.get

1.2. Device capabilities

commlog.sms.get

Get entries from SMS log

commlog.mms.get

Get entries from MMS log

commlog.email.get

Get entries from email log

commlog.call.get

Get entries from call log

2. Type Definitions

2.1. SMSArray

Array of SMS.

        typedef sequence<SMS> SMSArray;

2.2. MMSArray

Array of MMS.

        typedef sequence<MMS> MMSArray;

2.3. EmailArray

Array of Email.

        typedef sequence<Email> EmailArray;

2.4. CallArray

Array of Call.

        typedef sequence<Call> CallArray;

3. Interfaces

3.1. CommLogSMSSuccessCallback

Success callback for retrieving a list of SMS.

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

Success callback that takes an array of SMSs as input argument. It is used in the asynchronous operation to get the SMS Log.

Methods

onSuccess

Method invoked when a list of SMSs is retrieved succesfully

Signature
void onSuccess(SMSArray obj);
Parameters
  • obj: The list of SMSs

3.2. CommLogMMSSuccessCallback

Success callback for retrieving a list of MMS.

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

Success callback that takes an array of MMSs as input argument. It is used in the asynchronous operation to get the MMS Log.

Methods

onSuccess

Method invoked when a list of MMSs is retrieved succesfully

Signature
void onSuccess(MMSArray obj);
Parameters
  • obj: The list of MMSs

3.3. CommLogEmailSuccessCallback

Success callback for retrieving a list of E-mails.

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

Success callback that takes an array of E-mails as its input argument. It is used in the asynchronous operation to get the E-Mail log.

Methods

onSuccess

Method invoked when a list of e-mails is retrieved succesfully

Signature
void onSuccess(EmailArray obj);
Parameters
  • obj: The list of e-mails

3.4. CommLogCallSuccessCallback

Success callback for retrieving a list of Calls.

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

Success callback that takes an array of Calls as input argument. It is used in the asynchronous operation to get the list of Calls.

Methods

onSuccess

Method invoked when a list of calls is retrieved succesfully

Signature
void onSuccess(CallArray obj);
Parameters
  • obj: The list of calls

3.5. CommLogManager

Communication Log API.

        interface CommLogManager {

                const unsigned short INBOX_FOLDER = 0;

                const unsigned short OUTBOX_FOLDER = 1;

                const unsigned short SENT_FOLDER  = 2;

                const unsigned short DRAFT_FOLDER = 3;

                const unsigned short MISSED_CALLS_FOLDER = 0;

                const unsigned short RECEIVED_CALLS_FOLDER = 1;

                const unsigned short INITIATED_CALLS_FOLDER = 2;

                PendingOperation getSMSLog(in CommLogSMSSuccessCallback successCallback,
                                           in ErrorCallback errorCallback,
                                           in ShortArray messageFolders,
                                           [Optional]in Map filter)
                        raises(SecurityError, DeviceAPIError);


                PendingOperation getMMSLog(in CommLogMMSSuccessCallback successCallback,
                                           in ErrorCallback errorCallback,
                                           in ShortArray messageFolders,
                                           [Optional]in Map filter)
                        raises(SecurityError, DeviceAPIError);


                PendingOperation getEmailLog(in CommLogEmailSuccessCallback successCallback,
                                             in ErrorCallback errorCallback,
                                             in ShortArray messageFolders,
                                             [Optional]in Map filter)
                        raises(SecurityError, DeviceAPIError);


                PendingOperation getCallLog(in CommLogCallSuccessCallback successCallback,
                                            in ErrorCallback errorCallback,
                                            in ShortArray callFolder,
                                            [Optional]in Map filter)
                        raises(SecurityError, DeviceAPIError);

                StringArray getSMSSupportedPropertyKeys();

                StringArray getMMSSupportedPropertyKeys();

                StringArray getEmailSupportedPropertyKeys();

                StringArray getCallSupportedPropertyKeys();
        };

The communication logs manager interface offers methods to retrieve information from the Inbox, Outbox and call registry.

Code example
        // Define the getSMSLog success callback.
        function smsSuccessCallback(response) {
                var messages = response;
                // Get first message in the list of results
                var sms = messages[0];
        }

        // Define the requestFeature success callback.
        function successCallback(response) {
                bondi.commlog.getSMSLog(smsSuccessCallback, errorCallback,
                        { bondi.commlog.INBOX_FOLDER, bondi.commlog.OUTBOX_FOLDER},
                        { Recipient:"+34666666666", Body:"Huesca"});
        }

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

        // Request the commlog feature.
        bondi.requestFeature(successCallback, errorCallback, "commlog");
 

Constants

unsigned short INBOX_FOLDER

Folder message constants definition

unsigned short OUTBOX_FOLDER

Folder containing messages to be sent.

unsigned short SENT_FOLDER

Folder containing sent messages.

unsigned short DRAFT_FOLDER

Folder containing drafts.

unsigned short MISSED_CALLS_FOLDER

Folder of missed calls.

unsigned short RECEIVED_CALLS_FOLDER

Folder with received calls.

unsigned short INITIATED_CALLS_FOLDER

Folder with initiated calls.

Methods

getSMSLog

Get the list of selected SMSs

Signature
PendingOperation getSMSLog(CommLogSMSSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray messageFolders, Map filter);

Gets an array of SMSMessages objects for sms messages stored within the selected folders and matching the selected filter.

This is an asynchronous method.

In a search using this method, if more than one value is used, then the AND operator will be used betwwen all values to perform the search.

In a search using strings, the search conductes is case sensitive. If the string is found anywhere inside the key object value, the entire object will be returned.

Parameters
  • successCallback: function called when the invocation ends successfully, the response object is used to retrieve the array of SMS objects.
  • errorCallback: function called when an error occurs, the input parameter is an Error object with a code giving information about the type of error that occurred.
  • messageFolders: Array of ints stating in which message folders the web app has to look for messages. It can't be null. Array values must be 0 (INBOX_FOLDER),1 (SENT_FOLDER),2 (OUTBOX_FOLDER) or 3 (DRAFT_FOLDER).
  • filter: Array of key-value pairs acting as a filter for searching messages. Supported keys:
    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
    Supported keys are also returned in a string array by getSMSSupportedPropertyKeys.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR if parameters are not valid If parameters are not valid If folder isn't one of the following: INBOX_FOLDER,SENT_FOLDER, OUTBOX_FOLDER or DRAFT_FOLDER If some of the filter parameters are not supported
API features
http://bondi.omtp.org/api/commlog.sms.get
Code example
        // Define the success callback.
        function successCallback(response) {
                var messages = response;
                // Get first message in the list of results
                var sms = messages[0];
        }

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

        // Get the SMS log for the specified filter.
        bondi.commlog.getSMSLog(successCallback, errorCallback,
                { bondi.commlog.INBOX_FOLDER, bondi.commlog.OUTBOX_FOLDER},
                { Recipient:"+34666666666", Body:"Huesca"});
 
getMMSLog

Get the list of selected MMSs

Signature
PendingOperation getMMSLog(CommLogMMSSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray messageFolders, Map filter);

Gets an array of MMSMessage objects for MMS messages stored within the selected folders matching the selected filter.

In a search using this method, if more than one value is used, then the AND operator will be used betwwen all values to perform the search.

In a search using strings, the search conductes is case sensitive. If the string is found anywhere inside the key object value, the entire object will be returned.

This is an asynchronous method.

Parameters
  • successCallback: function called when the invocation ends successfully, use response object to retrieve the array of MMS objects.
  • errorCallback: function called when an error occurs, the input parameter is an Error object with a code giving information about the type of error that occurred.
  • messageFolders: Array of ints stating in which message folders the web app has to look for messages. It can't be null. Array values must be 0 (INBOX_FOLDER),1 (SENT_FOLDER),2 (OUTBOX_FOLDER) or 3 (DRAFT_FOLDER).
  • filter: Array of key-value pairs acting as a filter for searching messages. Supported keys:
    body: String. This represents the body of the mms as defined in
    recipients: String. Semicolom(;) separated string containing the recipients' addresses as defined
    store: Boolean. Indicates if the mms will be stored in the sent messages folder. True -> Stored
    attachments: String with the file name or path. It's the file attached to the mms.
    Supported keys are also returned in a string array by getMMSSupportedPropertyKeys method
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR If parameters are not valid If folder isn't one of the following: INBOX_FOLDER,SENT_FOLDER, OUTBOX_FOLDER or DRAFT_FOLDER If some of the filter parameters are not supported.
API features
http://bondi.omtp.org/api/commlog.mms.get
Code example
        // Define the success callback.
        function successCallback(response) {
                var messages = response;
                // Get first MMS in the list of results
                var mms = messages[0];
        }

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

        // Get the MMS log for the specified filter.
        bondi.commlog.getMMSLog(successCallback, errorCallback,
                { bondi.commlog.INBOX_FOLDER, bondi.commlog.OUTBOX_FOLDER},
                {Recipient:"+34666666666", Body:"Huesca"});
 
getEmailLog

Get the list of selected Emails

Signature
PendingOperation getEmailLog(CommLogEmailSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray messageFolders, Map filter);

In a search using this method, if more than one value is used, then the AND operator will be used betwwen all values to perform the search.

In a search using strings, the search conductes is case sensitive. If the string is found anywhere inside the key object value, the entire object will be returned.

Parameters
  • successCallback: function called when the invocation ends successfully, the response object is used to retrieve the array of Strings containing message IDs.
  • errorCallback: function called when an error occurs, the input parameter is an Error object with a code giving information about the type of error that occurred.
  • messageFolders: Array of Ints stating in which message folders the web app should look for messages.It can't be null. Array values must be 0 (INBOX_FOLDER),1 (SENT_FOLDER),2 (OUTBOX_FOLDER) or 3 (DRAFT_FOLDER).
  • filter: Array of key-value pairs acting as a filter for searching messages.
    from: String. The address used to send the email. It must be configured on the default messaging application of the phone. Addresses should be of the format defined in RFC 5322 3.4
    to: String. Semicolom(;) separated string containing the recipients list. Addresses should be of the format defined in RFC 5322 3.4
    cc: String. Semicolom(;) separated string containing the cc recipients list. Addresses should be of the format defined in RFC 5322 3.4
    bcc: String. Semicolom(;) separated string containing the bcc recipients list. Addresses should be of the format defined in RFC 5322 3.4
    subject: String. Resume of the email content in the format defined in RFC 5322 2.2
    body: String. Email text in the format defined in RFC 5322 2.3
    attachments: String with the file name or path. It's the file attached to the email.
    store: Boolean. Indicates if the mms will be stored in the sent messages folder. True -> Stored Supported keys are also returned in a string array by getEmailSupportedPropertyKeys method.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR If parameters are not valid. If folder isn't one of the following: INBOX_FOLDER,SENT_FOLDER, OUTBOX_FOLDER or DRAFT_FOLDER. If some of the filter parameters are not supported.
API features
http://bondi.omtp.org/api/commlog.email.get
Code example
        // Define the success callback.
        function successCallback(response) {
                var messages = response;
                // Get first email in the list of results
                var email = messages[0];
        }

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

        // Get the Email log for the specified filter.
        bondi.commlog.getEmailLog(successCallback, errorCallback,
                { bondi.commlog.INBOX_FOLDER, bondi.commlog.OUTBOX_FOLDER},
                { Recipient:"+34666666666", Body:"Huesca"});
 
getCallLog

Get the list of selected Calls

Signature
PendingOperation getCallLog(CommLogCallSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray callFolder, Map filter);

Gets an array of Call objects for calls stored within the selected folders and matching the selected filter.

In a search using this method, if more than one value is used, then the AND operator will be used betwwen all values to perform the search.

In a search using strings, the search conductes is case sensitive. If the string is found anywhere inside the key object value, the entire object will be returned.

This is an asynchronous method.

Parameters
  • successCallback: function called when the invocation ends successfully, the response object is used to retrieve the array of Strings containing call IDs.
  • errorCallback: function called when an error occurs, the input parameter is an Error object with a code giving information about the type of error that occurred.
  • callFolder: Array of Ints stating in which message folders the web app should loook for calls. It can't be null. Array values must be 0 (MISSED_CALLS_FOLDER),1(RECEIVED_CALLS_FOLDER) or 2(INITIATED_CALLS_FOLDER).
  • filter: Array of key-value pairs acting as a filter for searching calls. Supported keys:
    phoneNumber: String. The destination or the caller phone number
    startTime: Date. The datetime when the call was done, receieved or missed.
    duration: Long. Time in seconds with the duration of the call Supported keys are returned in a string array by getCallSupportedPropertyKeys.
Return value
PendingOperation in order to cancel the async call.
Exceptions
  • SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError: INVALID_ARGUMENT_ERROR If parameters are not valid. If folder isn't one of the following: MISSED_CALLS_FOLDER, RECEIVED_CALLS_FOLDER or INITIATED_CALLS_FOLDER. If some of the filter parameters are not supported.
API features
http://bondi.omtp.org/api/commlog.call.get
Code example
        // Define the success callback.
        function successCallback(response)
        {
                // Get first call in the list of results
                var myCall = response[0];
        }

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

        // Get the call log for the specified filter.
        var callsArray = new Array();
        callsArray.push(bondi.commlog.MISSED_CALLS_FOLDER);
        callsArray.push(bondi.commlog.RECEIVED_CALLS_FOLDER);
        bondi.commlog.getCallsLog(successCallback,errorCallback,callsArray, {phoneNumber:"+34666666666"});
 
getSMSSupportedPropertyKeys

Get the property keys of SMSs

Signature
StringArray getSMSSupportedPropertyKeys();

This method returns a list of the public SMS property keys. That is to say it returns all the parameters we can use to create an SMS (body, recipients, store...) and supported by the getSMSLog filter parameter.

Return value
Array of Strings containing the names of the message object public properties.
Code example
        var myBody = "New body for a draft message";
        var attributes = bondi.commlog.getSMSSupportedPropertyKeys();
        if (attributes[1] == "body") {
                var sms = bondi.messaging.createSMS();
                sms.setProperty(attributes[1],myBody);
        }
 
getMMSSupportedPropertyKeys

Get the property keys of MMSs

Signature
StringArray getMMSSupportedPropertyKeys();

This method returns a list of the public MMS property keys. That is to say it returns all the parameters we can use to create an MMS (body, recipients, store, attachments...) and supported by the getMMSLog filter parameter.

Return value
Array of Strings containing the names of the message object public properties.
Code example
        var myBody = "New body for a draft message";
        var attributes = bondi.commlog.getMMSSupportedPropertyKeys();
        if (attributes[1] == "body") {
                var mms = bondi.messaging.createMMS();
                mms.setProperty(attributes[1], myBody);
        }
 
getEmailSupportedPropertyKeys

Get the property keys of Emails

Signature
StringArray getEmailSupportedPropertyKeys();

This method returns a list of the public Email property keys. That is to say it returns all the parameters we can use to create an Email (body, subject, store, attachments...) and supported by the getEmaillLog filter parameter.

Return value
Array of Strings containing the names of the message object public properties.
Code example
        var myBody = "New body for a draft message";
        var attributes = bondi.commlog.getEmailSupportedPropertyKeys();
        if (attributes[1] == "body") {
                var email = bondi.messaging.createEmail();
                email.setProperty(attributes[1], myBody);
        }
 
getCallSupportedPropertyKeys

Gets the call attributes supported by the getCallLog filter parameter.

Signature
StringArray getCallSupportedPropertyKeys();
Return value
Array of Strings containing the names of the call object public properties.
Code example
        var attributes = bondi.commlog.getCallSupportedPropertyKeys();
        if (attributes[1] == "phoneNumber") {
                var phoneNumber = call.getProperty(attributes[1]);
        }
 

3.6. Call

Encapsulation of a call on the device.

        [Callback] interface Call {
                readonly attribute DOMString phoneNumber;

                readonly attribute Date startTime;

                readonly attribute unsigned long duration;

                readonly attribute DOMString id;

                readonly attribute unsigned short folder;
        };
Code example
        // Define the success callback.
        function successCallback(response) {
                var calls = response;
                // Get first phone number in the list of results
                alert(call[0].phoneNumber);
        }

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

        // Get the missed calls log.
        bondi.commlog.getCallLog(successCallback, errorCallback,
                { bondi.commlog.MISSED_CALLS_FOLDER},
                { phoneNumber:"+34666666666"});
 

Attributes

[readonly] DOMString phoneNumber

Phone number of the call object
String that contains the phone number that called or that was called (depending on the folder property).

This attribute is read-only.

Code example
        // Define the success callback.
        function successCallback(response) {
                var calls = response;
                // Get the phonenumber of the first call in the list of results
                alert(call[0].phoneNumber);
        }

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

        // Get the missed calls log.
        bondi.commlog.getCallLog(successCallback, errorCallback,
                { bondi.commlog.MISSED_CALLS_FOLDER},
                { phoneNumber:"+34666666666"});
 
[readonly] Date startTime

Date when the call started
Object containing date and time when the call took place.

This attribute is read-only.

Code example
        // Define a success callback.
        function successCallback(response) {
                alert(response[0].startTime);
        }

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

        // Get the missed calls log.
        bondi.commlog.getCallLog(successCallback, errorCallback,
                { bondi.commlog.MISSED_CALLS_FOLDER},
                { phoneNumber:"+34666666666"});
 
[readonly] unsigned long duration

Duration of the call
Integer which contains the duration of the call in seconds.

This attribute is read-only.

Code example
        // Define a success callback.
        function successCallback(response) {
                alert("The call lasted for " + response[0].duration + " seconds.");
        }

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

        // Get the missed calls log.
        bondi.commlog.getCallLog(successCallback, errorCallback,
                { bondi.commlog.MISSED_CALLS_FOLDER},
                { phoneNumber:"+34666666666"});
 
[readonly] DOMString id

Call identifier String containing the unique id of the call within the platform.

This attribute is read-only.

Code example
        // Define a success callback.
        function successCallback(response) {
                alert("This is the id for the first call in the log: " + response[0].id);
        }

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

 // Get the missed calls log.
        bondi.commlog.getCallLog(successCallback, errorCallback,
                { bondi.commlog.MISSED_CALLS_FOLDER},
                { phoneNumber:"+34666666666"});
 
[readonly] unsigned short folder

folder where the call was stored This property has access to the information about in which folder is the call stored. MISSED_CALLS_FOLDER=0, RECEIVED_CALLS_FOLDER=1 or INITIATED_CALLS_FOLDER=2

This attribute is read-only.

Code example
        // Define a success callback.
        function successCallback(response) {
                var calls = response;
                var call = calls[0];
                if (call.folder == bondi.commlog.MISSED_CALLS_FOLDER) alert("Missed call!");
        }

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

 // Get the missed calls log.
        bondi.commlog.getCallLog(successCallback, errorCallback,
                { bondi.commlog.MISSED_CALLS_FOLDER},
                { phoneNumber:"+34666666666"});