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
booladdContactsToGroup (QList< ContactId > contactIds, GroupId groupId) const
booladdContactsToGroup (QList< GroupMembershipSpecifier > membershipSpecifier, GroupId groupId) const
booladdContactToGroup (ContactId contactId, GroupId groupId) const
booladdContactToGroup (GroupMembershipSpecifier membershipSpecifier, GroupId groupId) const
voidaddContactToSim (const Contact &contact) const
ContactcontactDetails (ContactId contactId) const
ContactcontactDetails (AccountId accountId, ContactId contactId) const
ContactcontactFromVCard (const QString &vCardData) const
ContactGroupcontactGroup (GroupId groupId) const
intcontactGroupSize (GroupId groupId) const
QList< Contact >contacts (const ContactListFilters &filters) const
QList< ContactId >contactsInGroup (GroupId groupId) 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
voidcopyTo (ContactId contactId, QList< AccountId > &accountIds) 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
ContactcreateContact (const Contact &contact, bool isWork, bool isManualMergeOnly, QList< AccountId > &AccountId) const
ContactGroupcreateContactGroup (const ContactGroup &group) const
boolcreateContacts (const QList< Contact > &contacts) const
voiddeleteContact (ContactId contactId) const
voiddeleteContact (ContactId contactId, AccountId accountId) const
voiddeleteContactGroup (GroupId groupId) const
voiddeleteContacts (QList< ContactId > &contactIds) 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
QList< bb::pim::contacts::ContactFolder >folders (AccountId accountId) const
QList< ContactAttribute >groupAttributes (GroupId groupId) const
intgroupCount () const
QList< GroupMembershipSpecifier >groupMembershipDetails (GroupId groupId)
GroupMembershipSpecifiergroupMembershipDetails (GroupId groupId, ContactId contactId)
QList< ContactGroup >groups () const
QList< ContactGroup >groupsForContact (ContactId contactId) const
intimportContactsFromSimCard () const
boolimportContactVCards (const QString &vCardsData) const
boolisRemoteSearchAvailable () const
boolisRemoteSearchAvailable (AccountId account) 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
boolremoveContactFromGroup (ContactId contactId, GroupId groupId) 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
boolsetContactFolderSyncConfig (AccountId accountId, const QList< QPair< bb::pim::contacts::ContactFolderKey, bool > > &syncConfigPairs)
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
ContactGroupupdateContactGroup (const ContactGroup &updatedGroup, const QList< ContactId > removeContacts, const QList< ContactId > addContacts, const QList< GroupMembershipSpecifier > updateMemberships) const
boolupdateGroupMembership (QList< GroupMembershipSpecifier > groupMemberships, GroupId groupId) const

Signals Index

voidcontactFavourited (int contactId, bool favourited)
voidcontactGroupAdded (int groupId)
voidcontactGroupChanged (const bb::pim::contacts::ContactGroup &updatedGroup, QList< int > contactsAdded, QList< int > contactsUpdated, QList< int > contactsRemoved)
voidcontactGroupDeleted (int groupId)
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.

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

bool addContactsToGroup (
  • QList< ContactId >contactIds,
  • GroupIdgroupId )

Add contacts to a group.

Parameters
contactIds

The IDs of the contacts to add to the group.

groupId

The ID of the group to which the contacts are to be added.

Return:

True if the addition is successful, false otherwise.

Since:

BlackBerry 10.3.0

bool addContactsToGroup (

Add contacts to a group using a GroupMembershipSpecifier.

Parameters
membershipSpecifier

The GroupMembershipSpecifier that specifies the attributes to be used with this group.

groupId

The ID of the group to which the contacts are to be added.

Return:

True if the addition is successful, false otherwise.

Since:

BlackBerry 10.3.0

bool addContactToGroup (
  • ContactIdcontactId,
  • GroupIdgroupId )

Add a contact to a group.

Parameters
contactId

The ID of the contact to add to the group.

groupId

The ID of the group to which the contact is to be added.

Return:

True if the addition is successful.

Since:

BlackBerry 10.3.0

bool addContactToGroup (

Add a contact to a group using a GroupMembershipSpecifier.

Parameters
membershipSpecifier

The GroupMembershipSpecifier that specifies the attributes to be used with this group.

groupId

The ID of the group to which the contact is to be added.

Return:

True if the addition is successful, false otherwise.

Since:

BlackBerry 10.3.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

ContactGroup contactGroup (
  • GroupIdgroupId)

Retrieve a contact group.

Parameters
groupId

The ID of the group.

Return:

The contact group.

Since:

BlackBerry 10.3.0

int contactGroupSize (
  • GroupIdgroupId)

Retrieve the size of a contact group.

Parameters
groupId

The ID of the group.

Return:

The number of members in the contact group.

Since:

BlackBerry 10.3.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

QList< ContactId > contactsInGroup (
  • GroupIdgroupId)

Retrieve the IDs of contacts that are members of the specified group.

Parameters
groupId

The group's ID.

Return:

The IDs of the contacts that are members of the group.

Since:

BlackBerry 10.3.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 resultant vCard stream only contains 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 resultant vCard stream only contains 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

void copyTo (
  • ContactIdcontactId,
  • QList< AccountId > &accountIds )

Copies a contact to another account.

This function copies a contact to a specified account or accounts.

Parameters
contactId

The contact ID of the contact to copy.

accountIds

A list of accounts to copy the contact to.

Since:

BlackBerry 10.3.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

Contact createContact (
  • const Contact &contact,
  • boolisWork,
  • boolisManualMergeOnly,
  • QList< AccountId > &AccountId )

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, accountId);
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.

AccountId

A list of accountIds that the contact will be created in.

Return:

The contact that was created.

Since:

BlackBerry 10.3.0

ContactGroup createContactGroup (

Creates a new contact group.

You should use a ContactGroupBuilder to create the new ContactGroup

Parameters
group

The new group to be created.

Return:

The contact group that was created.

Since:

BlackBerry 10.3.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 deleteContact (
  • ContactIdcontactId,
  • AccountIdaccountId )

Deletes a contact from the database.

This function deletes the Contact with the provided contact ID and account 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.

accountId

The account ID of the contact to delete.

Since:

BlackBerry 10.3.0

void deleteContactGroup (
  • GroupIdgroupId)

Delete a contact group.

Parameters
groupId

The ID of the group to delete.

Since:

BlackBerry 10.3.0

void deleteContacts (
  • QList< ContactId > &contactIds)

Deletes a list of contacts from the database.

This function deletes contacts with the provided contact IDs from the database.

Parameters
contactIds

The list of contact IDs to delete.

Since:

BlackBerry 10.3.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 a vCards stream.

If a valid list of contact IDs is provided, a 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.1.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

QList< bb::pim::contacts::ContactFolder > folders (
  • AccountIdaccountId)

Retrieves a list of contact folders in the provided account.

Parameters
accountId

The account ID to retrieve the contact folders from.

Return:

A QList of contact folders in the provided account.

Since:

BlackBerry 10.3.1

QList< ContactAttribute > groupAttributes (
  • GroupIdgroupId)

Retrieve the attributes used to communicate with a group.

Attributes are associated with a group using GroupMembershipSpecifier. This specifies the ContactAttribute to use for each group member when communicating with a group.

Parameters
groupId

The group's ID.

Since:

BlackBerry 10.3.0

int groupCount ()

Retrieve the number of all contact groups.

Return:

The number of all contact groups.

Since:

BlackBerry 10.3.0

QList< GroupMembershipSpecifier > groupMembershipDetails (
  • GroupIdgroupId)

Retrieve membership details for all contacts in the group.

See also:

GroupMembershipSpecifier

Parameters
groupId

The group's ID.

Return:

A list of all membership details for all contacts in the group.

Since:

BlackBerry 10.3.0

GroupMembershipSpecifier groupMembershipDetails (
  • GroupIdgroupId,
  • ContactIdcontactId )

return membership details for a contact in a group.

See also:

GroupMembershipSpecifier

Parameters
groupId

the group's id.

Return:

contactId the contact's id.

Since:

BlackBerry 10.3.0

QList< ContactGroup > groups ()

Retrieve all contact groups.

Return:

All contact groups.

Since:

BlackBerry 10.3.0

QList< ContactGroup > groupsForContact (
  • ContactIdcontactId)

Retrieve groups in which a contact is a member.

Parameters
contactId

The contact's ID.

Return:

The groups for which a contact is a member

Since:

BlackBerry 10.3.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 a vCards stream to local contacts.

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

The vCards stream.

Return:

True if the vCards were imported successfully, false otherwise.

Since:

BlackBerry 10.1.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

bool isRemoteSearchAvailable (
  • AccountIdaccount)

Indicates whether remote search is available for the specified account.

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

Parameters
account

The account to check if remote search is currently available.

Return:

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

Since:

BlackBerry 10.3.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

bool removeContactFromGroup (
  • ContactIdcontactId,
  • GroupIdgroupId )

Remove a contact from a group.

Parameters
contactId

The ID of the contact to remove from the group.

groupId

The ID of the group from which the contact is to be removed.

Return:

True if the removal is successful, , false otherwise

Since:

BlackBerry 10.3.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

bool setContactFolderSyncConfig (
  • AccountIdaccountId,
  • const QList< QPair< bb::pim::contacts::ContactFolderKey, bool > > &syncConfigPairs )

Enables synchronization for a set of contact folders.

Parameters
accountId

The account ID of an account (for example, the account ID of an existing email account).

syncConfigPairs

A list of ContactFolderKey/bool pairs containing the contact folder ID and a boolean value representing whether sync is to be turned on or off for that folder.

Return:

true if synchronization configuration was set successfully, false otherwise.

Since:

BlackBerry 10.3.1

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 accountId. Note that most accounts do not require explicit synchronization. This API currently only supports AT&T Address Book accounts.

Parameters
accountId

The 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

ContactGroup updateContactGroup (

Update a contact group and its membership.

This function is used to update a contact group, add contacts to the group, remove contacts from the group, and update membership attributes for contacts in the group.

Parameters
updatedGroup

The group to be updated.

removeContacts

The IDs of the contacts to remove from the group.

addContacts

The IDs of the contacts to add to the group.

updateMemberships

The updated GroupMembershipSpecifier objects that define the attributes to use for each contact in the group.

Return:

The updated contact group.

Since:

BlackBerry 10.3.0

bool updateGroupMembership (

Update group membership for contacts in the group.

Parameters
groupMemberships

The updated memberships for contacts in the group.

groupId

the ID of the group to update.

Return:

True if the update is successful, false otherwise.

Since:

BlackBerry 10.3.0

Signals

void contactFavourited (
  • intcontactId,
  • boolfavourited )

Emitted when a contact's favorite status changes.

Parameters
contactId

The ID of the contact whose favorite status changed.

favourited

true if the contact is favorited, false if the contact is unfavorited.

Since:

BlackBerry 10.2.0

void contactGroupAdded (
  • intgroupId)

Emitted when a contact group is added.

Parameters
groupId

The new contact group's ID.

Since:

BlackBerry 10.3.0

void contactGroupChanged (

Emitted when a contact group is changed.

Parameters
updatedGroup

The updated contact group.

contactsAdded

The IDs of each Contact added to the group.

contactsUpdated

The IDs of each Contact updated in the group.

contactsRemoved

The IDs of each Contact removed from the group.

Since:

BlackBerry 10.3.0

void contactGroupDeleted (
  • intgroupId)

Emitted when a contact group is deleted.

Parameters
groupId

The ID of the deleted contact group.

Since:

BlackBerry 10.3.0

void contactNewSuggested (

Emitted when a suggested contact is found.

This signal is emitted when a suggested contact is found based on previous patterns. It is recommended to present a dialog to the user to ask whether a new contact should be made and to use the data to populate a contact edit screen.

Parameters
data

The attributes of the contact.

Since:

BlackBerry 10.2.0

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 (

Emitted when the data for one or more contacts has changed.

This signal is emitted when the data for one or more contacts has changed.

Parameters
changeTimeStamp

The date and time when the contact or contacts changed specified in UTC.

Since:

BlackBerry 10.2.0

void contactsDeleted (

Emitted when contacts are deleted.

When individual contacts are deleted, this signal is emitted. When an entire account 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-09-30



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

comments powered by Disqus