CallHistory API Guide

PUBLISHED 27 Jul 2015

Overview

The Tizen CallHistory API provides the interfaces and methods for accessing information about various telephony services for Circuit Switched Telephony and Voice over IP (VoIP). You can use the CallHistory API to browse or list the call history entries of a device, remove call history entries, and monitor changes.

The CallHistory API provides different levels of access to retrieve information about a device’s telephony services. To use this API, add the required permissions to the config.xml file. When the application is launched, a CallHistory object is instantiated automatically in the tizen object. The tizen.callhistory object retrieves information about the current state of the device.

Prerequisites
Request for Call History Entries
Remove a Call History Entry
Remove Multiple Call History Entries (Batch mode)
Remove All Call History Entries
Register Callback to Listen Call History Changes
Unregister the Callback Listener
Handle Changes to Call History
Screenshot

Prerequisites

To use any of the CallHistory's methods, you must declare the necessary features in the config.xml file. It is recommended that you do it using the SDK interface.
In this example, the callhistory features are needed. Open the config.xml file, choose the "Feature" tab, and add below features to enable them to use in your applications.

http://tizen.org/privilege/callhistory.read: Privilege to allow read access to call history.
http://tizen.org/privilege/callhistory.write: Privilege to allow write access to call history methods like, remove(), removeBatch() and removeAll().

Finally add http://tizen.org/api/tizen. If you want to do it manually, add the following <feature> tag to the file as below,

<?xml version="1.0" encoding="UTF-8"?>
<widget xmlns="http://www.w3.org/ns/widgets" xmlns:tizen="http://tizen.org/ns/widgets" id="http://yourdomain/TizenCallHistoryAPI" version="1.0.0" viewmodes="maximized">
    <tizen:application id="YcJaPTQp4d.TizenCallHistoryAPI" package="YcJaPTQp4d" required_version="2.2"/>
    <content src="index.html"/>
    <icon src="icon.png"/>
    <name>TizenCallHistoryAPI</name>
    <tizen:privilege name="http://tizen.org/privilege/callhistory.read"/>
    <tizen:privilege name="http://tizen.org/privilege/callhistory.write"/>
    <tizen:privilege name="http://tizen.org/privilege/tizen"/>
</widget>

Since the application will contain the Exit button, it will need the quitting functionality. To provide it, add the application.read feature.

Request for Call History Entries

The CallHistory interface is used to manage call history. This interface stores data about all incoming and outgoing calls, including the date and time of all calls.
The CallHistory interface is used to represent a call that was made or received. The call history data that is fetched from the system through the CallHistory interface is represented as entries using the CallHistoryEntry interface. The CallHistory interface provides methods for various operations, such as finding call history items, removing a single call history item, removing a list of call history items, removing the entire call history,
and listening to the call history changes.

Begin by defining a function that will be executed when "Get Call Log" button is clicked (in our sample application). To request for the call history, you need to use tizen.callhistory.find() function. This function is asynchronous and takes 6 parameters. Two first parameters are callback functions (the first one to be executed in case of success, the second - in case of failure). Other parameters are filter for filter definition and sortMode for sort options and limit and offset.
Result of call history request in case of success will be returned to the callback function as an array of CallHistoryEntry objects. The following is the parameters of the tizen.callhistory.find() method. The SuccessCallback parameter is a handler for query result set. It appends the entry in the call history if a call history item is found.

//Define success callback
function onSuccessCallHistory(results) {
	output.set(results.length + ' call history item(s) found !');
	for(var i=0; i<results.length; i++)
         {
	   output.append(i + '.' + results[i].toString());
	   // process the CallHistoryEntry
	 }
}

The errorCallback parameter reports failure on error.

//Define error callback
function onErrorCallHistory(error) {
	output.set('Query failed' + error.code);
}

The filter parameter is of AttributeFilter type and is used to define which call history results you are interested in. In the case of this tutorial, you want to show only telephone calls (not video calls or VOIP calls). To do this, you set filter's attributeName to "type", matchValue to "TEL" and matchFlag to "EXACTLY".
That means you want to choose only those CallHistoryEntry items, whose type attriburte has a value "TEL". Please refer to filter documentation for general information on filters usage and CallHistoryEntry documentation for information on other call record attributes which may be useful while creating your own filters.

var filter = new tizen.AttributeFilter("type", "EXACTLY", "TEL");

The AbstractFilter parameter may be used to search according to CallHistoryEntry interface parameters, for example type, features and so on. In the following example, remoteParties.remoteParty is an attribute name,the match value 123456789 is a telephone number to be matched, and the match flag is EXACTLY.

var numberfilter = new tizen.AttributeFilter("remoteParties.remoteParty",
                                             "EXACTLY",
                                             "123456789");

