ContactService

You don't need to provide a parent when you construct a ContactService object. If you don't provide a parent, the default value is NULL. If you create a ContactService object and provide a parent that is not NULL, you shouldn't allocate the instance on the stack. The parent that you provide is responsible for deleting the instance.

Only contacts that are retrieved using this function contain the full data of a particular contact. Other functions in this class return partial contacts. For this reason, you should update only those contacts that you retrieve using this function (instead of contacts that you retrieve using other functions in this class). Otherwise, you risk losing data because the contact content in the data will be overwritten with partial contact content.

The contacts that are returned are based on the criteria that's specified in the provided ContactListFilters. For example, you can specify that you want to return only contacts that have a specific kind and sub-kind.

You can provide an empty ContactListFilters to retrieve the entire contact list. Each contact 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 provide better performance in this case than returning contacts with full details. It is strongly recommended to use the paging mechanism available in ContactListFilters by setting an anchor ID and result limit values. The more data that's retrieved from this list, the slower the response time. For reasonable performance, you shouldn't exceed 200 results per page.

Here's how to retrieve a list of partial contacts and process the contacts efficiently using anchors and result limits:

ContactService service;
QList<Contact> contactPage;

ContactListFilters options;
const int maxLimit = 20;
options.setLimit(maxLimit);
do
{
    contactPage = service.contacts(options);
    doStuff(contactPage);
    if (contactPage.size() == maxLimit)
    {
        options.setAnchorId(contactPage[maxLimit-1].id());
    }
    else
    {
        break;
    }
} while (true);

Similar to contacts(), this function allows pagination. The filters that you provide affect the search results that are returned. At a minimum, you should set the search value within the filters before calling this function. Note that searches where the search value is a single letter can be slow. By default, the search is performed against certain attribute types. The default attribute types are first name, last name, company name, phone, and email.

Here's how to search for contacts that include the letter H:

ContactService service;
QList<Contact> contacts;
ContactSearchFilters options;
options.setSearchValue("H");
contacts = service.searchContacts(options);

Here's how to retrieve the number of contacts that include the letter H:

ContactService service;
int count;
ContactListFilters options;
options.setIsFavourite(true);
count = service.count(options);

Here's how to retrieve the number of contacts that include the letter H:

ContactService service;
int count;
ContactSearchFilters options;
options.setSearchValue("H");
count = service.count(options);

The phone number that's provided is normalized (special characters and spaces are removed). This function is similar to searchContacts(), but is designed specifically for reverse look-up of phone numbers. This function searches only the phone number field, instead of all fields. This can be very useful for caller ID functionality.

This search is a very targeted search, and is designed to be used as a fast lookup for auto-completion of email addresses.

This function queries the system to see if there is an integrated account that has remote search capability.

This function performs a remote search on the global address list (GAL) for contacts. You should use this function in conjunction with remoteSearchableAccounts(). For each account that supports remote search, you can use searchRemote() to paginate the search results. For example, here's how to paginate search results using a start index and end index:

QList<bb::pim::contacts::Contact> contacts;
bb::pim::contacts::ContactRemoteSearchFilters options;
options.setSearchValue(value);
options.setAccount(accountId);
options.setStartIndex(startIndex);
options.setEndIndex(endIndex);
contacts = ContactService().searchRemote(options);

After you retrieve the account IDs using this function, you can use the AccountService to get specific information about the account.

You should use a ContactBuilder to create the new Contact and set its properties, and then use this function to persist the new Contact to the database. The contactsAdded() signal is emitted when contacts are added successfully using this function.

As a Contact is added or changed, the Contact might be merged automatically with an existing Contact that has the same contact ID. In this case, the Contact that's returned might have the same contact ID as an existing contact, and the contactsChanged() signal is emitted instead of the contactsAdded() signal.

Here's how to create a Contact using a ContactBuilder and persist it to the database:

using namespace bb::pim::contacts;

