The Contacts API lets you add, change, and delete entries in the Contacts app on a device. You can add new contacts and specify information such as email and postal addresses, phone numbers, and photos. You can also specify more detailed information about a contact, such as whether a phone number is a work phone number, home phone number, or mobile phone number.

The Contact class represents a contact in the Contacts app. A set of ContactAttribute objects represents the information that's associated with a contact. A ContactAttribute is a single piece of information about a contact, such as an email address or a phone number. There's no limit to the number of attributes that a contact can have.

In addition to the general ContactAttribute class, which is used to represent a wide range of contact information, the Contacts API also includes several specialized classes that represent specific types of information. For example, the ContactPostalAddress class represents the postal address of a contact, and this class includes detailed information such as city, country, latitude, and longitude. The ContactPhoto class represents a set of photos that are associated with a contact, including both large photos and small photos.

Screen illustrating a Contact object.

Several classes in the Contacts API use the builder design pattern, which makes it easy to create instances of these classes and specify values for their properties. For example, the Contact class has a builder class called  ContactBuilder. Each of the functions in ContactBuilder returns a self reference to the builder, allowing you to chain function calls together.


To use the Contacts 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 Contacts permission ( access_pimdomain_contacts), which you specify in the bar-descriptor.xml file for your app.

Manipulating contacts

To create a new contact and add it to the contact database, you create a ContactBuilder object for the contact that you want to add. This object lets you add the attributes for the contact. You also create builder objects that correspond to the attributes that you want to add. For example, if you want to add a postal address, you create a ContactPostalAddressBuilder object and use its functions to populate the address information.

After you populate the attributes and add them to the contact, you can call ContactService::createContact() to add the contact to the database. You can also use ContactService::createContacts() to add multiple contacts to the database at once.

Not applicable

Here's how to create a contact and add a postal address and home phone number to the contact:

#include <bb/pim/contacts/ContactService>
#include <bb/pim/contacts/ContactBuilder>
#include <bb/pim/contacts/ContactPostalAddressBuilder>
#include <bb/pim/contacts/ContactAttributeBuilder>
#include <bb/pim/contacts/Contact>

using namespace bb::pim::contacts;
// Create the contact service object so you can access the
// database
ContactService service;
// Create the builder objects, which are used to create the
// contact, postal address, and home phone number
ContactBuilder contactBuilder;
ContactPostalAddressBuilder addressBuilder;
ContactAttributeBuilder attributeBuilder;
// Create the postal address
addressBuilder.setLine1("2220 University Ave. E.")
              .setPostalCode("N2K 0A8");
// Create the home phone number
// Add the postal address and home phone number to the contact
// Add the contact to the database
Contact createdContact = service.createContact(contactBuilder,

Not applicable

To update the value of an existing contact in the database, you need to retrieve the full details of an existing contact (see Retrieving contact details). Then, you can update the contact information by using the appropriate builder object and call ContactService::updateContact() to update the contact in the database.

Not applicable

Here's how to update the value of an existing contact in the database:

#include <bb/pim/contacts/ContactService>
#include <bb/pim/contacts/Contact>
#include <bb/pim/contacts/ContactBuilder>
#include <bb/pim/contacts/ContactAttributeBuilder>

using namespace bb::pim::contacts;
// Create the contact service object so you can access the
// database
ContactService service;
// Retrieve the full details of an existing contact
Contact contact = service.contactDetails(42);
// If the existing contact was retrieved successfully, update the
// contact information
if ( {
    ContactBuilder editor = contact.edit();
    Contact updatedContact = service.updateContact(editor);

Not applicable

Retrieving contact details

There are several functions in  ContactService that let you retrieve lists of contacts. For example, the  contacts() function returns a list of contacts that fit the criteria that you specify. However, each contact that's returned is a partial contact and has limited information attached to it. You can use these partial contacts to populate a list view, and they provide better performance than returning contacts with full details.

If you need to retrieve all of the information that's associated with a contact, you can call ContactService::contactDetails(). Contacts that are retrieved using this function contain a full set of data. Before you update the information of an existing contact using  updateContact(), make sure to retrieve the complete contact information using contactDetails(). Otherwise, you could lose some contact information because it might be overwritten with partial contact data.

Specifying attribute kinds and subkinds

The ContactAttribute class is designed to support a wide range of attributes that you can add to a contact, which gives you extra flexibility when you use contacts in your app. For example, a ContactAttribute might represent a phone number, an email address, a name, or some other piece of information. You might even have some custom information that's specific to your application and that you want to associate with a contact.

Screen showing kinds and subkinds for a contact.

You can use kinds and subkinds to specify the information that a ContactAttribute holds. A kind specifies metadata about the type of an attribute. The AttributeKind::Type enumeration represents a kind and includes values such as Name, Email, and Phone. You can think of a kind as a general classification for the type of information an attribute represents.

To supplement the kind of an attribute, you can be even more specific and provide a subkind. A subkind specifies more granular metadata about the type of an attribute. The AttributeSubKind::Type enumeration represents a subkind. For example, if the kind of attribute is a phone number (represented by AttributeKind::Phone), then possible subkinds might be AttributeSubKind::WorkAttributeSubKind::Home, and so on. By using combinations of kinds and subkinds, you can specify a wide range of attributes for contacts.

When you want to display a kind/subkind combination in your app, it can be helpful to have a string representation of the kind and subkind. For example, if you want to display a work phone number (that is, the contact uses AttributeKind::Phone and AttributeSubKind::Work), you might want to display a field that's labeled "Phone (Work)" in your UI. You can use ContactAttribute::attributeDisplayLabel() to retrieve a localized string that represents the kind and subkind of the attribute. The Contacts API recognizes many common kind/subkind combinations and can provide you with strings to use in your UI. Alternatively, you can specify your own label for the attribute by using  ContactAttributeBuilder::setLabel() when you create the attribute.

Filtering contacts

When you manipulate contacts in your apps, you might want to retrieve a list of contacts that fit certain criteria. For example, you might want to retrieve only the contacts that have a particular attribute, or search for contacts that include a specific string. You might also want to retrieve a list of contacts in a particular order, such as ascending alphabetically by last name.

You can use the  ContactListFilters class and  ContactSearchFilters class to specify criteria for a set of contacts that you're interested in. The ContactListFilters class is designed to work with ContactService::contacts() to specify the number, type, and sorting of the contacts that are returned. The ContactSearchFilters class is designed to work with the various search functions in ContactService, such as  ContactService::searchContacts() and ContactService::searchContactsByPhoneNumber().

Not applicable

Here's how to create a ContactSearchFilters object that searches for contacts that contain the letter "H". By default, a ContactSearchFilters searches the first name, last name, company name, phone number, and email attributes for the specified value, but you can specify the fields that you want to search by using  setSearchFields().

#include <bb/pim/contacts/ContactService>
#include <bb/pim/contacts/ContactSearchFilters>
#include <bb/pim/contacts/Contact>

using namespace bb::pim::contacts;
// Create the contact service object
ContactService service;
// Create the search filter and set the search value
ContactSearchFilters options;
// Retrieve the list of contacts that fit the filter's criteria
QList<Contact>contacts = service.searchContacts(options);

Not applicable

You can call setLimit() to set a limit on the number of results that you obtain when you use a filter. This limit can be useful if you're searching a large set of contacts and don't want to retrieve all of the results at once. Instead, you could choose to display only a small set of initial results from the query, and then retrieve additional results if the user requests them. By default, if you don't set a limit on the number of results, a maximum of 20 results are retrieved.

Last modified: 2015-05-07

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

comments powered by Disqus