Contact

Since: BlackBerry 10.0.0

#include <bb/pim/contacts/Contact>

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

The Contact class represents contact data, such as name, email address, and postal address.

This class represents data that's commonly associated with a contact in a contacts application. Its data is mostly derived from its attributes, postal addresses, and photos. The data can be populated and retrieved from existing contacts by using the ContactService class.

To add new contacts, a ContactBuilder can be used to populate the contents of a Contact, and then the Contact can be persisted to the database by calling ContactService::createContact().


Overview

Public Functions Index

Contact ()
Contact (const Contact &contact)
~Contact ()
AccountIdaccountId () const
ContactActivityListactivities () const
QList< ContactAttribute >attributes () const
QStringdisplayCompanyName () const
QStringdisplayName () const
QStringdisplayName (NameOrder::Type order) const
ContactBuilderedit ()
QList< ContactAttribute >emails () const
QList< ContactAttribute >filteredAttributes (AttributeKind::Type kind) const
QList< QList< ContactAttribute > >filteredAttributesByGroupKey (AttributeKind::Type kind) const
QStringfirstName () const
ContactIdid () const
boolisFavourite () const
boolisPartialContact () const
boolisReadOnly () const
boolisShadowContact () const
boolisValid () const
QDateTimelastModified () const
QStringlastName () const
QList< ContactNews >news (int count) const
QList< ContactOnlineStatus >onlineStatus () const
Contact &operator= (const Contact &contact)
QList< ContactAttribute >phoneNumbers () const
QList< ContactPhoto >photos () const
QList< QPair< QString, AttributeSubKind::Type > >possibleSubKinds (AttributeKind::Type kind, int &selectedIndex) const
QList< ContactPostalAddress >postalAddresses () const
ContactPhotoprimaryPhoto () const
QStringsmallPhotoFilepath () const
QStringsortCompanyName () const
QStringsortFirstName () const
QStringsortLastName () const
intsourceAccountCount () const
QList< AccountId >sourceAccountIds () const
ContactType::Typetype () const

Public Functions

Contact ()

Constructs an empty Contact.

Since:

BlackBerry 10.0.0

