PhoneLogs

- BlackBerry OS 5.0+
- Ripple Emulator

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

API Summary

addPhoneLogListener

---

static Boolean addPhoneLogListener(onCallLogAdded : function, onCallLogRemoved : function, onCallLogUpdated : function, onCallLogReset : function)

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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.

Returns

Returns true if the listener is assigned

Parameter	Type	Description
onCallLogAdded	function(addedCallLog : blackberry.phone.PhoneLogs.CallLog)	This callback function is triggered when a new call log is added. addedCallLog: Object that contains the CallLog that was added
onCallLogRemoved	function(removedCallLog : blackberry.phone.PhoneLogs.CallLog)	This callback function is triggered when a call log is removed. removedCallLog: Object that contains the CallLog that was removed
onCallLogUpdated	function(newCallLog : blackberry.phone.PhoneLogs.CallLog, oldCallLog : blackberry.phone.PhoneLogs.CallLog)	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	function()	This callback function is triggered when a call log is reset.

Code Example(s)

<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>

callAt

---

static CallLog callAt(index : Number, folderID : Number)

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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

Returns

Returns the CallLog specified by the index

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

Code Example(s)

<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>

deleteCallAt

---

static Boolean deleteCallAt(index : Number, folderID : Number)

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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

Returns

Returns true if the item was successfully deleted

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

Code Example(s)

<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>

find

---

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

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

This method lookup the CallLog that match the expression provided.

Returns

The function returns list of CallLogs that match search criteria

Parameter	Type	Description
filter	FilterExpression Optional	optional expression parameter that defines the search criteria for the find. If no value is provided all the Logs are suitable.
folderID	Number Optional	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	String Optional	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	Number Optional	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	Boolean Optional	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.

Code Example(s)

<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>

numberOfCalls

---

static Number numberOfCalls(folderID : Number)

Supported Platform(s)

 - BlackBerry OS 5.0+
 - Ripple Emulator

Description

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

Returns

Returns number of calls

Parameter	Type	Description
folderID	Number	ID of the folder to check (one of the FOLDER_* values).

Code Example(s)

<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:

---

Property	Type	Description	Supported Platform(s)
FOLDER_MISSED_CALLS default: 0	Number	Folder ID for the missed call folder.	- BlackBerry OS 5.0+  - Ripple Emulator
FOLDER_NORMAL_CALLS default: 1	Number	Folder ID for other (not missed) calls.	- BlackBerry OS 5.0+  - Ripple Emulator

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:19 GMT-0500 (EST)