QContact Class

Member Function Documentation

QContact::QContact()

Construct an empty contact.

The contact will have an empty id, and have type QContactType::TypeContact. The isEmpty() function will return true.

QContact::QContact(const QContact & other)

Initializes this QContact from other

QContact::~QContact()

Frees the memory used by this QContact

void QContact::addTag(const QString & tag)

Adds the tag to this contact.

See also QContactTag.

bool QContact::appendDetail(const QContactDetail & detail)

Appends the given detail to the list of stored details. This is a convenience method intended to be used e.g. by backend developers to populate an empty QContact object when fetching data from the backend. If detail is a QContactType, the existing contact type will be overwritten with detail. There is never more than one contact type in a contact.

Note that if another detail of the same type and id has been previously saved in this contact, that detail is duplicated. For this reason, this method should not be used to update an existing contact object with a newer version of an existing detail. For this use case, the clients must use the saveDetail() method.

See also saveDetail().

QList<QContactActionDescriptor> QContact::availableActions(const QString & serviceName = QString()) const

Return a list of descriptors for the actions available to be performed on this contact.

The actions considered can be restricted by the optional parameters The actions can be restricted to those provided by a specific service with the serviceName parameter. If serviceName is empty, actions provided by any service will be returned if the contact meets the required criteria (contains details of the correct type, etc).

Each action that matches the above criteria will be tested to see if this contact is supported by the action, and a list of the action descriptors that are supported will be returned.

void QContact::clearDetails()

Removes all details of the contact. This function does not modify the id or type of the contact. Calling isEmpty() after calling this function will return true.

void QContact::clearTags()

Removes all tags associated with the contact.

See also QContactTag.

QContactDetail QContact::detail(QContactDetail::DetailType type) const

Returns the first detail stored in the contact which with the given type. The type argument is typically the detail type constant provided by a specific subclass of QContactDetail. For example:

 QContactDetail detail = contact.detail(QContactName::Type);

It would usually be more convenient to use the template version of this function, in the following manner:

 QContactName name = contact.detail<QContactName>();

T QContact::detail() const

Returns the first detail of the template parameter type, as returned by the template details() function. The type must be a subclass of QContactDetail.

QList<QContactDetail> QContact::details(QContactDetail::DetailType type = QContactDetail::TypeUndefined) const

Returns a list of details of the given type.

The type argument is typically the detail type constant provided by a specific subclass of QContactDetail. For example:

 QList<QContactDetail> details = contact.details(QContactPhoneNumber::Type);

It would usually be more convenient to use the template version of this function, in the following manner:

 QList<QContactPhoneNumber> phoneNumbers = contact.details<QContactPhoneNumber>();

QList<T> QContact::details() const

Returns a list of details of the template parameter type. The type must be a subclass of QContactDetail.

For example:

 QList<QContactPhoneNumber> phoneNumbers = contact.details<QContactPhoneNumber>();

QContactId QContact::id() const

Returns the QContactId that identifies this contact.

This may have been set when the contact was retrieved from a particular manager, or when the contact was first saved in a manager. The QContactId is only valid with a specific manager. See QContactManager::saveContact() for more information.

See also setId().

bool QContact::isEmpty() const

Returns true if this QContact is empty, false if not.

An empty QContact has no extra details. The type of the contact is irrelevant.

bool QContact::isPreferredDetail(const QString & actionName, const QContactDetail & detail) const

Returns true if the given detail is a preferred detail for the given actionName, or for any action if the actionName is empty.

See also preferredDetail().

QContactDetail QContact::preferredDetail(const QString & actionName) const

Returns the preferred detail for a given actionName.

If the actionName is empty, or there is no preference recorded for the supplied actionName, returns an empty QContactDetail.

See also setPreferredDetail() and preferredDetails().

QMap<QString, QContactDetail> QContact::preferredDetails() const

Returns the recorded detail preferences for action names.

Each entry in the map has the action name as the key, and the corresponding preferred detail as the value.

QList<QContact> QContact::relatedContacts(const QString & relationshipType = QString(), QContactRelationship::Role role = QContactRelationship::Either) const

Returns a list of the ids of contacts which have a relationship of the given relationshipType with this contact. The role parameter describes the role that the related contacts have in the relationship.

If relationshipType is empty, relationships of all types will be considered.