The CompositeFilter parameter represents a set of filters. The UNION type composite filter matches any object that is matched by any of its filters; the INTERSECTION type composite filter matches all objects that are matched by all of its filters.

// create a composite filter for time constraints
var y2009Filter = new tizen.AttributeRangeFilter("startTime",
                                                 new Date(2009, 0, 1),
                                                 new Date(2010, 0, 1));

var y2011Filter = new tizen.AttributeRangeFilter("startTime",
                                                 new Date(2011, 0, 1),
                                                 new Date(2012, 0, 1) );

// create composite filter
var datefilter = new tizen.CompositeFilter("UNION",
                                           [y2009Filter, y2011Filter]);

// Create a video call filter
var tfilter = new tizen.AttributeFilter("features", "EXACTLY", "VIDEOCALL");

var ifilter = new tizen.CompositeFilter("INTERSECTION", [numberFilter, dateFilter, tfilter]);

The sortMode parameter is of SortMode type and defines how the results will be sorted. The usage of sortMode is similar to filters: you decide which attribute of CallHistoryEntry item will be the key for sorting and which order you want to be used. In the case of this tutorial, results will be sorted descending by the time when call occurred (the latest calls on top). To do this you set the sortMode's attributeName to "startTime" and order to "DESC".

Please refer to sortMode documentation for more information about sorting and CallHistoryEntry documentation for information on other call record attributes which may be useful when creating your own sorting.

Below example sorts the calls according to the start time, in descending order.

var sortMode = new tizen.SortMode("startTime", "DESC"};

If you set the attribute name of sortMode to startTime and order to DESC, the results are sorted in the descending order according to the time when the call occurred (the latest calls are on top).

The limit parameter allows you to specify the maximum number of matching results that are to be returned. Setting this to 0 makes the limit infinite.

The offset parameter is used to skip that many matching results that are to be returned; offset 0 is the same as omitting the offset clause.

For example, if your search results consist of 100 matching results, and if you have specified an offset of 10 and a limit of 20, then from the 100 matching results, you get the objects from 10-29. The matching results from 0-9 are skipped. Offset is the starting point to begin-lower limit, and limit is the upper limit from offset.

//Define success callback
function onSuccessCallHistory(results) {
	output.set(results.length + ' call history item(s) found !');
	for(var i=0; i<results.length; i++) {
		output.append(i + '.' + results[i].toString());
		// process the CallHistoryEntry
		} }
//Define error callback
function onErrorCallHistory(error) {
	output.set('Query failed' + error.code);
}
//get the call history
function showCallHistory() {
	console.log("Checking for call history entries..");
// Define filter
var filter = new tizen.AttributeFilter("type", "EXACTLY", "TEL");

// Define sort mode: descending on call start time.
var sortMode = new tizen.SortMode("startTime", "DESC");
// Make the query and wire up the callbacks
try {
    tizen.callhistory.find(onSuccessCallHistory, onErrorCallHistory, filter, sortMode); // Limits can be used,when displaying the list
   } catch(err) {
	  output.set('Error: Find Call failed: ' + err.code + ':' + err.message);
   }
}

Remove a Call History Entry

The tizen.callhistory.remove method can be used to remove an entry from the call history. This method takes a specific call history entry to be deleted.
The following example illustrates how to remove a specified call entry using the remove method.

Example code:
//Define success callback
function onSuccessRemove(callList) {
	if (callList.length > 0) {
		tizen.callhistory.remove(callList[0]);
		output.set('Removed 1 call history Item');
	} else {
		output.set('No Call History Items Found');
	}
}
//Define error callback
function onErrorRemove(error) {
	output.set('Query failed' + error.code);
}
//Function to remove a call log
function RemoveCallLog()
{
    console.log("Remove a Call Log entry called..");
  // Define filter
  //var filter = new tizen.AttributeFilter("type", "EXACTLY", "TEL");
  //Make the query and wire up the callbacks
  tizen.callhistory.find(onSuccessRemove, onErrorRemove);
}

Remove Multiple Call History Entries (Batch mode)

If you want to remove multiple call history entries, you can either use the tizen.callhistory.remove method multiple times or the CallHistory.removeBatch method. The removeBatch method takes a list of call history items to be removed as a parameter instead of a single entry. Hence, this is an efficient approach to asynchronously delete a list of call history entries. The following example illustrates how to remove multiple call entries using the removeBatch method.

 Example code:
//Define success callback
function onSuccessRemoveBatch(results) {
	function removeBatchSuccess() {
	    output.set('Successfuly removeds' + results.length + ' items');
	}
	function removeBatchError() {
	    output.set('Exception : ' + error.code);
	}
	if (results.length > 0) {
	    tizen.callhistory.removeBatch(results, removeBatchSuccess, removeBatchError);
	} else {
	    output.set('No call history items found');
	}
}
//Define error callback
function onErrorRemoveBatch(error) {
	output.set('Query failed' + error.code);
}
function RemoveBatchEntries() {
   console.log("Remove Call log entries as a batch called..");
   // Define filter
   var filter = new tizen.AttributeFilter("type", "EXACTLY", "TEL");
   //Make the query and wire up the callbacks
   tizen.callhistory.find(onSuccessRemoveBatch, onErrorRemoveBatch,filter);
}

