CallHistory API指南

PUBLISHED 27 7月 2015

概述

Tizen CallHistory API提供访问Circuit Switched Telephony and Voice over IP (VoIP)各种电话服务信息的接口和方法。你可以使用CallHistory API来浏览或列出设备的通话记录条目，删除通话记录条目和监测变化。

CallHistory API提供了不同级别的访问权限去检索设备电话服务的信息。要使用这些API，需在config.xml文件中添加需要的权限。当应用程序被启动，一个CallHistory对象将自动在tizen对象被实例化。 tizen.callhistory对象用于检索与设备当前状态相关的信息。

先决条件

要使用CallHistory方法，你必须在config.xml文件中声明必要的功能。建议使用SDK接口实现。
在这个实例中，需要callhistory功能。打开config.xml文件，选择“Feature”选项卡，然后在你的应用中添加以下功能来使用它们。

：有允许读取通话记录的权限。
：有允许写通话记录方法的权限，如：remove(), removeBatch() and removeAll()。

最后。如果你想手动修改，请像如下添加下面的<feature>标签，

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

由于该应用程序将包含Exit按钮，这将需要退出功能。为了提供它，请添加application.read功能。

请求通话记录条目

CallHistory接口用于管理呼叫历史。接口存储所有呼入和呼出的数据，包括所有通话的日期和时间。
CallHistory接口用于表示发出或接收的呼叫。呼叫历史数据是通过CallHistory接口从系统获取，它被表示为使用CallHistoryEntry接口的条目。该CallHistory接口提供各种操作方法，如：查找通话记录项，删除单个通话记录项，删除通话记录项的列表，删除整个通话记录，
和监听电话记录的变化。

通过定义一个函数，在"Get Call Log"按钮将被执行（在我们的示例应用程序中）。请求通话记录，你需要使用tizen.callhistory.find（）函数。这个函数是异步的，并且有6个参数。头两个数是回调函数（第一个在成功时被执行，第二个在失败时被执行）。其他参数用于设置过滤器，sortMode设置排序选项，然后是限制与偏移。
在成功的情况下，呼叫历史请求的结果将被返回给回调函数作为CallHistoryEntry对象的数组。以下是tizen.callhistory.find（）方法的参数。 SuccessCallback是用于查询结果集的处理函数。如果呼叫历史项目被发现，它将在通话记录中添加条目，。

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

errorCallback参数报告错误。

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

filter参数是AttributeFilter类型，用来定义你对哪些呼叫历史结果感兴趣。在本教程的中，你想只显示电话（不是视频电话或VOIP电话）。要做到这一点，你可以设置过滤的attributeName为“type”，matchValue为"TEL" 和matchFlag为"EXACTLY"。
这意味着你想只选择那些CallHistoryEntry事项，其类型值为"TEL"。请参阅关于过滤器使用的文档和其他你自己创建的过滤器的可能有用的通话记录的CallHistoryEntry文档。

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

AbstractFilter参数可用于根据CallHistoryEntry接口参数进行搜索，例如：类型，特征等。在下面的例子中，remoteParties.remoteParty是一个属性名称，123456789是一个电话号码，匹配标志是EXACTLY。

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

CompositeFilter参数表示一组过滤器。 UNION组合过滤器可与任何对象的过滤器匹配；INTERSECTION 组合过滤器也可与任何对象的过滤器匹配。

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

sortMode参数是SortMode类型，定义了如何将结果排序。 sortMode的用法类似于过滤器：你要决定CallHistoryEntry事项的属性是排序关键字和你想要如何排序。至于本教程，结果将按通话发生时间的降序排列（上面是最新的呼叫）。要做到这一点，你需要设置sortMode的attributeName 为“startTime”，顺序为“DESC”。

请参考sortMode文档以获取更多关于排序的信息，CallHistoryEntry文档上有可能有用的关于你自己创建的排序的通话记录的信息。

下面的例子是按来电时间按降序排列的。

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

如果你设置sortMode的属性名为startTime，oder为DESC，结果将按呼叫发生时间的降序排列（最新的呼叫是在上面）。

极限参数允许你设定返回的匹配结果的最大数目。将其设置为0表示无限制。

offset参数是用来跳过很多要返回的匹配结果；offset为0表示忽略该值。

例如，如果你的搜索结果包含100的匹配结果，并且offset设为10，limit设为20，那么你将从100个匹配结果中得到10-29对象。匹配结果0-9被跳过。 offset是起点，limit是从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);
   }
}

删除通话记录条目

tizen.callhistory.remove方法用来从呼叫历史中删除条目。此方法可删除具体的通话记录条目。
下面的例子演示了如何使用这个remove方法删除指定的呼叫项。

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

删除多个通话记录条目（批处理模式）

如果你想删除多个通话记录条目，您可以多次使用tizen.callhistory.remove方法或CallHistory.removeBatch方法。 removeBatch方法将通话记录列表作为参数删除，而不是单个条目。因此，这是一种有效的异步删除通话记录条目列表的方法。下面的例子演示了如何使用removeBatch方法删除多个通话条目。

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

删除所有通话记录条目

tizen.callhistory.removeAll方法删除所有通话记录项。这个方法接受以下参数：

successCallback是一个通用的成功处理函数。

errorCallback是一个错误处理程序函数。

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

注册回调来监听通话记录的变化

任何通话记录的变化都会产生事件。注册监听可以让你定义一个事件发生的回调函数。当对象中一个特定事件的发生，即任何改变时，所有的处理程序都被调用。

您可以使用tizen.callhistory.addChangeListener方法来注册一个回调函数来监视CallHistory的变化。该方法接受CallHistoryChangeCallback对象，
它定义了两个处理函数，onAdded和onChanged，分别用来处理附加事件和更新通话记录。 addChangeListener方法的返回值是用于注销的处理函数。

下面的例子演示了如何使用CallHistory.addChangeListener方法。

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

注意：此方法成功注册的回调后返回处理程序的ID。

注销回调监听

您可以使用CallHistory.removeChangeListener方法注销先前已注册的监听。方法为：

使用这个之前addChangeListener获取的句柄参数。

删除由addChangeListener返回的监听对象

您需要使用由tizen.callhistory.addChangeListener方法返回的ID。下面的例子说明如何注销监听器：

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

注意：此方法的参数之前从注册函数返回的ID。

处理通话记录的变更

CallHistoryChangeCallback接口用于定义处理通话记录变化的回调函数。注册变化监听器允许你在将应用程序的视图同步到通话记录数据库。

添加新的通话记录项。

通过定义CallHistoryChangeCallback接口的onAdded处理函数，你可以跟踪新的呼出通话。 onAdded方法是一个方便的回调方法，用于跟踪被添加到呼叫记录中的新的呼入和传出通话。 CallHistoryEntry对象代表加入到通话记录的新的事项，它作为onAdded处理函数的参数传递。

更改为通话记录项

CallHistoryChangeCallback接口的onChanged处理函数是一个回调函数，用于处理CallHistory项的变化。您可以使用此方法来跟踪变化或更新通话记录。 CallHistoryEntry对象代表通话记录中的变化项，它传递给onChanged处理函数。

请参阅以下addListener方法的示例代码。

截图

Picture 1: 主菜单

图2：当删除一个Callhistory项时

开发环境：

Tizen SDK

版本：2.2.0
构建 id： 20130708-1957

注：
CallHistory API示例应用程序是参考程序（参见下文件附件部分）。

文件附件:

tizencallhistoryapi.zip

List

评论:

适用于开发人员的提示

标签:

callhistory, call

用户菜单

Tizen Developers

社区

CallHistory API指南