The Bondi telephony Module - Version 1.5

void onEvent(in Call incommingCall);

The notification callback handler for managing incomming calls is also used for a successfull migration of a call from one telephony provider to another one.

PendingOperation getTelephonyProviders(in TelephonyProviderSuccessCallback successCallback, in TelephonyErrorCallback errorCallback);

The number of telephony providers that are accessible through the telephony API depends on the number of available CS and PS providers installed on the device. To distinguish between multiple telephony providers the provider description and properties can be used to select the telephony provider to use.

If the method is executed succcessfuly, telephony providers can be provided, the successcallback is raised. If access is denied by the Security Policy, the errorCallback is invoked with an SecurityError PERMISSION_DENIED_ERROR. If an invalid parameter is passed in the ErrorCallback is invoked with an DeviceAPIError INVALID_ARGUMENT_ERROR.

TelephonyProvider getDefaultProvider();

Get the default telephony provider that is commonly used on the device.

PendingOperation init(in SuccessCallback successCallback, in ErrorCallback errorCallback, in TelephonyProviderConfigurationOptions options);

Initializes the telephony provider which usually means that needed connections to the related telephony provider's network are established and the user is allowed to make calls (from the backend point of view).

If using init without any parameters was not successful the user could be ask to enter a user name and password for accessing the telephony provider.

Telephony tariff based telephony providers usually don't need any additional user credentials.

The ErrorCallback receives a DeviceAPIError with code INVALID_ARGUMENT_ERROR if any of the passed in parameters is invalid. The ErrorCallback receives a TelephonyError with code TELEPHONY_PROVIDER_NOT_INITIALIZED if initializing the provider was not successful for any other reason.

void setIncommingCallEventListener(in OnIncommingCallEvent incommingCallEventListener);

Sets the event listener that receives incomming calls to this telephony provider. If setIncommingCallEventListener is called and a listener was registered before only the newer one will receive incomming calls.

DOMString getMyAddress();

The address is either a valid phone number that follows the e.164 phone number scheme if the associated telephony provider is a circuit switched telephony provider or it should be a valid SIP URI if the associated telephony provider is a packet switched telephony provider.

Call createCall(in DOMString callingPartner);

Creating a call object the can be used to manage a call with the passed in calling partner. Creating a call does not mean that the call is established. To establish a call use Call.open().

The passed in calling partner address must be either a valid phone number for Core telephony providers that follows the e.164 phone number scheme or should be valid SIP URI for Data telephony providers.

PendingOperation migrateCall(in OnIncommingCallEvent successCallback, in ErrorCallback errorCallback, in Call call);

Migrating a call allows to switch an ongoing call from one telephony provider to another. The returned Call will be in state CALL_STATE_CONNECTED if migrating a call was successful. The passed in call will be terminated if migrating the call was successfull.

The error callback receives a SecurityError if creating a call with this telephony provider is not allowed. It receives a DeviceAPIError with code Unknown_Error if migrating was not succesfull or is not possible. It receives a TelephonyError with code TELEPHONY_PROVIDER_NOT_INITIALIZED if the telephony provider is not initialized befor calling migrateCall. It receives a DeviceAPIError with code INVALID_ARGUMENT_ERROR if any input parameter is invalid.

PendingOperation open(in SuccessCallback successCallback, in ErrorCallback errorCallback);

Establisgin a connection either through connecting a calling partner for a created call or through accepting a call for incomming calls. The CALL_STATE_ESTABLISHING event is published to signal that establishing a call is ongoing. If the connection was successfully established the CALL_STATE_CONNECTED is published.

The errorCallback receives a TelephonyError with code TELEPHONY_NOT_ALLOWED_ERROR if opening the call is not allowed which is the case if the call is not in state CALL_STATE_IDLE. It receives a DeviceAPIError with code UNKNOWN_ERROR if the call could not be opened for any reason.

PendingOperation reject(SuccessCallback successCallback, ErrorCallback errorCallback);

A call that was recieved through an OnIncommingCallEvent event can be rejected in order to drop the incomming call and send an on-hook signal. A rejected call moves into the CALL_STATE_CLOSED state.

The errorCallback receives a TelephonyError with code TELEPHONY_NOT_ALLOWED_ERROR if rejecting the call is not allowed which is the case if the call is not in state CALL_STATE_RINGING.

PendingOperation close(in SuccessCallback successCallback, in ErrorCallback errorCallback);

Closes a call and disconnects from all calling partners. The call moves into the CALL_STATE_CLOSED state.

The errorCallback receives a TelephonyError with code TELEPHONY_NOT_ALLOWED_ERROR if closing the call is not allowed which is the case if the call is not in state CALL_STATE_ON_HOLD or CALL_STATE_CONNECTED.

PendingOperation hold(in SuccessCallback successCallback, in ErrorCallback errorCallback);

A call can be set on hold to create another seperated call or to accept another incomming call without closing an ongoing call. Thus, it is possible to switch between multiple calls.

If an ongoing call can be holded the call moves to the CALL_STATE_ON_HOLD state and publishes an event accordingly.

The errorCallback receives a TelephonyError with code TELEPHONY_NOT_ALLOWED_ERROR if holding the call is not allowed which is the case if the call is not in state CALL_STATE_CONNECTED. It receives a DeviceAPIError with code UNKNOWN_ERROR for any other errors.

PendingOperation resume(in SuccessCallback successCallback, in ErrorCallback errorCallback);

If the call state is CALL_STATE_ON_HOLD it can be resumed. If resuming is successfull the call goes back into the CALL_STATE_CONNECTED state.

The errorCallback receives a TelephonyError with code TELEPHONY_NOT_ALLOWED_ERROR if resuming the call is not allowed which is the case if the call is not in state CALL_STATE_ON_HOLD. It receives a DeviceAPIError with code UNKNOWN_ERROR for any other errors.

PendingOperation join(in SuccessCallback successCallback, in ErrorCallback errorCallback, in Call call);

Joins two calls into one to create a connection with more than two calling partners. If joining was successfull the joined participant will be added to the list of partners. The passed in call goes into the CALL_STATE_CLOSED event.

The errorCallback receives a TelephonyError with code TELEPHONY_NOT_ALLOWED_ERROR if joining a call is not allowed which is the case if this call is not in state CALL_STATE_CONNECTED or CALL_STATE_ON_HOLD. It receives a DeviceAPIError with code UNKNOWN_ERROR for any other errors.

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

        // 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"});
 

unsigned long getNumberOfCalls(in ShortArray callFolders);

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

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

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.

        // 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);
 

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.

      // 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);