Remove All Call History Entries

The tizen.callhistory.removeAll method deletes all call history items. This method accepts the following parameters:

successCallback is a generic success handler.

errorCallback is an error handler..

Example code:

//Define error callback
function onError(error) {
  output.set('Query failed' + error.code);
}

function onSuccess() {
  output.set('Call log cleared successfully');
}

function onSuccessFind(list) {
	if (list.length > 0) {
	try {
	      tizen.callhistory.removeAll(onSuccess, onError);
	    } catch (err) {
		      onError(err);
	          }
	 } else {
	      output.set('No call history items found');
	 }
}

function removeAllCallHistory() {
	console.log("Remove all Call Logs called..");
	// Make the query and wire up the callbacks
	tizen.callhistory.find(onSuccessFind, onError);
}

Register Callback to Listen Call History Changes

Any change made to the call history is an event. Registering listeners allows you to define callbacks to be executed every time an event occurs. Whenever a specific event occurs within the object, that is, any change occurs, all handlers are invoked.

You can use the tizen.callhistory.addChangeListener method to register a callback for observing CallHistory changes. This method accepts a CallHistoryChangeCallback object,
which defines 2 handlers, onadded and onchanged, to handle the events for additions and updates to the call history, respectively. The return value of the addChangeListener method is a handle that can be used for unregistering.

The following example illustrates how to use the CallHistory.addChangeListener method.

var onCallHistoryChange = {
	onadded: function(newItems) {
	  alert("New call log item added");
	  for ( var i = 0; i < newItems.length; i++) {
	     output.append('Item ' + i + 'startTime: ' + newItems[i].startTime);
	   }},
	onchanged: function(changedItems) {
	  alert("Call items changed");
	  for ( var i = 0; i < changedItems.length; i++) {
	     output.append('Item ' + i + 'direction: ' + changedItems[i].direction);
	   }
	  }};
function registerCallbackCallHistory() {
    console.log("Registering to callback changes..");
    //Define error callback
    function onError(error) {
 	output.set('Callback Registration failed' + error.code);
     }
    // Make the query and wire up the callbacks
    try {
     var callHistoryListener = tizen.callhistory.addChangeListener(onCallHistoryChange);
	 output.set('Registered the change notification callbacks');
	} catch (err) {
	  onError(err);
	}
}

Note: This method returns a handler ID after a successful callback registration.

Unregister the Callback Listener

You can use the CallHistory.removeChangeListener method to unregister a previously registered listener.This method:

Uses the handle parameter, which has been previously obtained from addChangeListener.

Deletes the listener object returned by addChangeListener

You need to use the ID returned by the tizen.callhistory.addChangeListener method.The following example illustrates how to unregister the listener:

Example code:

function deregisterHandlerCallHistory() {
	//Define error callback
	function onError(error) {
		output.set('Callback UnRegistration failed' + error.code);
	}
	try {
	  // Pass handle returned from "tizen.callhistory.addChangeListener call
	  tizen.callhistory.removeChangeListener(callHistoryListener);
	   output.set('Unregistered the change notification callback');
	  } catch (err) {
		onError(err);
	    }
	}

Note: This method takes the ID as the parameter, which was returned from earlier registration.

Handle Changes to Call History

The CallHistoryChangeCallback interface is used to define callbacks for handling changes in the call history. Registering change listeners allows you to synchronize the view of your application to changes in the call history database.

Addition of a New Call History Item.

By defining an onadded handler of the CallHistoryChangeCallback interface, you can keep track of new calls made. The onadded method is a convenient callback method to keep track of any new incoming and outgoing call that has been added to the call history. An array of CallHistoryEntry objects representing the new items added to the call history is passed as an argument to the onadded handler.

Changes to a Call History Item

The onchanged handler of the CallHistoryChangeCallback interface is a callback method for handling changes to CallHistory items. You can use this method to keep track of any changes or updates that have been made to the call history. An array of CallHistoryEntry objects representing the changed items in the call history is passed to the onchanged handler.

Refer example code under AddListener method.

Screenshot

Picture 1: Main Menu

Picture 2: When removed a Callhistory entry

Development Environment:

Tizen SDK

Version : 2.2.0
Build id : 20130708-1957

Note:
The CallHistory API sample application is available for reference (See under File Attachment section).

File attachments:

tizencallhistoryapi.zip

List

Category:

Dev Tips

Tags:

callhistory, call

User Menu

Tizen Developers

Community

CallHistory API Guide