Phone

If you're using API level 10.3 or later, you can use the personal information management (PIM) Phone API to gather information about past incoming or outgoing phone calls on a device. You can use the PIM Phone API to retrieve the history of calls (also called the call log), which you can filter to display only calls that fit certain criteria in your app. You can also retrieve the properties for a particular call and identify the contacts who were involved in the call.

The PIM Phone API returns information about past calls only. For information about APIs that let you initiate calls and perform real-time operations on calls that are in progress, see Telephony.

The CallEntry class represents a single past call. This class includes details of the call, such as the caller name (as provided by the network, such as a caller ID value), phone number, call type (incoming, outgoing, missed, or unknown), duration, and line ID (such as cellular).

Like other PIM APIs (such as the Contacts API), the PIM Phone API includes a service class, CallHistoryService, that's used to interact with the call history database on the device. You can use this service class to retrieve the call history by using the callHistory() function. The service class also includes the callHistoryAdded() and callHistoryDeleted() signals, which you can monitor when you want to know when calls are added to or deleted from the call history.

Screen showing the call history on a device.

The callHistory() function returns a list of CallEntryResult objects, each of which corresponds to a call in the call history. You can retrieve the associated CallEntry object by using the call() function, and you can also identify which contacts were involved in the call by using the contacts() function. To use the contacts() function, you need to enable contact search by using a filter. To learn more about filtering, see Filtering call history results.

To identify any errors that might occur when you call callHistory(), you can provide a CallHistoryError object as a parameter. This object stores the result of callHistory() and includes values to indicate if there was no error, an unknown error, or an error because the requested data doesn't exist.

Prerequisites

To use the PIM Phone API in your app, you need to link against the correct library by adding the following line to your project's .pro file:

LIBS += -lbbpim

Your app must also have the Phone Call Logs permission ( access_pimdomain_calllogs), which you specify in the bar-descriptor.xml file for your app.

Retrieving the call history

There are two versions of callHistory() that you can use to retrieve the call history, depending on whether you want a set of calls or just a single call from the history:

callHistory(bb::pim::account::AccountKey,
            const CallHistoryFilter&,
            const CallHistoryParam&,
            CallHistoryError::Type*)

This version takes a CallHistoryFilter object as a parameter, which specifies a set of criteria that's used to filter the results that you receive. This function lets you retrieve a list of calls based on information that's important in your app and in a sort order that you specify. To learn more, see Filtering call history results.

callHistory(bb::pim::account::AccountKey,
            CallEntryId,
            const CallHistoryParam&,
            const CallHistoryError::Type*)

Instead of taking a CallHistoryFilter object, this version takes a CallEntryId as a parameter, which specifies a particular call to retrieve from the call history. This version is equivalent to calling the first version of callHistory() with a CallHistoryFilter that contains a call ID.

Not applicable

Here's how to use both versions of callHistory() to retrieve either the entire call history or a specific call within the history:

#include <bb/pim/phone/CallHistoryService>
#include <bb/pim/phone/CallHistoryFilter>
#include <bb/pim/phone/CallHistoryParam>
#include <bb/pim/phone/CallHistoryError>
#include <bb/pim/phone/CallEntryResult>
#include <bb/pim/phone/CallEntry>

#include <bb/pim/account/Account>

using namespace bb::pim::phone;
// Create the call history service object
CallHistoryService callHistoryService;

// Retrieve the default call history account on the device. The
// ID of a valid account is required when calling callHistory()
bb::pim::account::Account defaultAccount =
                          callHistoryService.defaultAccount();

// Create a default-constructed CallHistoryFilter. By passing
// this type of CallHistoryFilter to callHistory(), all calls
// in the call history are returned
CallHistoryFilter defaultFilter;

// Create a CallHistoryParam with contact search disabled.
// Contact search is useful if you want to identify the contacts
// that were involved in a call
CallHistoryParam callHistoryParams;
callHistoryParams.setContactSearchEnabled(false);

