PhoneLogs

A container to maintain a list of CallLog objects that together represent the call log for phone calls stored in the message list.


Supported Platform(s)

- BlackBerry OS 5.0+
- Ripple Emulator
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.phone.PhoneLogs.addPhoneLogListener Y Y Y      Y
blackberry.phone.PhoneLogs.callAt Y Y Y      Y
blackberry.phone.PhoneLogs.deleteCallAt Y Y Y      Y
blackberry.phone.PhoneLogs.find Y Y Y      Y
blackberry.phone.PhoneLogs.numberOfCalls Y Y Y      Y
FOLDER_MISSED_CALLS Y Y Y      Y
FOLDER_NORMAL_CALLS Y Y Y      Y

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.phone.Find" /> Y Y Y      Y
<feature id="blackberry.phone.PhoneLogs" /> Y Y Y      Y

Permission Elements (PlayBook and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Functions

static Boolean blackberry.phone.PhoneLogs.addPhoneLogListener (onCallLogAdded: function(addedCallLog : blackberry.phone.PhoneLogs.CallLog), onCallLogRemoved: function(removedCallLog : blackberry.phone.PhoneLogs.CallLog), onCallLogUpdated: function(newCallLog : blackberry.phone.PhoneLogs.CallLog, oldCallLog : blackberry.phone.PhoneLogs.CallLog), onCallLogReset: function())


Registers PhoneLogListener to listen for call log events.

Register listeners when interested in receiving call log events. When you subscribe more than one callback function, every new callback set will overwrite each previous. To unsubscribe from all callbacks, pass null as a parameter.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
onCallLogAdded This callback function is triggered when a new call log is added.

addedCallLog: Object that contains the CallLog that was added
onCallLogRemoved This callback function is triggered when a call log is removed.

removedCallLog: Object that contains the CallLog that was removed
onCallLogUpdated This callback function is triggered when a call log is updated.

newCallLog: Object that contains the CallLog that represents the new CallLog
oldCallLog: Object that contains the CallLog that represents the old CallLog
onCallLogReset This callback function is triggered when a call log is reset.

Return:

Returns true if the listener is assigned



Code Example:
<script type="text/javascript">
  // Register with phone log listener to be notified with its events
  // Here, we are interested to get notified regarding all possible events other than phone log removal 
  alert("Registering for phone log events.. ");
  var res = blackberry.phone.PhoneLogs.addPhoneLogListener(OnCallLogAdded,  null, OnCallLogUpdated, OnReset);
  alert("Registered for phone log events: " + res);

  // Invoked when a new call log added
  function OnCallLogAdded(callLog) {
    alert("Call Log Added!");
  }

  // Invoked when a call log has been updated
  function OnCallLogUpdated(newCallLog, oldCallLog) {
    alert("Call Log Updated!");
  }

  // Invoked to reset the log
  function OnReset() {
    alert("Log Reset!");
  }
</script>

static CallLog blackberry.phone.PhoneLogs.callAt (index : Number, folderID : Number)


Retrieves a particular call from the appropriate log folder by index.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
index The index of the call in the phone log, from 0 to numberOfCalls(folderID) - 1
folderID ID of the folder from which to retrieve the call, (one of the FOLDER_* constants)

Return:

Returns the CallLog specified by the index



Code Example:
<script type="text/javascript">
  // Display 'normal' call log retrieved at index specified
  var index = 1;
  var res = blackberry.phone.PhoneLogs.callAt(index, blackberry.phone.PhoneLogs.FOLDER_NORMAL_CALLS);
  alert("CallLog retreived: " + res);
</script>

static Boolean blackberry.phone.PhoneLogs.deleteCallAt (index : Number, folderID : Number)


Deletes a call from the log. The call will be removed from the appropriate list.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
index Index of the call log to delete, from 0 to numberOfCalls(folderID) - 1
folderID ID of the folder containing the call log to delete (one of the FOLDER_* values).

Return:

Returns true if the item was successfully deleted



Code Example:
<script type="text/javascript">
  //Display if 'normal' call log was successfully deleted at index specified
  var index = 1;
  var res = blackberry.phone.PhoneLogs.deleteCallAt(index, blackberry.phone.PhoneLogs.FOLDER_NORMAL_CALLS);
  alert("Is deleting normal call at index: " + index + " succeeded? " + res);
</script>

static CallLog[] blackberry.phone.PhoneLogs.find ([filter : FilterExpression], [folderID : Number], [orderBy : String], [maxReturn : Number], [isAscending : Boolean])


This method lookup the CallLog that match the expression provided.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
filter optional expression parameter that defines the search criteria for the find. If no value is provided all the Logs are suitable.
folderID optional 'folderID' parameter specifying the folder where to performed find. If 'folderID' is not supplied the search is made in the missed calls folder (FOLDER_MISSED_CALLS).
orderBy optional 'orderBy' parameter specifying the field which the results will be sorted by. If 'isAscending' is not supplied or 'isAscending' is true, the sort results will be in an ascending order. If 'isAscending' is false, the sort results will be in a descending order.
maxReturn optional integer parameter specifying the maximum number of results to return from the find. If not supplied or set to -1, it will return all results found.
isAscending optional 'isAscending' parameter specifying whether the sort order is ascending or descending. If not supplied or set to true, the results sorted by the field specified by 'orderBy' will be in an ascending order. If set to false, the sort results will be in a descending order. If no 'orderBy' value is specified, 'isAscending' is neglected.

Return:

The function returns list of CallLogs that match search criteria



Code Example:
<script type="text/javascript">
  // Iterating through array of 'normal' call logs matching the find criteria
  var filter = new blackberry.phone.Find.FilterExpression("duration", ">", 3);
  var found = blackberry.phone.PhoneLogs.find(filter, blackberry.phone.PhoneLogs.FOLDER_NORMAL_CALLS, "duration", 6, false);
  if (found) {
    alert("Length of find return is: " + found.length);

    for (i = 0; i < found.length; i++) {
        alert((i + 1) + "->duration: Duration=" + found[i].duration + ", name:" + found[i].name);
    }
  }
</script>

static Number blackberry.phone.PhoneLogs.numberOfCalls (folderID : Number)


Retrieves the number of calls in a given phone log folder.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator


Parameters
folderID ID of the folder to check (one of the FOLDER_* values).

Return:

Returns number of calls



Code Example:
<script type="text/javascript">
  // Display the number of 'missed' call logs
  var res = blackberry.phone.PhoneLogs.numberOfCalls(blackberry.phone.PhoneLogs.FOLDER_MISSED_CALLS);
  alert("Number of missed calls: " + res);
</script>

Constants

static Number FOLDER_MISSED_CALLS = 0


Folder ID for the missed call folder.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

static Number FOLDER_NORMAL_CALLS = 1


Folder ID for other (not missed) calls.


Supported Platforms
 - BlackBerry OS 5.0+
 - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:41 GMT-0500 (EST)