Samsung Electronics logo

Searching for Call History Items

Learning how to retrieve call history items using different parameters allows you to view specific items in a specific order, making call history monitoring easy and convenient.

  1. To retrieve call history items, use the find(successCallback, errorCallback, filter, sortMode, limit, offset) method of the CallHistory interface.

    This method is asynchronous, and the result of the query is an array of CallHistoryEntry objects.

    webapis.callhistory.find(onSuccess, onError, ifilter, sortMode, 20, 10);
  2. Use the SuccessCallback parameter of the find() method to define an event handler for the query result set.

    In the following code snippet, the found call history items are appended to the console log.

    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 */
  3. Use the filter parameter of the find() method to define a filter for the query result set. A filter with the CallHistoryEntry attributes is used to limit the results of the call history search.

    You can define various filters:

    • The AttributeFilter type is used to search based on a single CallHistoryEntry attribute (for attributes supported in the filter, see CallHistory Filter Attributes).

      For example, the following filters define that only cellular calls or calls where the remote party has the telephone number 123456789 are included in the query results:

      /* First filter example */
      var filter = new webapis.AttributeFilter("type", "EXACTLY", "TEL");
      /* Second filter example */
      var numberFilter = new webapis.AttributeFilter("remoteParties.remoteParty", "EXACTLY", "123456789")
    • The CompositeFilter type 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.

      For example, the following code snippet defines a set of filters that include in the query results only the video calls where the remote party has the telephone number 123456789 and the call has started during the year 2009 or 2011:

      /* Create the ranges for the time filter */
      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));
      /* Create a time filter */
      var datefilter = new webapis.CompositeFilter("UNION",
                                                 [y2009Filter, y2011Filter]);
      /* Create a video call filter */
      var tfilter = new webapis.AttributeFilter("features", "EXACTLY", "VIDEOCALL");
      /* Combine the filters into a set */
      var ifilter = new webapis.CompositeFilter("INTERSECTION", [numberFilter, dateFilter, tfilter]);
  4. Use the sortMode order parameter for the query result set. If the parameter is undefined or set to null, the results are sorted by default in a descending order based on the startTime attribute.

    In the following code snippet, the found call history items are sorted according to the start time, in descending order:

    var sortMode = new webapis.SortMode("startTime", "DESC"};
  5. Use the limit and offset parameters of the find() method to specify the starting point and upper limit of the results that are returned.

    The limit parameter specifies the maximum number of matching results that are returned (the value 0 makes the limit infinite), while the offset parameter skips that many matching results that are to be returned (the value 0 means nothing is skipped).

    For example, if your search results consist of 100 matching results and you have specified an offset of 10 and a limit of 20, you get the objects from 10-29. The matching results from 0-9 are skipped due to the offset, and the 20 results starting from the first result after the offset are returned.