Note: This function only examines the relationships that were present when this contact was retrieved from a manager. You can also query the manager directly, if you require the most up to date information.

 // Who are the members of a group contact?
 QList<QContactId> groupMembers = groupContact.relatedContacts(QContactRelationship::HasMember, QContactRelationship::Second);
 // What groups is this contact in?
 QList<QContactId> contactGroups = contact.relatedContacts(QContactRelationship::HasMember, QContactRelationship::First);
 // An alternative to QContact::relationships()
 QList<QContactId> spouses = contact.relatedContacts(QContactRelationship::HasSpouse, QContactRelationship::Either);
 if (spouses.count() > 1) {
     // Custom relationship type
     QList<QContactId> therapists = contact.relatedContacts("HasTherapist", QContactRelationship::Second);
 }

See also QContactRelationshipFetchRequest and QContactManager::relationships().

QList<QContactRelationship> QContact::relationships(const QString & relationshipType = QString()) const

Returns a list of relationships of the given relationshipType in which this contact is a participant.

If relationshipType is empty, all relationships will be returned.

Note: This function only examines the relationships that were present when this contact was retrieved from a manager. You can also query the manager directly, if you require the most up to date information.

 QList<QContactRelationship> spouseRelationships = contact.relationships(QContactRelationship::HasSpouse);
 // For each relationship in spouseRelationships, contact.id() will either be first() or second()

See also QContactRelationshipFetchRequest and QContactManager::relationships().

bool QContact::removeDetail(QContactDetail * detail)

Removes the detail from the contact.

The detail in the contact which has the same key as that of the given detail will be removed if it exists. Only the key is used for comparison - that is, the information in the detail may be different.

Any action preferences for the matching detail is also removed.

Be aware that if a contact is retrieved (or reloaded) from the backend, the keys of any details it contains may have been changed by the backend, or other threads may have modified the contact details in the backend. Therefore, clients should reload the detail that they wish to remove from a contact after retrieving the contact, in order to ensure that the remove operation is successful.

If the detail's access constraint includes QContactDetail::Irremovable, this function will return false.

Returns true if the detail was removed successfully, false if an error occurred.

Note that the caller retains ownership of the detail.

bool QContact::saveDetail(QContactDetail * detail)

Saves the given detail in the list of stored details, and sets the detail's id. If another detail of the same type and id has been previously saved in this contact, that detail is overwritten. Otherwise, a new id is generated and set in the detail, and the detail is added to the contact.

If the detail's access constraint includes QContactDetail::ReadOnly, this function will return true and save the detail in the contact, however attempting to save the contact in a manager may fail (if that manager decides that the read only detail should not be updated). Details with the QContactDetail::ReadOnly constraint set are typically provided in a contact by the manager, and are usually information that is either synthesized, or not intended to be changed by the user (e.g. presence information for other contacts).

If detail is a QContactType, the existing contact type will be overwritten with detail. There is never more than one contact type in a contact.

Be aware that if a contact is retrieved (or reloaded) from the backend, the keys of any details it contains may have been changed by the backend, or other threads may have modified the contact details in the backend. Therefore, clients should reload the detail that they wish to save in a contact after retrieving the contact, in order to avoid creating unwanted duplicated details.

Returns true if the detail was saved successfully, otherwise returns false.

Note that the caller retains ownership of the detail.

void QContact::setId(const QContactId & id)

Sets the id of this contact to id.

Note that this only affects this object, not any corresponding structures stored by a QContactManager.

If you change the id of a contact and save the contact in a manager, the previously existing contact will still exist. You can do this to create copies (possibly modified) of an existing contact, or to save a contact in a different manager.

See also id() and QContactManager::saveContact().

bool QContact::setPreferredDetail(const QString & actionName, const QContactDetail & preferredDetail)

Set a particular detail (preferredDetail) as the preferred detail for any actions with the given actionName.

The preferredDetail object must exist in this object, and the actionName cannot be empty.

Returns true if the preference could be recorded, and false otherwise.

See also preferredDetail().

void QContact::setTags(const QStringList & tags)

Sets the list of tags associated with the contact to tags.

See also tags() and QContactTag.

void QContact::setType(const QContactType::TypeValues & type)

Sets the type of the contact to the given type.

See also type().

QStringList QContact::tags() const

Returns the list of tags for this contact. Tags are used for non-exclusive categorization.

See also setTags() and QContactTag.

QContactType::TypeValues QContact::type() const

Returns the type of the contact. Every contact has exactly one type which is either set manually (by saving a modified copy of the QContactType in the contact, or by calling setType()) or synthesized automatically.

See also setType().

bool QContact::operator!=(const QContact & other) const

Returns true if this contacts id or details are different to those of the other contact.

QContact & QContact::operator=(const QContact & other)

Replace the contents of this QContact with other

bool QContact::operator==(const QContact & other) const

Returns true if this contact is equal to the other contact, false if either the id or stored details are not the same