ContactService service;
ContactBuilder builder;
builder.addAttribute(ContactAttributeBuilder()
                     .setKind(AttributeKind::Name)
                     .setSubKind(AttributeSubKind::NameGiven)
                     .setValue("Hello");
builder.addAttribute(ContactAttributeBuilder()
                     .setKind(AttributeKind::Profile)
                     .setSubKind(AttributeSubKind::ProfileTwitter)
                     .setValue("World"));
Contact createdContact = service.createContact(builder, false);

You should use a ContactBuilder to create the new Contact and set its properties, and then use this function to persist the new Contact to the database. The contactsAdded() signal is emitted when contacts are added successfully using this function.

As a Contact is added or changed, the Contact might be merged automatically with an existing Contact that has the same contact ID. In this case, the Contact that's returned might have the same contact ID as an existing contact, and the contactsChanged() signal is emitted instead of the contactsAdded() signal.

Here's how to create a Contact using a ContactBuilder and persist it to the database:

using namespace bb::pim::contacts;

ContactService service;
ContactBuilder builder;
builder.addAttribute(ContactAttributeBuilder()
                     .setKind(AttributeKind::Name)
                     .setSubKind(AttributeSubKind::NameGiven)
                     .setValue("Hello");
builder.addAttribute(ContactAttributeBuilder()
                     .setKind(AttributeKind::Profile)
                     .setSubKind(AttributeSubKind::ProfileTwitter)
                     .setValue("World"));
Contact createdContact = service.createContact(builder, false, true);

You should use a ContactBuilder to create the new Contact and set its properties, and then use this function to persist the Contact to the database. The contactsAdded() signal is emitted when contacts are added successfully using this function.

As a Contact is added or changed, the Contact might be merged automatically with an existing Contact that has the same contact ID. In this case, the Contact that's returned might have the same contact ID as an existing contact, and the contactsChanged() signal is emitted instead of the contactsAdded() signal.

Here's how to create multiple Contact using a ContactBuilder and persist them to the database:

using namespace bb::pim::contacts;

ContactService service;
QList<Contact> contacts;
for (int i = 1; i < 100; i++) {
     ContactBuilder builder;
     builder.addAttribute(ContactAttributeBuilder()
                     .setKind(AttributeKind::Name)
                     .setSubKind(AttributeSubKind::NameGiven)
                     .setValue(QString("Hello" + QString::number(i))));
     builder.addAttribute(ContactAttributeBuilder()
                     .setKind(AttributeKind::Profile)
                     .setSubKind(AttributeSubKind::ProfileTwitter)
                     .setValue(QString("World" + QString::number(i))));
     contacts.append(builder)
}

bool result = service.createContacts(contacts);

This function is similar to createContact(), but it uses a Contact that's retrieved using contactDetails(). You can use a ContactBuilder to update the properties of the Contact, and then use this function to persist the updated information to the database. The contactsChanged() signal is emitted when contacts are updated successfully using this function.

As a Contact is added or changed, the Contact might be merged automatically with an existing Contact. In this case, the Contact that's returned from this function might not have the same contact ID as the one that was passed in to be updated, and the contactsDeleted() and contactsChanged() signals are emitted.

Here's how to update a Contact:

Contact contact = service.contactDetails(42);
if (contact.id())
{
    ContactBuilder editor = contact.edit();
    editor.addAttribute(ContactAttributeBuilder()
                         .setKind(AttributeKind::Phone)
                         .setSubKind(AttributeSubKind::Work)
                         .setValue("555-6745"));
    Contact updatedContact = ContactService().updateContact(editor);
}

This function deletes the Contact with the provided contact ID from the database. The contactsDeleted() signal is emitted when a contact is deleted successfully using this function.

Favorite contacts are displayed in the favorites grid in the Contacts application, at the top of the contact list.

For more information about favorite actions, see ContactFavouriteAction.

This function sets a favorite action to associate with a contact attribute.

If a contact is sourced from a social provider, you can use this function to retrieve its online status. For example, you can retrieve the online status of a BBM contact using this function.

This function uses the contents of the provided Contact (such as company, email, name, and so on) to form a request to fetch the relevant news for the contact.

Using the provided contact ID, this function retrieves the individual contacts that make up this contact. These contacts come from the different accounts. The contacts that are returned are designed to be read-only return values, and you shouldn't delete or update them using the ContactService.

Using the provided list of contact IDs, this function merges them into one contact. The first contact in the provided list remains, while the rest of the contacts are deleted. The appropriate signals are emitted for each contact that's affected by this function (for example, contactsChanged() for the contact that's changed, contactsDeleted() for the contacts that are deleted).

This function results in two contacts. The list of AccountId/ContactId pairs are sub-contacts of the provided unified contact and will be extracted and make up one new unified contact. What's left over will remain as part of the original unified contact.

This function is a more flexible version of contactDetails(), in which you can provide an account ID to retrieve an original contact. This function is designed to be used with mergeContacts() and unmergeContacts() to ensure that the contact about to be unmerged is the correct one.

This function persists the setting of a primary photo to the database. The photo ID must be one belonging to the contact.

This function lets you save a new contact photo to the contact, and makes it the primary photo. Another way of achieving this is to add a ContactPhoto object to the Contact and either create a new contact or update that same contact. This function is just a faster way of achieving the same result if all that is required is adding a new photo.

This function saves the list of personal unified contacts to the SIM card. It's possible that not all contacts can be stored on the SIM card, because space on the SIM card is limited.

This function imports the contacts from the SIM card to the local contacts database. This function doesn't check for duplicate contacts.

Using the provided contact ID, this function deletes the data of that contact that was sourced from the SIM card. If the entire contact is composed of SIM card data, then the entire contact is deleted. If the contact only includes some data that was sourced from the SIM card, only the SIM card data is removed.

This contact is merged automatically with the existing contacts, if possible. Otherwise, it will appear as a new contact in the contacts list.

It's possible that there's no SIM card inserted in the device, or that the SIM card is full, so this function may or may not succeed. To determine if the function is successful, you can check the signals that are emitted: contactsAdded() if a contact was added, or contactsUpdated() if a contact was merged.

The perimeter status can be Inactive, Locked, Unlocked

If a Contact is found that matches the provided contact ID and contact list filters, that Contact is returned. If no such Contact is found, an empty Contact with an ID of 0 is returned.

If a valid contact ID is provided, a VCard stream (version 3.0) is created. If a parsing error occurs, an empty stream is returned.

If a valid contact ID is provided, a VCard stream (version 3.0) is created. If a parsing error occurs, an empty stream is returned.

This function converts a VCard stream into a Contact. If a parsing error occurs, the returned Contact is empty (you can verify this by using Contact::isValid()). To save the contact to the database, you can use createContact().

If valid contact ID list is provided, VCards stream (version 3.0) is created. If parsing error occurs, an empty stream is returned.