CallHistory API

This API provides interfaces and methods for retrieving information from the call history.

For more information on the Call History features, see Call History Guide.

Since: 2.0

Table of Contents


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 removeBatch (CallHistoryEntry[] entries, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void removeAll (optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback)
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

This interface defines what is instantiated by the Tizen object from the Tizen Platform. The tizen.callhistory object allows access to the Call History API.
  [NoInterfaceObject] interface CallHistoryObject {
    readonly attribute CallHistory callhistory;
  };
  Tizen implements CallHistoryObject;

Since: 2.0

Attributes

  • readonly CallHistory callhistory
    Object representing a callhistory.

    Since: 2.0

1.2. RemoteParty

This interface represents remote parties.
  [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

This interface represents the subset of properties of calls, which become a call record in the call history after the call ends.
  [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 uid
    An attribute to store the unique identifier of a call record.

    Since: 2.0

  • readonly DOMString type
    An 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[] remoteParties
    An attribute to store the remote parties participating in the call.

    Since: 2.0

  • readonly Date startTime
    An 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 duration
    An 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 direction
    An 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

This interface manages call history. Apps can read or delete call history (depending on permission). Modifying call history is allowed for certain attributes, like direction. Adding call history is owned by the back-end. Filtering is supported for all fields of CallHistoryEntry.
  [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

This is a callback interface of CallHistory operations. For example code, see CallHistory interface.
  [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

This is a callback interface of CallHistory operations. For example code, see CallHistory interface.
  [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

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee that the call log application runs on a device with the telephony feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/network.telephony
  • For more information, see Application Filtering.

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