CallHistory API
For more information on the Call History features, see Call History Guide.
Since: 2.0
Table of Contents
- 1. Interfaces
- 1.1. CallHistoryObject
- 1.2. RemoteParty
- 1.3. CallHistoryEntry
- 1.4. CallHistory
- 1.5. CallHistoryEntryArraySuccessCallback
- 1.6. CallHistoryChangeCallback
- 2. Related Feature
- 3. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
CallHistoryObject | |
RemoteParty | |
CallHistoryEntry | |
CallHistory |
void find (CallHistoryEntryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? limit, optional unsigned long? offset)
void remove (CallHistoryEntry entry)
void removeBatch (CallHistoryEntry[] entries, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
long addChangeListener (CallHistoryChangeCallback observer)
void removeChangeListener (long handle)
|
CallHistoryEntryArraySuccessCallback | void onsuccess (CallHistoryEntry[] entries) |
CallHistoryChangeCallback |
void onadded (CallHistoryEntry[] newItems)
void onchanged (CallHistoryEntry[] changedItems)
void onremoved (DOMString[] removedItems)
|
1. Interfaces
1.1. CallHistoryObject
[NoInterfaceObject] interface CallHistoryObject { readonly attribute CallHistory callhistory; };
Tizen implements CallHistoryObject;
Since: 2.0
Attributes
-
readonly
CallHistory callhistoryObject representing a callhistory.
Since: 2.0
1.2. RemoteParty
[NoInterfaceObject] interface RemoteParty { readonly attribute DOMString? remoteParty; readonly attribute PersonId? personId; };
Since: 2.0
Attributes
-
readonly
DOMString remoteParty [nullable]An attribute to store the remote party identifier (RPID). The RPID is a unique identifier used by a service with call capability. It also includes phone numbers. Contacts are also defined per service, so an RPID can be resolved to a Contact. A null value means that the remote is hidden (private number).
Since: 2.0
-
readonly
PersonId personId [nullable]An attribute to store the identifier of the person to whom the raw contact belongs.
If the contact cannot be resolved, the value is null. See Contact API for more information.
Since: 2.0
1.3. CallHistoryEntry
[NoInterfaceObject] interface CallHistoryEntry { readonly attribute DOMString uid; readonly attribute DOMString type; readonly attribute DOMString[]? features; readonly attribute RemoteParty[] remoteParties; readonly attribute Date startTime; readonly attribute unsigned long duration; attribute DOMString direction; readonly attribute DOMString? callingParty; };
Since: 2.0
Attributes
-
readonly
DOMString uidAn attribute to store the unique identifier of a call record.
Since: 2.0
-
readonly
DOMString typeAn attribute to store the service type of the call saved to call history.
The following values are supported:
- TEL - for all protocols with phone number addressing (PSTN, GSM, CDMA, LTE, etc.)
- XMPP - for generic XMPP calls
- SIP - for generic SIP calls
Since: 2.0
-
readonly
DOMString[]
features [nullable]An attributes to store the features associated with the call service saved to call history. The following values are supported:
- CALL - for all call types
- VOICECALL - for voice-only calls
- VIDEOCALL - for audio and video channel support in a call
- EMERGENCYCALL - to denote an emergency call
Since: 2.0
-
readonly
RemoteParty[]
remotePartiesAn attribute to store the remote parties participating in the call.
Since: 2.0
-
readonly
Date startTimeAn attribute to store the start time of the call. This attribute is the moment when media channels come up. The exact meaning is defined by the back-end.
Since: 2.0
-
readonly
unsigned long durationAn attribute to store the duration of the call in seconds. This attribute is the duration from media channels coming up to the moment when media channels tear down on the same call service. If the call is migrated to another service, another call history entry is used. The exact meaning is defined by the back-end.
Since: 2.0
-
DOMString directionAn attribute to indicate whether the call had been dialed, received, missed, blocked, or rejected. The following values are supported:
- DIALED - for dialed calls
- RECEIVED - for received calls
- MISSEDNEW - for missed calls not seen yet
- MISSED - for missed calls
- BLOCKED - for blocked calls
- REJECTED - for rejected calls
Since: 2.0
-
readonly
DOMString callingParty [nullable]Indicates the phone number of SIM card used for the call.
It is the device's local phone number - the number assigned to the SIM card (see SystemInfoSIM). If there is more than one SIM card in the device, this attribute can be used to recognize which SIM card was used to make/receive the call.
Since: 2.3
Remark: A null value means that the phone number of the device cannot be retrieved because the device user might not allow this functionality.
1.4. CallHistory
[NoInterfaceObject] interface CallHistory { void find(CallHistoryEntryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? limit, optional unsigned long? offset) raises(WebAPIException); void remove(CallHistoryEntry entry) raises(WebAPIException); void removeBatch(CallHistoryEntry[] entries, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void removeAll(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); long addChangeListener(CallHistoryChangeCallback observer) raises(WebAPIException); void removeChangeListener(long handle) raises(WebAPIException); };
Since: 2.0
Methods
-
find
-
Finds and returns call history.
void find(CallHistoryEntryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? limit, optional unsigned long? offset);
Since: 2.0
The errorCallback() is launched with these error types:
- InvalidValuesError - If any of the input parameters contain an invalid value.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/callhistory.read
Parameters:
- successCallback: A handler for a query result set.
- errorCallback [optional] [nullable]: The method to call when an error occurs.
- filter [optional] [nullable]: A filter defined on CallHistoryEntry attributes. It can be a composite filter.
- sortMode [optional] [nullable]: The sort order in which call history is returned.
- limit [optional] [nullable]: The maximum limit of a query result (It has the same meaning as SQL LIMIT). If the limit is 0, the query result has no limit.
-
offset [optional] [nullable]:
The offset in the result set, from where the results are listed (It has the same semantics as SQL OFFSET).
The maximum number of results listed is the value of the specified limit parameter. Default value is 0, meaning no offset.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if the feature is not supported.
Code example:
/* Defines success callback. */ function onSuccess(results) { console.log(results.length + " call history item(s) found!"); for (var i = 0; i < results.length; i++) { console.log(i + ". " + results[i].toString()); /* Process the CallHistoryEntry. */ } } /* Defines error callback. */ function onError(error) { console.log("Query failed: " + error.name); } /* Defines filter: list CS calls, most recent first. */ var filter = new tizen.AttributeFilter("type", "EXACTLY", "TEL"); /* Defines sort mode: descending on call start time. */ var sortMode = new tizen.SortMode("startTime", "DESC"); /* Makes the query and wires up the callbacks. */ tizen.callhistory.find(onSuccess, onError, filter, sortMode); var numberfilter = new tizen.AttributeFilter("remoteParties.remoteParty", "EXACTLY", "123456789"); /* Creates 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)); var datefilter = new tizen.CompositeFilter("UNION", [y2009Filter, y2011Filter]); /* Creates a filter to find all video calls (including cellular, skype, etc). */ /* Filter matches any features from the "features" array exactly. */ var tfilter = new tizen.AttributeFilter("features", "EXACTLY", "VIDEOCALL"); /* Creates a composite filter. */ var ifilter = new tizen.CompositeFilter("INTERSECTION", [numberFilter, dateFilter, tfilter]); /* Makes the query and wires up the callbacks; reuse sortMode. */ tizen.callhistory.find(onSuccess, onError, ifilter, sortMode);
-
remove
-
Removes call history synchronously.
void remove(CallHistoryEntry entry);
Since: 2.0
Privilege level: public
Privilege: http://tizen.org/privilege/callhistory.write
Parameters:
- entry: Call history entry to be deleted.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if the feature is not supported.
with error type UnknownError, if any other error occurs.
Code example:
/* Defines success callback. */ function onSuccess(results) { if (results.length > 0) { tizen.callhistory.remove(results[0]); } } /* Defines error callback. */ function onError(error) { console.log("Query failed: " + error.name); } /* Makes the query and wires up the callbacks. */ tizen.callhistory.find(onSuccess, onError);
-
removeBatch
-
Removes a call history list asynchronously.
void removeBatch(CallHistoryEntry[] entries, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.0
The errorCallback() is launched with these error types:
- InvalidValuesError - If any of the input parameters contain an invalid value.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/callhistory.write
Parameters:
- entries: A list of call history entries to delete.
- successCallback [optional] [nullable]: A generic success handler.
- errorCallback [optional] [nullable]: An error handler.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if this feature is not supported.
Code example:
/* Defines success callback. */ function onSuccess(results) { tizen.callhistory.removeBatch(results); } /* Defines error callback. */ function onError(error) { console.log("Query failed: " + error.name); } /* Makes the query and wires up the callbacks. */ tizen.callhistory.find(onSuccess, onError);
-
removeAll
-
Removes call history asynchronously.
void removeAll(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 2.0
The errorCallback() is launched with these error types:
- InvalidValuesError - If any of the input parameters contain an invalid value.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/callhistory.write
Parameters:
- successCallback [optional] [nullable]: A generic success handler.
- errorCallback [optional] [nullable]: An error handler.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if this functionality is not allowed.
with error type NotSupportedError, if this feature is not supported.
-
addChangeListener
-
Adds a listener to register for callback to observe call history changes.
long addChangeListener(CallHistoryChangeCallback observer);
Since: 2.0
Privilege level: public
Privilege: http://tizen.org/privilege/callhistory.read
Parameters:
- observer: A callback for handling the list of new or changed or CallHistoryEntry objects in the call history.
Return value:
-
long:
A handle which can be used for unregistering.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if the feature is not supported.
with error type UnknownError, if any other error occurs.
Code example:
var onListenerCB = { onadded: function(newItems) { console.log("New Item added"); for (var i in newItems) { console.log("Item " + i + " startTime: " + newItems[i].startTime); } }, onchanged: function(changedItems) { console.log("Items changed"); for (var i in changedItems) { console.log("Item " + i + " direction: " + changedItems[i].direction); } }, onremoved: function(removedItems) { console.log("Items removed"); for (var i in removedItems) { console.log("Item " + i + ": " + removedItems[i]); } } }; try { /* Registers a call history callback. */ var handle = tizen.callhistory.addChangeListener(onListenerCB); /* Unregisters a previously registered listener. */ tizen.callhistory.removeChangeListener(handle); } catch (error) { console.log("Exception - code: " + error.name + " message: " + error.message); }
-
removeChangeListener
-
Removes a listener to unregister a previously registered listener.
void removeChangeListener(long handle);
Since: 2.0
Privilege level: public
Privilege: http://tizen.org/privilege/callhistory.read
Parameters:
- handle: The previously obtained listener handle.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any input parameter contains invalid values.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type NotSupportedError, if the feature is not supported.
with error type UnknownError, if any other error occurs.
1.5. CallHistoryEntryArraySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface CallHistoryEntryArraySuccessCallback { void onsuccess(CallHistoryEntry[] entries); };
Since: 2.0
Methods
-
onsuccess
-
Called when the queries on call history have been successfully completed.
void onsuccess(CallHistoryEntry[] entries);
Since: 2.0
Parameters:
- entries: An array of CallHistoryEntry objects, representing the result set of the query over the call history.
1.6. CallHistoryChangeCallback
[Callback, NoInterfaceObject] interface CallHistoryChangeCallback { void onadded(CallHistoryEntry[] newItems); void onchanged(CallHistoryEntry[] changedItems); void onremoved(DOMString[] removedItems); };
Since: 2.0
Methods
-
onadded
-
Called when a new call history item is added.
void onadded(CallHistoryEntry[] newItems);
Since: 2.0
Parameters:
- newItems: An array of CallHistoryEntry objects, representing the new items added to call history.
-
onchanged
-
Called when the call history has been changed.
void onchanged(CallHistoryEntry[] changedItems);
Since: 2.0
Parameters:
- changedItems: An array of CallHistoryEntry objects, representing the changed items in call history.
-
onremoved
-
Called when the call history has been removed.
void onremoved(DOMString[] removedItems);
Since: 2.0
Parameters:
- removedItems: An array of a UID of CallHistoryEntry objects, representing the removed items in call history.
2. Related Feature
To guarantee that the call log application runs on a device with the telephony feature, declare the following feature requirements in the config file:
3. Full WebIDL
module CallHistory { Tizen implements CallHistoryObject; [NoInterfaceObject] interface CallHistoryObject { readonly attribute CallHistory callhistory; }; [NoInterfaceObject] interface RemoteParty { readonly attribute DOMString? remoteParty; readonly attribute PersonId? personId; }; [NoInterfaceObject] interface CallHistoryEntry { readonly attribute DOMString uid; readonly attribute DOMString type; readonly attribute DOMString[]? features; readonly attribute RemoteParty[] remoteParties; readonly attribute Date startTime; readonly attribute unsigned long duration; attribute DOMString direction; readonly attribute DOMString? callingParty; }; [NoInterfaceObject] interface CallHistory { void find(CallHistoryEntryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? limit, optional unsigned long? offset) raises(WebAPIException); void remove(CallHistoryEntry entry) raises(WebAPIException); void removeBatch(CallHistoryEntry[] entries, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void removeAll(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); long addChangeListener(CallHistoryChangeCallback observer) raises(WebAPIException); void removeChangeListener(long handle) raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface CallHistoryEntryArraySuccessCallback { void onsuccess(CallHistoryEntry[] entries); }; [Callback, NoInterfaceObject] interface CallHistoryChangeCallback { void onadded(CallHistoryEntry[] newItems); void onchanged(CallHistoryEntry[] changedItems); void onremoved(DOMString[] removedItems); }; };