// Create a CallHistoryError to store the result of callHistory()
CallHistoryError *callHistoryError = new CallHistoryError();

// Retrieve the call history
QList<CallEntryResult> callHistoryResults =
                       callHistoryService.callHistory(
                           defaultAccount.id(),
                           defaultFilter,
                           callHistoryParams,
                           callHistoryError);

// ...

// Retrieve a specific call from the call history
CallEntryResult specificCallResult =
                callHistoryService.callHistory(
                    defaultAccount.id(),
                    134,
                    callHistoryParams,
                    callHistoryError);

// Retrieve the CallEntry object from the CallEntryResult
CallEntry actualCall = specificCallResult.call();

Not applicable

Filtering call history results

You might want to retrieve a subset of the full call history (for example, only those calls that occurred after a particular date and time, or only incoming calls). You may also want the results of callHistory() to be sorted in a specific way, such as in descending order by start date and time.

You can use the CallHistoryFilter class, combined with supporting classes such as CallAttribute and SortOrder, to specify the results that you receive from callHistory(). Here's a summary of some of the ways you can filter the results using functions in CallHistoryFilter:

The CallHistoryParam class provides additional parameters for callHistory(). Specifically, you can use setContactSearchEnabled() to indicate whether you want to search for potential contacts that match the call results from callHistory(). Because this search is a potentially expensive operation in terms of processing power, you can disable it if you aren't interested in retrieving the contacts that were involved in a call.

If contact search is enabled, you can use CallEntryResult::contacts() to retrieve a list of contacts that are involved in the call. The ContactEntry class represents these types of contacts, and this class is part of the bb::pim::common namespace. You can call accountId() and id() to retrieve the account ID and contact ID of the contact, respectively.

Not applicable

Here's how to use CallHistoryFilter to retrieve calls that occurred after a particular date, in ascending order by caller name:

#include <bb/pim/phone/CallHistoryService>
#include <bb/pim/phone/CallHistoryFilter>
#include <bb/pim/phone/CallAttribute>
#include <bb/pim/phone/SortOrder>
#include <bb/pim/phone/CallHistoryParam>
#include <bb/pim/phone/CallHistoryError>
#include <bb/pim/phone/CallEntryResult>

#include <bb/pim/common/ContactEntry>

#include <bb/pim/account/Account>

using namespace bb::pim::phone;
// Create the call history service object
CallHistoryService callHistoryService;

// Retrieve the default call history account on the device. The
// ID of a valid account is required when calling callHistory()
bb::pim::account::Account defaultAccount =
                          callHistoryService.defaultAccount();

// Create a CallHistoryFilter with the specified set of filter
// criteria. This filter specifies calls that occurred after
// March 3, 2014, sorted in ascending order by caller name
CallHistoryFilter specificFilter;
QDateTime date(QDate(2014, 3, 3));
specificFilter.setEarliest(date);
specificFilter.setSortAttribute(CallAttribute::Name);
specificFilter.setSortOrder(SortOrder::Ascending);

// Create a CallHistoryParam with contact search enabled.
// Contact search is useful if you want to identify the contacts
// that were involved in a call
CallHistoryParam callHistoryParams;
callHistoryParams.setContactSearchEnabled(true);

// Create a CallHistoryError to store the result of callHistory()
CallHistoryError *callHistoryError = new CallHistoryError();

// Retrieve the call history
QList<CallEntryResult> callHistoryResults =
                       callHistoryService.callHistory(
                           defaultAccount.id(),
                           specificFilter,
                           callHistoryParams,
                           callHistoryError);

// Retrieve the list of contacts involved in a specific call in
// the history (say, the first call returned)
QList<bb::pim::common::ContactEntry> involvedContacts =
                       callHistoryResults.at(0).contacts();

Not applicable

Related resources

Last modified: 2015-05-07



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus