ContactService

Since: BlackBerry 10.0.0

#include <bb/pim/contacts/ContactService>

To link against this class, add the following line to your .pro file: LIBS += -lbbpim

The ContactService class provides CRUD (create/read/update/delete) operations on Contact objects.

Permissions:

The application must have the access_pimdomain_contacts permission to access the contacts database.

ContactService provides functions for adding, retrieving, updating, and deleting Contact objects, as well as for searching and counting Contact objects based on criteria specified using filter classes, such as ContactListFilters and ContactSearchFilters.

Each contact that's retrieved using the ContactService can come from any source, and can sometimes come from multiple sources if it's a merged contact. For example, contacts can come from the Contacts application, BlackBerry Messenger and other social networking applications, or an inserted SIM card. There are functions that you can use to filter contacts or handle contacts from their respective sources. However, the primary use case for this class is to treat all contacts the same, regardless of source.

Here's how to retrieve a list of contacts using contacts():
ContactListFilters filters;
filters.setLimit(20);
QList<Contact> contactList = ContactService().contacts(filters);
Here's how to search for a list of contacts with certain criteria using searchContacts():
ContactSearchFilters filters;
filters.setLimit(5);
filters.setSearchValue("Joe");
QList<Contact> contactList = ContactService().searchContacts(filters);
Here's how to retrieve the complete details of a single contact using contactDetails():
Contact contact = ContactService().contactDetails(5);
See also:

Contact


Overview

Public Functions Index

ContactService (QObject *parent=NULL)
virtual ~ContactService ()
QList< ContactActivity >activities (ContactId contactId) const
QList< ContactActivity >activities (ContactId contactId, Activity::Types activityFilter) const
voidaddContactToSim (const Contact &contact) const
ContactcontactDetails (ContactId contactId) const
ContactcontactDetails (AccountId accountId, ContactId contactId) const
ContactcontactFromVCard (const QString &vCardData) const
QList< Contact >contacts (const ContactListFilters &filters) const
QByteArraycontactToVCard (ContactId contactId) const
QByteArraycontactToVCard (ContactId contactId, VCardPhotoEncoding::Type photoEncoding, int sizeLimit) const
QByteArraycontactToVCard (const Contact &contact) const
QByteArraycontactToVCard (const Contact &contact, VCardPhotoEncoding::Type photoEncoding, int sizeLimit) const
intcount (const ContactListFilters &filters) const
intcount (const ContactSearchFilters &filters) const
ContactcreateContact (const Contact &contact, bool isWork) const
ContactcreateContact (const Contact &contact, bool isWork, bool isManualMergeOnly) const
boolcreateContacts (const QList< Contact > &contacts) const
voiddeleteContact (ContactId contactId) const
voiddeleteSimContact (ContactId contactId) const
intenterpriseContactCount () const
QByteArrayexportContactVCards (const QList< ContactId > &contactIds, VCardPhotoEncoding::Type photoEncoding) const
QList< ContactFavouriteAction >favouriteActions (ContactId contactId) const
ContactfilteredContact (ContactId contactId, const ContactListFilters &filters) const
intimportContactsFromSimCard () const
boolimportContactVCards (const QString &vCardsData) const
boolisRemoteSearchAvailable () const
voidmergeContacts (const QList< ContactId > &contactIds) const
QList< Contact >mergedContacts (ContactId contactId) const
QList< ContactOnlineStatus >onlineStatus (ContactId contactId) const
QList< ContactOnlineStatus >onlineStatus (AccountId accountId, ContactId contactId) const
PerimeterStatus::TypeperimeterStatus () const
QList< AccountId >remoteSearchableAccounts () const
QList< ContactNews >retrieveNews (const Contact &contact, unsigned int limit) const
intsaveContactsToSimCard () const
QList< Contact >searchContacts (const ContactSearchFilters &filters) const
QList< Contact >searchContactsAutoComplete (const ContactAutoCompleteSearchFilters &filters) const
QList< Contact >searchContactsByPhoneNumber (const ContactSearchFilters &filters) const
QList< Contact >searchRemote (const ContactRemoteSearchFilters &filters) const
voidsetFavouriteAction (ContactId id, const ContactFavouriteAction &action) const
voidsetFavouriteContact (ContactId contactId, bool favourite) const
boolsetPrimaryPhoto (ContactId contactId, int photoId) const
voidsetPrimaryPhoto (ContactId contactId, const QString &filepath) const
boolsyncContacts (bb::pim::account::AccountKey accountId) const
voidunmergeContacts (ContactId contactId, const QList< QPair< AccountId, ContactId > > &idPairs) const
ContactupdateContact (const Contact &contact) const

Signals Index

voidcontactFavourited (int contactId, bool favourited)
voidcontactNewSuggested (const QMap< QString, QVariant > data)
voidcontactsAdded (QList< int > contactIds)
voidcontactsChanged (QList< int > contactIds)
voidcontactsDataChanged (QDateTime changeTimeStamp)
voidcontactsDeleted (QList< int > contactIds)
voidcontactsReset ()
voidcontactSyncCompleted ()

Public Functions

ContactService (

Constructs a new ContactService with the provided parent.

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.

Parameters
parent

The parent of the ContactService, or NULL if no parent is provided.

Since:

BlackBerry 10.0.0

virtual~ContactService ()

Destructor.

Since:

BlackBerry 10.0.0

QList< ContactActivity > activities (
  • ContactIdcontactId)

Retrieves the activity stream that's shared between you and the provided contact.

Parameters
contactId

The contact ID of the contact to retrieve the activity stream for.

Return:

A list of activities that are shared between you and the provided contact.

Since:

BlackBerry 10.0.0

QList< ContactActivity > activities (
  • ContactIdcontactId,
  • Activity::TypesactivityFilter )

Retrieves the activity stream that's shared between you and the provided contact.

Parameters
contactId

The contact ID of the contact to retrieve the activity stream for.

activityFilter

The filter for different activity types, multiple activity types can be specified using the bitwise OR operator

Return:

A list of activities that are shared between you and the provided contact.

Since:

BlackBerry 10.1.0

void addContactToSim (

Adds the provided contact to the SIM card.

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.

Parameters
contact

The contact to add.

Since:

BlackBerry 10.0.0

Contact contactDetails (
  • ContactIdcontactId)

Retrieves the full details for the Contact with the provided ID.

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.

Parameters
contactId

The ID of the contact whose details should be retrieved.

Return:

The contact (including full details) with the provided contact ID.

Since:

BlackBerry 10.0.0

Contact contactDetails (
  • AccountIdaccountId,
  • ContactIdcontactId )

Retrieves detailed contact information for a 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.

Parameters
accountId

The account ID of the contact whose details should be retrieved.

contactId

The contact ID of the contact whose details should be retrieved.

Return:

The contact (including full details) with the provided account ID and contact ID.

Since:

BlackBerry 10.0.0

Contact contactFromVCard (

Converts a VCard stream to a contact.

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

Parameters
vCardData

The VCard stream to convert.

Return:

A contact that corresponds to the provided VCard stream.

Since:

BlackBerry 10.0.0

QList< Contact > contacts (

Retrieves a list of partial contacts based on the criteria in the provided list filter.

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);
Parameters
filters

The list filters to apply to the returned contact list.

Return:

A list of partial contacts that match the criteria in the provided list filter.

Since:

BlackBerry 10.0.0

QByteArray contactToVCard (
  • ContactIdcontactId)

Converts a contact to a VCard stream.

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.

Parameters
contactId

The contact ID of the contact to convert.

Return:

A VCard stream that corresponds to the provided contact.

Since:

BlackBerry 10.0.0

QByteArray contactToVCard (

Converts a contact to a VCard stream.

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.

Parameters
contactId

The contact ID of the contact to convert.

photoEncoding

The vcard photo encoding type

sizeLimit

The vcard size limit

Return:

A VCard stream that corresponds to the provided contact.

Since:

BlackBerry 10.0.0

QByteArray contactToVCard (

Converts a contact to a VCard stream.

If a valid contact is provided, a VCard stream (version 3.0) is created. If a parsing error occurs, an empty stream is returned. Note that if contact is a partial contact, the result VCard stream will only contain partial contact data.

Parameters
contact

The contact to convert.

Return:

A VCard stream that corresponds to the provided contact.

Since:

BlackBerry 10.2.0

QByteArray contactToVCard (

Converts a contact to a VCard stream.

If a valid contact is provided, a VCard stream (version 3.0) is created. If a parsing error occurs, an empty stream is returned. Note that if contact is a partial contact, the result VCard stream will only contain partial contact data.

Parameters
contact

The contact to convert.

photoEncoding

The vcard photo encoding type

sizeLimit

The vcard size limit

Return:

A VCard stream that corresponds to the provided contact.

Since:

BlackBerry 10.2.0

int count (

Retrieves the number of contacts that match the criteria in the provided list filter.

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);
Parameters
filters

The list filters to apply to the returned result.

Return:

The number of contacts that match the criteria in the provided list filter.

Since:

BlackBerry 10.0.0

int count (

Retrieves the number of contacts that match the criteria in the provided search filter.

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);
Parameters
filters

The search filters to apply to the returned result.

Return:

The number of contacts that match the criteria in the provided search filter.

Since:

BlackBerry 10.0.0

Contact createContact (
  • const Contact &contact,
  • boolisWork )

Creates and adds a new contact to the database.

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);
Parameters
contact

The new contact to be persisted.

isWork

If true, the contact will be stored in the enterprise perimeter. If application permissions do not allow it or there is no enterprise account integrated, the contact will be created in the personal perimeter.

Return:

The contact that was created.

Since:

BlackBerry 10.0.0

Contact createContact (
  • const Contact &contact,
  • boolisWork,
  • boolisManualMergeOnly )

Creates and adds a new contact to the database.

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);
Parameters
contact

The new contact to be persisted.

isWork

If true, the contact will be stored in the enterprise perimeter. If application permissions do not allow it or there is no enterprise account integrated, the contact will be created in the personal perimeter.

isManualMergeOnly

If true, the contact will not be merged automatically with another contact even if a matching contact is found. However, this contact can be merged by a merge request.

Return:

The contact that was created.

Since:

BlackBerry 10.0.0

bool createContacts (

Creates and adds multiple new contacts to the database in the personal perimeter.

You should use a ContactBuilder to create the new Contact objects and set their properties, and then use this function to persist the Contact objects 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 contactsChanged() signal is emitted instead of the contactsAdded() signal.

Here's how to create multiple Contact objects 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);
Parameters
contacts

The new contacts to be persisted.

Return:

true if contacts were added successfully, false otherwise.

Since:

BlackBerry 10.1.0

void deleteContact (
  • ContactIdcontactId)

Deletes a contact from the database.

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.

Parameters
contactId

The contact ID of the contact to delete.

Since:

BlackBerry 10.0.0

void deleteSimContact (
  • ContactIdcontactId)

Deletes contact data that is sourced from the SIM card.

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.

Parameters
contactId

The contact ID of the contact whose SIM card data should be removed.

Since:

BlackBerry 10.0.0

int enterpriseContactCount ()

Retrieves the number of contacts that are considered enterprise contacts.

Return:

The number of contacts that are considered enterprise contacts.

Since:

BlackBerry 10.0.0

QByteArray exportContactVCards (

Converts contacts to VCards stream.

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

Parameters
contactIds

The list of contact IDs whose contacts to convert.

photoEncoding

The vcard photo encoding type

Return:

A VCards stream that corresponds to the provided contacts.

Since:

BlackBerry 10.0.0

QList< ContactFavouriteAction > favouriteActions (
  • ContactIdcontactId)

Retrieves the list of favorite actions associated with the provided contact.

For more information about favorite actions, see ContactFavouriteAction.

Parameters
contactId

The contact ID of the contact to retrieve the list of favorite actions for.

Return:

A list of favorite actions associated with the provided contact.

Since:

BlackBerry 10.0.0

Contact filteredContact (

Retrieves a partial contact based on the provided contact ID and contact list filter.

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.

Parameters
contactId

The contact ID of the contact to retrieve.

filters

The contact list filters to apply to the returned contact.

Return:

A contact that matches the provided contact ID and criteria in the provided contact list filter.

Since:

BlackBerry 10.0.0

int importContactsFromSimCard ()

Imports contacts from the SIM card into local storage.

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

Return:

The number of contacts that were imported from the SIM card into local storage.

Since:

BlackBerry 10.0.0

bool importContactVCards (

Import VCards stream to local contacts.

This function imports VCards stream into local contacts. If a parsing error occurs on one of vcards, the vcard will not be saved to local contacts
Parameters
vCardsData

The VCards stream.

Return:

true if the importing vcards was successfully, false otherwise.

Since:

BlackBerry 10.0.0

bool isRemoteSearchAvailable ()

Indicates whether remote search is available within any of the accounts that are integrated.

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

Return:

true if remote search is available in an integrated account, false otherwise.

Since:

BlackBerry 10.0.0

void mergeContacts (
  • const QList< ContactId > &contactIds)

Merges the provided list of unified contacts.

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

Parameters
contactIds

The list of contact IDs whose contacts should be merged.

Since:

BlackBerry 10.0.0

QList< Contact > mergedContacts (
  • ContactIdcontactId)

Retrieves the individual contacts that make up the provided merged 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.

Parameters
contactId

The contact ID of the merged contact to retrieve individual contacts for.

Return:

A list of individual contacts that make up the provided merged contact.

Since:

BlackBerry 10.0.0

QList< ContactOnlineStatus > onlineStatus (
  • ContactIdcontactId)

Retrieves the online status information about the provided contact.

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.

Parameters
contactId

The contact ID of the contact to retrieve online status information for.

Return:

A list of online statuses for the provided contact.

Since:

BlackBerry 10.0.0

QList< ContactOnlineStatus > onlineStatus (
  • AccountIdaccountId,
  • ContactIdcontactId )

Retrieves the online status information about the provided contact from one of its source accounts.

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.

Parameters
account

The source account ID of the contact to retrieve online status information from.

contactId

The contact ID of the contact to retrieve online status information for.

Return:

A list of online statuses for the provided contact.

Since:

BlackBerry 10.2.0

PerimeterStatus::Type perimeterStatus ()

Retrieves the current perimeter status.

The perimeter status can be Inactive, Locked, Unlocked

Return:

The current perimeter status.

Since:

BlackBerry 10.0.0

QList< AccountId > remoteSearchableAccounts ()

Retrieves the list of account IDs for accounts that support remote search.

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

Return:

A list of account IDs for accounts that support remote search.

Since:

BlackBerry 10.0.0

QList< ContactNews > retrieveNews (
  • const Contact &contact,
  • unsigned intlimit )

Retrieves news that's related to information in the provided contact.

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.

Parameters
contact

The contact to retrieve news for.

limit

The maximum number of news items that are returned.

Return:

A list of news items that are related to the provided contact.

Since:

BlackBerry 10.0.0

int saveContactsToSimCard ()

Saves contacts to the SIM card.

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.

Return:

The number of contacts that were saved to the SIM card.

Since:

BlackBerry 10.0.0

QList< Contact > searchContacts (

Searches for and retrieves a list of contacts based on the provided search filter.

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);
Parameters
filters

The search filters to apply to the search results.

Return:

A list of partial contacts that match the criteria in the provided search filter.

Since:

BlackBerry 10.0.0

QList< Contact > searchContactsAutoComplete (

Performs a search of email, social providers, and so on, for auto-complete results in the "To|Cc|Bcc" fields.

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

Parameters
filters

The auto-complete search filters to apply to the search results.

Return:

A list of contacts that match the criteria in the provided search filter.

Since:

BlackBerry 10.0.0

QList< Contact > searchContactsByPhoneNumber (

Performs a search based on the provided phone number.

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.

Parameters
filters

The search filters to apply to the search results.

Return:

A list of contacts that match the criteria in the provided search filter.

Since:

BlackBerry 10.0.0

QList< Contact > searchRemote (

Performs a remote search based on the provided remote search filters.

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);
Parameters
filters

The remote search filters to apply to the search results.

Return:

A list of remote contacts that match the criteria in the provided remote search filter.

Since:

BlackBerry 10.0.0

void setFavouriteAction (
  • ContactIdid,
  • const ContactFavouriteAction &action )

Sets a favorite action for an attribute within the provided contact.

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

Parameters
id

The contact ID of the contact to set a favorite action for.

action

The favorite action to set.

Since:

BlackBerry 10.0.0

void setFavouriteContact (
  • ContactIdcontactId,
  • boolfavourite )

Sets whether the provided contact is a favorite.

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

Parameters
contactId

The contact ID of the contact to set as a favorite.

favourite

If true the contact is set as a favorite, if false the contact is not set as a favorite.

Since:

BlackBerry 10.0.0

bool setPrimaryPhoto (
  • ContactIdcontactId,
  • intphotoId )

Sets the primary photo of the provided contact using a photo ID.

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

Parameters
contactId

The contact ID of the contact whose primary photo should be set.

photoId

The photo ID of the photo to set as the primary photo for the contact.

Return:

true if the primary photo was set successfully, false otherwise.

Since:

BlackBerry 10.0.0

void setPrimaryPhoto (
  • ContactIdcontactId,
  • const QString &filepath )

Sets the primary photo of the provided contact using a file path.

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.

Parameters
contactId

The contact ID of the contact whose primary photo should be set.

filepath

The file path of the photo to set as the primary photo for the contact.

Since:

BlackBerry 10.0.0

bool syncContacts (
  • bb::pim::account::AccountKeyaccountId)

Initiates contact synchronization.

This function initiates contact synchronization for a selected
Parameters
accountId.

Note that most accounts do not require explicit synchronization. This API currently only supports AT&T Address Book accounts.

accountId

Id of the account to sync.

Return:

true if the synchronization was successful, false otherwise.

Since:

BlackBerry 10.2.0

void unmergeContacts (
  • ContactIdcontactId,
  • const QList< QPair< AccountId, ContactId > > &idPairs )

Unmerges the provided unified contact.

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.

Parameters
contactId

The contact ID of the contact to unmerge.

idPairs

A list of AccountId/ContactId pairs of the sub-contacts that make up the unified contact. These will result in one merged contact.

Since:

BlackBerry 10.0.0

Contact updateContact (

Update an existing contact in the database.

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);
}
Parameters
contact

The contact to be updated.

Return:

The contact that was updated.

Since:

BlackBerry 10.0.0

Signals

void contactFavourited (
  • intcontactId,
  • boolfavourited )

Emitted when a contact's favourite status changes.

Parameters
contactId

The ID of the contact who's favourite status has changed.

favourited

True if the contact is favourited, False if the contact is unfavourited.

Since:

BlackBerry 10.2.0

void contactNewSuggested (

Emitted when a suggested contact is found.

This signal is emitted when the signature block service in pimcore has found a suggested contact. The expectation is that a UI popup will present itself to ask the user if a new contact should be made, and the data will prepopulate a contact edit screen.

Since:

BlackBerry 10.x.x

void contactsAdded (

Emitted when new contacts are added.

Parameters
contactIds

The list of contact IDs that were added.

Since:

BlackBerry 10.0.0

void contactsChanged (

Emitted when one or more contacts are changed.

When contacts have been merged or changed, this signal is emitted.

Parameters
contactIds

The list of contact IDs that were changed.

Since:

BlackBerry 10.0.0

void contactsDataChanged (

void contactsDeleted (

Emitted when contacts are deleted.

When individual contacts are deleted, this signal is emitted. When an entireaccount is removed from the system, the contactsReset() signal is emitted instead, in which case any cached contacts should be dropped.

Parameters
contactIds

The list of contact IDs that were deleted.

Since:

BlackBerry 10.0.0

void contactsReset ()

Emitted when the current list of contacts has significantly changed.

This signal is emitted when something significant has happened to the contacts database. For example, a source account that has been deleted will trigger this signal. It is expected that all cached copies of the contacts list will be flushed and retrieved again when this happens.

Since:

BlackBerry 10.0.0

void contactSyncCompleted ()

Emitted when contact synchronization has been completed.

This signal is used in a scenario where lazy loading is preferred.

Since:

BlackBerry 10.0.0

Last modified: 2014-03-13

comments powered by Disqus