Samsung Electronics logo

Samsung Web API: Callhistory


Introduction

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

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


Table of Contents


Summary of Interfaces and Methods

Interface Method
CallHistoryObject
RemoteParty
CallHistoryEntry
CallHistory void find(CallHistoryEntryArraySuccessCallback successCallback, ErrorCallback? errorCallback, AbstractFilter? filter, SortMode? sortMode, unsigned long? limit, unsigned long? offset)
void remove(CallHistoryEntry entry)
void removeBatch(CallHistoryEntry[] entries, SuccessCallback? successCallback, ErrorCallback? errorCallback)
void removeAll(SuccessCallback? successCallback, 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

This interface defines what is instantiated by the WebAPIs object from the platform. The webapis.callhistory object allows access to the CallHistory API.

    [NoInterfaceObject] interface CallHistoryObject {
        readonly attribute CallHistory callhistory;
    };
    WebAPIs implements CallHistoryObject;

1.2. RemoteParty

This interface represents remote parties.

    [NoInterfaceObject] interface RemoteParty {
        readonly attribute DOMString? remoteParty;

        readonly attribute PersonId? personId;

    };

ATTRIBUTES

readonly DOMString? remoteParty

An attribute to store the RPID. The remote party identifier (RPID) that 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).

This attribute is read-only.

readonly PersonId? personId

An attribute to store the identifier of the person that the raw contact belongs to.

If the contact cannot be resolved, the value is null. See Contact API for more information.

This attribute is read-only.

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

ATTRIBUTES

readonly DOMString uid

An attribute to store The unique identifier of a call record.

This attribute is read-only.

readonly DOMString type

An attribute to store the service type of the call saved to call history.

The following values are the supported:

  • TEL - for all protocols with phone number addressing (PSTN, GSM, CDMA, LTE, etc.)
  • XMPP - for generic XMPP calls
  • SIP - for generic SIP calls
This attribute is read-only.

readonly DOMString[]? features

An array of attributes to store the features associated with the call service are saved to call history. The following values are the supported:

  • CALL - for all call types
  • VOICECALL - for voice-only calls
  • VIDEOCALL - for audio and video channel support in the call
  • EMERGENCYCALL - to denote an emergency call
This attribute is read-only.

readonly RemoteParty[] remoteParties

An array of attributes to store the remote parties participating in the call.

This attribute is read-only.

readonly Date startTime

An attribute to store the start time of the call. The exact meaning is defined by the back-end. The intention of this attribute is to give the moment when media channels come up.

This attribute is read-only.

readonly unsigned long duration

An attribute to store the duration of the call in seconds. The exact meaning is defined by the back-end. The intention of this attribute is to count the duration from media channels up to the moment when media channels tear down, on the same call service. If the call gets migrated to another service, another call history entry is used.

This attribute is read-only.

DOMString direction

An attribute to store to indicate whether the call was dialed, received, missed, blocked or rejected. The following values are the 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

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

METHODS

find

Finds and returns call history.

Signature
void find(CallHistoryEntryArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional AbstractFilter? filter, optional SortMode? sortMode, optional unsigned long? limit, optional unsigned long? offset);

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.
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No.
    • Type: CallHistoryEntryArraySuccessCallback.
    • Description: A handler for query result set.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: The method to call when an error occurs.
  • filter
    • Optional: Yes.
    • Nullable: Yes.
    • Type: AbstractFilter.
    • Description: A filter defined on CallHistoryEntry attributes. It can be a composite filter.
  • sortMode
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SortMode.
    • Description: A variable to determine the sort order in which call history are return.
  • limit
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: A variable to represent the maximum limit of query result (It is the same meaning as SQL LIMIT). If limit is 0, query result is no limit.
  • offset
    • Optional: Yes.
    • Nullable: Yes.
    • Type: unsigned long.
    • Description: The offset in the result set, from where the results are listed (It is the same semantics as SQL OFFSET).
      The number of results listed is maximum the specified limit parameter. Defaults to 0, meaning no offset.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

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 webapis.AttributeFilter("type", "EXACTLY", "TEL");

 // Defines sort mode: descending on call start time.
 var sortMode = new webapis.SortMode("startTime", "DESC");

 // Makes the query and wire up the callbacks
 webapis.callhistory.find(onSuccess,
                         onError,
                         filter,
                         sortMode);

 var numberfilter = new webapis.AttributeFilter(
                                 "remoteParties.remoteParty",
                                 "EXACTLY",
                                 "123456789");
                   
 // Creates a composite filter for time constraints
 var y2009Filter = new webapis.AttributeRangeFilter(
                                "startTime",
                                new Date(2009, 0, 1),
                                new Date(2010, 0, 1));

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

 var datefilter = new webapis.CompositeFilter("UNION", [y2009Filter, y2011Filter]);

 // Creates a filter to find all video calls (including cellular, skype, etc)
 // The filter matches exactly any features from the "features" array
 var tfilter = new webapis.AttributeFilter("features", "EXACTLY", "VIDEOCALL");

 // Creates composite filter
 var ifilter = new webapis.CompositeFilter("INTERSECTION",
                                         [numberFilter, dateFilter, tfilter]);

 // Makes the query and wire up the callbacks; reuse sortMode
 webapis.callhistory.find(onSuccess,
                         onError,
                         ifilter,
                         sortMode);

 

