Contacts

The Contacts API lets you add, modify, and delete entries in the Contacts application on a device. You can add new contacts and specify information such as email and postal addresses, phone numbers, photos, and so on. 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.

Each contact in the Contacts application is represented by a Contact object. The information that's associated with a contact is represented by a set of  ContactAttribute objects. A ContactAttribute represents 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 apps, you need to import the correct library by adding the following line to your project's .pro file:

LIBS += -lbbpim

Your app must also have the access_pimdomain_contacts permission, which you specify in the bar-descriptor.xml file for your app. To learn more about the bar-descriptor.xml file, see The bar-descriptor.xml file.

Here's how to create a contact and add a postal address and home phone number to the contact. To save your contacts to the database, you need to create and use a ContactService object.

// Create the contact service object
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("419 Phillip St.")
              .setCity("Waterloo")
              .setRegion("Ontario")
              .setCountry("Canada")
              .setPostalCode("N2L 3X2");
 
// Create the home phone number
attributeBuilder.setKind(AttributeKind::Phone)
                .setSubKind(AttributeSubKind::Home)
                .setValue("519-888-7465");
                 
// Add the postal address and home phone number to the contact
contactBuilder.addPostalAddress(addressBuilder);
contactBuilder.addAttribute(attributeBuilder);
 
// Add the contact to the database
Contact createdContact = service.createContact(contactBuilder, false);

You can also update the value of an existing contact in the database. Here's how to do that:

// Create the contact service object
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 (contact.id()) {
    ContactBuilder editor = contact.edit();
    editor.addAttribute(ContactAttributeBuilder()
                        .setKind(AttributeKind::Phone)
                        .setSubKind(AttributeSubKind::Work)
                        .setValue("555-6745"));
    Contact updatedContact = service->updateContact(editor);
}

Using the Contacts API

The following sections outline some important concepts about contacts. You may find these concepts useful as you work with contacts in your apps.

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 very little information attached to it. These partial contacts are designed to be used 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 sub-kinds

The ContactAttribute class is designed to support a wide range of attributes that you can add to a contact. 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.

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

Screen showing kinds and subkinds for a contact.

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

When you want to display a kind/sub-kind combination in your app, it can be helpful to have a string representation of the kind and sub-kind. 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 sub-kind of the attribute. The Contacts API recognizes many common kind/sub-kind 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.

Using contact filters

When you manipulate contacts in your own 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().

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().

// Create the contact service object
ContactService *service;
 
// Create the search filter and set the search value
ContactSearchFilters options;
options.setSearchValue("H");
 
// Retrieve the list of contacts that fit the filter's criteria
QList<Contact>contacts = service->searchContacts(options);

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 particularly 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: 2014-01-23

comments powered by Disqus