Contact (

Copy constructor.

This function constructs a Contact containing exactly the same values as the provided Contact.

Parameters
contact

The Contact to be copied.

Since:

BlackBerry 10.0.0

~Contact ()

Destructor.

Since:

BlackBerry 10.0.0

AccountId accountId ()

Retrieves the account ID of this Contact.

The account ID determines which account this Contact belongs to.

Return:

The account ID of this Contact.

Since:

BlackBerry 10.0.0

ContactActivityList activities ()

Retrieves the activity stream that's shared between you and this Contact.

An activity is an event that involves a contact. For example, an activity could be receiving an email or phone call from a contact.

Return:

A list of activities that are shared between you and this Contact.

Since:

BlackBerry 10.0.0

QList< ContactAttribute > attributes ()

Retrieves the list of attributes for this Contact.

Attributes represent the properties of a Contact, such as name, email address, postal address, and so on. This function retrieves the list of the attributes that this Contact has values for.

Return:

The list of attributes for this Contact.

Since:

BlackBerry 10.0.0

QString displayCompanyName ()

Retrieves the company name of this Contact.

You might choose to display the company name along with the contact name in a list view in your application. This value will be populated only when a contact is retrieved using the ContactService.

Return:

The company name of this Contact.

Since:

BlackBerry 10.0.0

QString displayName ()

Retrieves the display name of this Contact.

The display name is simply the last name of the Contact appended to the first name. This value will be populated only when the Contact is retrieved using the ContactService.

Return:

The display name of this Contact.

See also:

ContactService

Since:

BlackBerry 10.0.0

QString displayName (

Retrieves the display name of this Contact.

The display name is the last name of the Contact appended to the first name. This value will be populated only when the Contact is retrieved using the ContactService.

Parameters
order

The order of the display name.

Return:

The display name of this Contact.

See also:

ContactService

Since:

BlackBerry 10.3.0

ContactBuilder edit ()

Edits the contents of this Contact.

This function returns a ContactBuilder that you can use to change the values of this Contact.

Return:

A ContactBuilder that you can use to change the values of this Contact.

Since:

BlackBerry 10.0.0

QList< ContactAttribute > emails ()

Retrieves a list of attributes of this Contact that represent email addresses.

This function retrieves all contact attributes for this Contact where the attribute kind is AttributeKind::Email. This is a convenience function, and is equivalent to calling filteredAttributes(AttributeKind::Email).

Return:

A list of contact attributes that represent email addresses.

See also:

ContactAttributeKind, filteredAttributes()

Since:

BlackBerry 10.0.0

QList< ContactAttribute > filteredAttributes (

Retrieves the list of attributes for this Contact that are of the provided attribute kind.

This function returns only the attributes of this Contact that are of the provided kind, represented by a value from the AttributeKind::Type enumeration. For example, here's how to retrieve a list of attributes that have a kind of AttributeKind::Phone:

Contact contact = ContactService().contactDetails(5);
QList<ContactAttribute> phoneAttributes = contact.filteredAttributes(AttributeKind::Phone);
Parameters
kind

The kind of attribute to retrieve.

Return:

A list of attributes for this Contact that are of the provided kind.

Since:

BlackBerry 10.0.0

QList< QList< ContactAttribute > > filteredAttributesByGroupKey (

Groups the attributes for this Contact according to the provided attribute kind.

This function returns a list of lists based on the provided attribute kind. The items in the inner list are values for each of the sub-kinds of the provided attribute kind.

For example, if you provide AttributeKind::Phone as the argument to this function, there are several sub-kinds associated with this kind, such as AttributeSubKind::Work, AttributeSubKind::PhoneMobile, AttributeSubKind::Home, and so on. If there are multiple values for each of these sub-kinds (that is, more than one work phone number, mobile phone number, or home phone number that's associated with this contact) then each inner list that's returned includes the values for one of the sub-kinds.

Parameters
kind

The kind of attribute to group by.

Return:

A list of lists that represent groupings of attributes for this Contact.

Since:

BlackBerry 10.0.0

QString firstName ()

Retrieves the first name of this Contact.

This is a convenience function, and lets you retrieve the first name of this contact directly. To accomplish this another way, you can retrieve the list of attributes for the contact using attributes(), and then search for an attribute that has a kind of AttributeKind::Name and a sub-kind of AttributeSubKind::NameGiven.

This function is available only for fully populated contacts, or contacts from list queries and search queries where AttributeKind::Name is part of the options. For example, here's how to retrieve a list of contacts on which you can call this function to retrieve the contacts' first names:

ContactListOptions filters;
filters.setLimit(20);
filters.hasAttribute(AttributeKind::Name);
QList<Contact> contactList = ContactService().contacts(filters);
Return:

The first name of this Contact.

Since:

BlackBerry 10.0.0

ContactId id ()

Retrieves the ID of this Contact.

You can use this value to interact with this Contact and perform different operations using the ContactService, such as retrieving the contact details, contact list anchor, or contact search anchor, and other operations. The ID is assigned automatically when the contact is added to the database using the ContactService, and you can't change the ID after it's been assigned.

Return:

The ID of this Contact.

Since:

BlackBerry 10.0.0

bool isFavourite ()

Indicates whether this Contact is a favorite.

If this Contact is a favorite, this function returns true. Favorite contacts are displayed in the favorites grid in the Contacts application.

Return:

true if this Contact is a favorite, false otherwise.

Since:

BlackBerry 10.0.0

bool isPartialContact ()

Indicates whether this Contact is a partial contact.

For performance reasons, Contact objects that are returned from ContactService may sometimes be partial contacts, and won't contain all of the information for the contact. Contact objects that you retrieve by calling ContactService::contactDetails() will be full contacts, and Contact objects that you retrieve using other functions in ContactService will be partial contacts.

Return:

true if this Contact is a partial contact, false otherwise.

Since:

BlackBerry 10.0.0

bool isReadOnly ()

Indicates whether this Contact is a read-only contact.

You can't change the attributes of a read-only contact.

Return:

true if this Contact is read-only, false otherwise.

Since:

BlackBerry 10.0.0

bool isShadowContact ()

Indicates whether this Contact is a shadow contact.

You can't unlink a shadow contact.

Return:

true if this Contact is a shadow contact, false otherwise.

Since:

BlackBerry 10.2.0

bool isValid ()

Indicates whether this Contact is valid.

Contacts without attributes, postal addresses, or photos are considered invalid. You should use this function to determine if a Contact is valid before you use it.

Return:

true if this Contact is valid, false otherwise.

Since:

BlackBerry 10.0.0

QDateTime lastModified ()

Retrieves the date when this Contact was last updated.

Return:

The date when this Contact was last updated.

Since:

BlackBerry 10.2.0

QString lastName ()

Retrieves the last name of this Contact.

This is a convenience function, and lets you retrieve the last name of this contact directly. To accomplish this another way, you can retrieve the list of attributes for the contact using attributes(), and then search for an attribute that has a kind of AttributeKind::Name and a sub-kind of AttributeSubKind::NameSurname.

This function is available only for fully populated contacts, or contacts from list queries and search queries where AttributeKind::Name is part of the options. For example, here's how to retrieve a list of contacts on which you can call this function to retrieve the contacts' last names:

ContactListOptions filters;
filters.setLimit(20);
filters.hasAttribute(AttributeKind::Name);
QList<Contact> contactList = ContactService().contacts(filters);
Return:

The last name of this Contact.

Since:

BlackBerry 10.0.0

QList< ContactNews > news (
  • intcount)

Retrieves the current company news for this Contact.

This function retrieves the current company news for a particular contact. The content of the news will be relevant to the contact from its attributes.

Parameters
count

Return:

A list of news articles for this Contact.

Since:

BlackBerry 10.0.0

QList< ContactOnlineStatus > onlineStatus ()

Retrieves a list of contact statuses for this Contact.

This function retrieves the online status of a contact. Each status will be from a different source. For example, if the contact is retrieved from a social networking application, such as BlackBerry Messenger, you can use this function to determine if the contact is online.

Return:

A list of contact statuses for this Contact.

Since:

BlackBerry 10.0.0

Contact & operator= (

Assignment operator.

This operator copies all values from the provided Contact into this Contact.

Parameters
contact

The Contact from which to copy all values.

Return:

A Contact with all copied data

Since:

BlackBerry 10.0.0

QList< ContactAttribute > phoneNumbers ()

Retrieves a list of attributes of this Contact that represent phone numbers.

This function retrieves all contact attributes for this Contact where the attribute kind is AttributeKind::Phone. This is a convenience function, and is equivalent to calling filteredAttributes(AttributeKind::Phone).

Return:

A list of contact attributes that represent phone numbers.

See also:

ContactAttributeKind, filteredAttributes()

Since:

BlackBerry 10.0.0

QList< ContactPhoto > photos ()

Retrieves a list of photos that are associated with this Contact.

These photos are populated only when the full contact details are retrieved from the ContactService using ContactService::contactDetails(). When you call ContactService::contacts() or ContactService::searchContacts, only the primary photo is retrieved.

Return:

A list of photos that are associated with this Contact.

Since:

BlackBerry 10.0.0

QList< QPair< QString, AttributeSubKind::Type > > possibleSubKinds (

Retrieves the possible alternate labels and sub-kinds of the provided attribute kind.

This function returns a list of label/sub-kind pairs that can be used for this Contact, based on the provided kind, that are different than any existing sub-kinds. For example, consider a contact that has a work phone number, specified by the AttributeKind::Phone kind and AttributeSubKind::Work sub-kind. If you provide AttributeKind::Phone as the kind argument, this function will return other possible sub-kinds and their associated labels, such as AttributeSubKind::Work with a label of "Work 2" (because there's already a work phone number for the contact), AttributeSubKind::Home with a label of "Home", and so on.

Parameters
kind

The attribute kind to retrieve the sub-kinds of.

selectedIndex

The index to select.

Return:

A list of pairs that represent possible alternate labels and sub-kinds for this Contact.

Since:

BlackBerry 10.0.0

QList< ContactPostalAddress > postalAddresses ()

Retrieves a list of postal addresses that are associated with this Contact.

Return:

A list of postal addresses that are associated with this Contact.

Since:

BlackBerry 10.0.0

ContactPhoto primaryPhoto ()

Retrieves the primary photo that is associated with this Contact.

Return:

The primary photo that is associated with this Contact.

Since:

BlackBerry 10.0.0

QString smallPhotoFilepath ()

Retrieves the file path of a small photo for this Contact.

You might use a small photo as a thumbnail image for the Contact when displaying a list of contacts in your application. An example of this value is "/accounts/1000/pimdata/contacts/1345571651/img-example-small.jpg". This value will be populated only when a contact is retrieved using the ContactService.

Return:

The file path of a small photo for this Contact.

Since:

BlackBerry 10.0.0

QString sortCompanyName ()

Retrieves the value that's used for sorting by company name.

The contacts database maintains company name data for sorting purposes. This data might not be the same as the actual company name for the contact. For example, if the contact has only a last name, then the last name is included in the company name sorting data as well. By using this data for sorting purposes, contacts without a company name can be sorted properly when sorting by both last name and company name.

Return:

The value that's used for sorting by company name.

Since:

BlackBerry 10.0.0

QString sortFirstName ()

Retrieves the value that's used for sorting by first name.

The contacts database maintains first name data for sorting purposes. This data might not be the same as the actual first name for the contact. For example, if the contact has only a last name, then the last name is included in the first name sorting data as well. By using this data for sorting purposes, contacts without a first name can be sorted properly when sorting by both first name and last name.

Return:

The value that's used for sorting by first name.

Since:

BlackBerry 10.0.0

QString sortLastName ()

Retrieves the value that's used for sorting by last name.

The contacts database maintains last name data for sorting purposes. This data might not be the same as the actual last name for the contact. For example, if the contact has only a first name, then the first name is included in the last name sorting data as well. By using this data for sorting purposes, contacts without a last name can be sorted properly when sorting by both first name and last name.

Return:

The value that's used for sorting by last name.

Since:

BlackBerry 10.0.0

int sourceAccountCount ()

Retrieves the number of account sources for this Contact.

Contacts can be merged from multiple accounts to form a single contact. For example, contacts might be merged from a personal account and a work account. If the same contact exists in both accounts, the contact information is merged into a single contact that includes all of the information from both accounts. For this merged contact, this function would return 2, because the contact information is sourced from 2 accounts.

Return:

The number of account sources for this Contact.

Since:

BlackBerry 10.0.0

QList< AccountId > sourceAccountIds ()

Retrieves a list of the account IDs of the sources for this Contact.

Contacts can be merged from multiple accounts to form a single contact. For example, contacts might be merged from a personal account and a work account. If the same contact exists in both accounts, the contact information is merged into a single contact that includes all of the information from both accounts. This function returns all of the account IDs that are sources for this contact.

Return:

A list of the account IDs of the sources for this Contact.

Since:

BlackBerry 10.0.0

ContactType::Type type ()

Retrieves the type of Contact.

Contact objects returned by the ContactService can be of multiple types. For example, a Contact can be a ContactGroup.

Return:

The ContactType.

Since:

BlackBerry 10.3.0

Last modified: 2014-06-24



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

comments powered by Disqus