remove

Removes a call history synchronously.

Signature
void remove(CallHistoryEntry entry);
Parameters
  • entry
    • Optional: No.
    • Nullable: No.
    • Type: CallHistoryEntry.
    • Description: Call history entry to be deleted.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

Code example
 // Defines success callback
 function onSuccess(results) {
     if (results.length > 0)
         webapis.callhistory.remove(results[0]);
 }

 // Defines error callback
 function onError(error) {
     console.log("Query failed" + error.name);
 }

 // Makes the query and wires up the callbacks
 webapis.callhistory.find(onSuccess, onError);

 

removeBatch

Removes a list of call history asynchronously.

Signature
void removeBatch(CallHistoryEntry[] entries, optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

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.
Parameters
  • entries
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: A list of call history entries to delete.
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: A generic success handler.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: An error handler.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

Code example
 // Defines success callback
 function onSuccess(results) {
     webapis.callhistory.removeBatch(results);
 }

 // Defines error callback
 function onError(error) {
     console.log("Query failed" + error.name);
 }

 // Makes the query and wires up the callbacks
 webapis.callhistory.find(onSuccess, onError);

 

removeAll

Removes all call history asynchronously.

Signature
void removeAll(optional SuccessCallback? successCallback, optional ErrorCallback? errorCallback);

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.
Parameters
  • successCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: SuccessCallback.
    • Description: A generic success handler.
  • errorCallback
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ErrorCallback.
    • Description: An error handler.
Exceptions
  • WebAPIException:

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if this functionality is not allowed.

    with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.

addChangeListener

Adds a listener to register for callback to observe call history changes.

Signature
long addChangeListener(CallHistoryChangeCallback observer);
Parameters
  • observer
    • Optional: No.
    • Nullable: No.
    • Type: CallHistoryChangeCallback.
    • Description: 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 UnknownError, if any other error occurs.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

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 = webapis.callhistory.addChangeListener(onListenerCB);

     // Unregisters a previously registered listener
     webapis.callhistory.removeChangeListener(handle);
 } catch (error) {
     console.log("Exception - code: " + error.name + " message: " + error.message);
 }

 

removeChangeListener

Removes a listener to unregister a previously registered listener.

Signature
void removeChangeListener(long handle);
Parameters
  • handle
    • Optional: No.
    • Nullable: No.
    • Type: long.
    • Description: The previously obtained listener handle.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type NotSupportedError, if the feature is not supported.

    with error type SecurityError, if the functionality is not allowed.

    with error type InvalidValuesError, if any input parameter contains invalid values.

    with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

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

METHODS

onsuccess

Called when the queries on call history have been successfully completed.

Signature
void onsuccess(CallHistoryEntry[] entries);
Parameters
  • entries
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: 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 a CallHistory operations. For example code, see CallHistory interface.

    [Callback, NoInterfaceObject]
    interface CallHistoryChangeCallback {
        void onadded(CallHistoryEntry[] newItems);

        void onchanged(CallHistoryEntry[] changedItems);

        void onremoved(DOMString[] removedItems);
    };

METHODS

onadded

Called when a new call history item is added.

Signature
void onadded(CallHistoryEntry[] newItems);
Parameters
  • newItems
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of CallHistoryEntry objects, representing the new items added to call history.

onchanged

Called when the call history have been changed.

Signature
void onchanged(CallHistoryEntry[] changedItems);
Parameters
  • changedItems
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of CallHistoryEntry objects, representing the changed items in call history.

onremoved

Called when the call history have been removed.

Signature
void onremoved(DOMString[] removedItems);
Parameters
  • removedItems
    • Optional: No.
    • Nullable: No.
    • Type: array.
    • Description: An array of an uid of CallHistoryEntry objects, representing the removed items in call history.

2. Full WebIDL

module Callhistory {
    [NoInterfaceObject] interface CallHistoryObject {
        readonly attribute CallHistory callhistory;
    };
    
    WebAPIs implements CallHistoryObject;

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

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