Bondi logo

The Bondi telephony Module - Version 1.1

February 2010

Authors


Abstract

List call-logs on the device.

Table of Contents


Summary of Methods

InterfaceMethod
LogManagerSuccessCallbackvoid onSuccess(LogEntries obj)
LogManagerPendingOperation findLogEntries(LogManagerSuccessCallback successCallback, ErrorCallback errorCallback, ShortArray callFolder, LogFilter filter)
unsigned long getNumberOfCalls(ShortArray callFolders)
PendingOperation deleteLogEntry(SuccessCallback successCallback, ErrorCallback errorCallback, DOMString callID, unsigned short folder)
PendingOperation clearLog(SuccessCallback successCallback, ErrorCallback errorCallback, unsigned short callFolder)
LogEntry
LogFilter
LogManagerObject

1. Introduction

Copyright 2010 OMTP Ltd.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

In this version, this API contains only log-related features. In future versions this API will also be used to manage phone calls.

This API provides access to information on recent calls (missed, received, and initiated). The information contain all meta-information related to the according call. These meta-information may include the telephone number and date of a call.

This API does not provide event notifications incoming calls. Thus, the application is not able to subscribe for a callback in the event of an incoming call, but rather has the possibility to request the current list of calls.

However, the listing of calls can be filtered in order to reduce the effort for the using application and to fasten the identification of relevant entries.

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/1.1/telephony

All the telephony features

Includes API features:

  • http://bondi.omtp.org/api/1.1/telephony.log.get
  • http://bondi.omtp.org/api/1.1/telephony.log.delete

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 LogManager is instantiated, and the resulting object appears in the global namespace as Bondi.telephonyLog.

http://bondi.omtp.org/api/1.1/telephony.log.get

Call to CallManager.findLogEntries

Device capabilities:

  • telephony.log.get
http://bondi.omtp.org/api/1.1/telephony.log.delete

Call to CallManager.deleteLogEntry and CallManager.clearLog

Device capabilities:

  • telephony.log.delete

1.3. Device capabilities

telephony.log.get

Get entries from call log

Security parameters:

  • folders: Space-separated list of folder identifiers from which the call entries are to be retrieved.
telephony.log.delete

Delete call log entries from a log

Security parameters:

  • folder: Folder identifier from which the call log entry/entries is/are to be deleted.

2. Type Definitions

2.1. LogEntries

Array of call log entries.

        typedef sequence<LogEntry> LogEntries;

3. Interfaces

3.1. LogManagerSuccessCallback

Success callback for retrieving a list of Calls.

        [Callback=FunctionOnly, NoInterfaceObject] interface LogManagerSuccessCallback {
                void onSuccess(in LogEntries 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 successfully

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

3.2. LogManager

Call Log Manager API.

        interface LogManager {

                const unsigned short MISSED_CALLS_FOLDER = 0;

                const unsigned short RECEIVED_CALLS_FOLDER = 1;

                const unsigned short INITIATED_CALLS_FOLDER = 2;


                PendingOperation findLogEntries(in LogManagerSuccessCallback successCallback,
                                in ErrorCallback errorCallback,
                                in ShortArray callFolder,
                                [Optional] in LogFilter filter);

                unsigned long getNumberOfCalls(in ShortArray callFolders)
                        raises(DeviceAPIError);


                PendingOperation deleteLogEntry(in SuccessCallback successCallback,
                                in ErrorCallback errorCallback,
                                in DOMString callID, in unsigned short folder);

        PendingOperation clearLog(in SuccessCallback successCallback,
                                                                        in ErrorCallback errorCallback,
                                                                        in unsigned short callFolder);
        };

The LogManager interface offers methods to retrieve information from the call registry.

Constants

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

findLogEntries

Get the list of selected call log entries

Signature
PendingOperation findLogEntries(in LogManagerSuccessCallback successCallback, in ErrorCallback errorCallback, in ShortArray callFolder, in LogFilter filter);

Gets an array of LogEntry objects for call log entries s stored within the selected folders and matching the selected filter.

The filtering is implemented according to the design patterns (chapter 2.4). If no filter is passed all the calls will be returned.

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.

Errors that can be returned in the ErrorCallback:

  • 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 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
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 look 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: Specifies the conditions to be met by the calls
Return value
PendingOperation in order to cancel the async call.
API features
http://bondi.omtp.org/api/1.1/telephony.log.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 = [];
        callsArray.push(bondi.telephonyLog.MISSED_CALLS_FOLDER);
        callsArray.push(bondi.telephonyLog.RECEIVED_CALLS_FOLDER);
        bondi.telephonyLog.findLogEntries(successCallback,errorCallback,callsArray, {phoneNumber:"+34666666666"});
 
getNumberOfCalls

Get the number of calls in a call folder

Signature
unsigned long getNumberOfCalls(in ShortArray callFolders);

Gets the number of calls contained in the folders passed as input argument.

Parameters
  • callFolders: Array of ints describing in which call folders the calls should be counted. The Possible values of the array elements are 0 (MISSED_CALLS_FOLDER), 1 (RECEIVED_CALLS_FOLDER) or 2 (INITIATED_CALLS_FOLDER).
Return value
The number of calls matching the criteria
Exceptions
  • DeviceAPIError:

    INVALID_ARGUMENT_ERROR if parameters are not valid

Code example
        var foldersArray = [];
        foldersArray.push(bondi.telephonyLog.MISSED_CALLS_FOLDER);
  var number = bondi.telephonyLog.getNumberOfCalls(foldersArray);
  alert("There are " + number + " missed calls");
 
deleteLogEntry

Deletes all the calls from a call folder

Signature
PendingOperation deleteLogEntry(in SuccessCallback successCallback, in ErrorCallback errorCallback, in DOMString callID, in unsigned short folder);

Errors that can be returned in the ErrorCallback:

  • 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, e.g.if folder isn't one of the following: MISSED_CALLS_FOLDER, RECEIVED_CALLS_FOLDER or INITIATED_CALLS_FOLDER.
Parameters
  • successCallback: function called when the invocation completes successfully.
  • errorCallback: function called when an error occurs, the callback provides an input parameter that is an Error object that gives information about the type of error that occurred.
  • callID: Call identifier
  • folder: Call folder from which the messages should be removed. The possible values are 0 (MISSED_CALLS_FOLDER), 1 (RECEIVED_CALLS_FOLDER) or 2 (INITIATED_CALLS_FOLDER).
Return value
PendingOperation in order to allow cancelling the async call.
API features
http://bondi.omtp.org/api/1.1/telephony.log.delete
Code example
        // Define the success callback.
        function successCallback(response)
        {
                alert("Call log is now empty");
        }

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

        // Get the call for the specified callid
        bondi.telephonyLog.deleteLogEntry(successCallback,errorCallback, callid, bondi.telephonyLog.MISSED_CALLS_FOLDER);
 
clearLog

Deletes all the calls from a call folder

Signature
PendingOperation clearLog(in SuccessCallback successCallback, in ErrorCallback errorCallback, in unsigned short callFolder);

Errors that may be returned in the ErrorCallback:

  • SecurityError PERMISSION_DENIED_ERROR when access is denied by the security policy.
  • DeviceAPIError INVALID_ARGUMENT_ERROR if a malformed argument has been supplied or a required argument has been omitted.
Parameters
  • successCallback: function called when the invocation completes successfully.
  • errorCallback: function called when an error occurs, the callback provides an input parameter that is an Error object that gives information about the type of error that occurred.
  • callFolder: Call folder from which the entries should be removed. The possible values are 0 (MISSED_CALLS_FOLDER), 1 (RECEIVED_CALLS_FOLDER) or 2 (INITIATED_CALLS_FOLDER).
Return value
PendingOperation in order to allow cancelling the async call.
API features
http://bondi.omtp.org/api/1.1/telephony.log.delete
Code example
      // Define the success callback.
      function successCallback(response)
      {
              alert("Call log is now empty");
      }

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

      // Get the call log for the specified filter.
                var callsArray = [];
                callsArray.push(bondi.telephonyLog.MISSED_CALLS_FOLDER);
                callsArray.push(bondi.telephonyLog.RECEIVED_CALLS_FOLDER);
                bondi.telephonyLog.clearLog(successCallback,errorCallback, callsArray);
 

3.3. LogEntry

Encapsulation of a call log entry on the device.

        [NoInterfaceObject] interface LogEntry {
                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.telephonyLog.findLogEntries(successCallback, errorCallback,
                [ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
                { phoneNumber:"+34666666666"});
 

Attributes

readonly DOMString phoneNumber

Phone number
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.telephonyLog.findLogEntries(successCallback, errorCallback,
                [ bondi.telephonyLog.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.telephonyLog.findLogEntries(successCallback, errorCallback,
                [ bondi.telephonyLog.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.telephonyLog.findLogEntries(successCallback, errorCallback,
                [ bondi.telephonyLog.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.telephonyLog.findLogEntries(successCallback, errorCallback,
                [ bondi.telephonyLog.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.telephonyLog.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.telephonyLog.findLogEntries(successCallback, errorCallback,
                [ bondi.telephonyLog.MISSED_CALLS_FOLDER ],
                { phoneNumber:"+34666666666"});
 

3.4. LogFilter

Used for perform search operations in the Call Log

        [NoInterfaceObject, Callback] interface LogFilter : GenericFilter {
                
        };

This interface is intended to be used for input parameters for call searching (findLogEntries). Interface used for creation of the Filter objects depending on the CallProperties interface All the attributes are optional and by default are undefined

Code example
        // Define the success callback.
        function successCallback(response) {
                var calls = response;
                // Get first message in the list of results
                var call = calls[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.telephonyLog.findLogEntries(successCallback, errorCallback,
                [ bondi.telephonyLog.RECEIVED_CALLS_FOLDER ],
                { phoneNumber:"+34666666666"});
 

3.5. LogManagerObject

Specifies what is instantiated at feature request

        interface LogManagerObject {
                readonly attribute LogManager telephonyLog;
        };
        Bondi implements LogManagerObject;