QContact Class Reference

 #include <QContact>

Member Function Documentation

QContact::QContact ()

Construct an empty contact.

The contact will have an empty display label, 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.

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.

This function was introduced in Qt Mobility 1.0.

void QContact::clearTags ()

Removes all tags associated with the contact.

See also QContactTag.

QContactDetail QContact::detail ( const QString & definitionName ) const

Returns the first detail stored in the contact with the given definitionName

This function was introduced in Qt Mobility 1.0.

QContactDetail QContact::detail ( const QLatin1Constant & definitionName ) const

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

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

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

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

This function was introduced in Qt Mobility 1.0.

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.

This function was introduced in Qt Mobility 1.0.

QList<QContactDetail> QContact::details ( const QString & definitionName = QString() ) const

Returns a list of details with the given definitionName The definitionName string can be determined by the DefinitionName attribute of defined objects (e.g. QContactPhoneNumber::DefinitionName) or by requesting a list of all the definitions synchronously with detailDefinitions() or asynchronously with a detail definition fetch request, and then inspecting the name() of each definition. If definitionName is empty, all details of any definition will be returned.

This function was introduced in Qt Mobility 1.0.

QList<QContactDetail> QContact::details ( const QString & definitionName, const QString & fieldName, const QString & value ) const

Returns a list of details of the given definitionName, with fields named fieldName and with value value. The definitionName string can be determined by the DefinitionName attribute of defined objects (e.g. QContactPhoneNumber::DefinitionName) or by requesting a list of all the definitions synchronously with detailDefinitions() or asynchronously with a detail definition fetch request, and then inspecting the name() of each definition. If definitionName is empty, all details of any definition will be returned.

This function was introduced in Qt Mobility 1.0.

QList<QContactDetail> QContact::details ( const QLatin1Constant & definitionName ) const

Returns a list of details of the given definitionName.

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

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

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

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

This function was introduced in Qt Mobility 1.0.

QList<QContactDetail> QContact::details ( const QLatin1Constant & definitionName, const QLatin1Constant & fieldName, const QString & value )

Returns a list of details of the given definitionName, with fields named fieldName and with value value.

This function was introduced in Qt Mobility 1.0.

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

This function was introduced in Qt Mobility 1.0.

QList<T> QContact::details ( const QString & fieldName, const QString & value ) const

Returns a list of details of the template parameter type which have field called fieldName, with matching value. The type must be a subclass of QContactDetail.

For example:

 QList<QContactPhoneNumber> homePhones = contact.details<QContactPhoneNumber>("Context", "Home");

This function was introduced in Qt Mobility 1.0.

QString QContact::displayLabel () const

Returns the display label of this contact.

A contact which has been retrieved from a manager will have a display label set when the contact is retrieved.

The display label is usually read-only, since some managers do not support arbitrary labels (see also QContactName::setCustomLabel()). If you modify the contact in a way that would affect the display label, you can call QContactManager::synthesizeContactDisplayLabel() to get an up-to-date display label.

See the following example for more information:

     /* Retrieve a contact */
     QContact c = manager->contact(myId);
     qDebug() << "Current display label" << c.displayLabel();

     /* Update some fields that might influence the display label */
     QContactName name = c.detail<QContactName>();
     name.setFirstName("Abigail");
     name.setLastName("Arkansas");
     c.saveDetail(&name);

     /* Update the display label */
     manager->synthesizeContactDisplayLabel(&c);
     qDebug() << "Now the label is:" << c.displayLabel();

This function was introduced in Qt Mobility 1.0.

See also QContactManager::synthesizeContactDisplayLabel().

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.

This function was introduced in Qt Mobility 1.0.

See also setId() and localId().

bool QContact::isEmpty () const

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

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

This function was introduced in Qt Mobility 1.0.

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

QContactLocalId QContact::localId () const

Returns the QContactLocalId that identifies this contact within its manager

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 QContactLocalId is associated with a specific manager, but other contacts with the same local id might exist in different managers.

See QContactManager::saveContact() for more information.

This function was introduced in Qt Mobility 1.0.

See also id().

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<QContactId> 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);
 }

This function was introduced in Qt Mobility 1.0.

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

This function was introduced in Qt Mobility 1.0.

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.

This function was introduced in Qt Mobility 1.0.

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.

If detail is a QContactDisplayLabel, the contact will not be updated, and the function will return false. Since the display label formatting is specific to each manager, use the QContactManager::synthesizeContactDisplayLabel() function instead.

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.

This function was introduced in Qt Mobility 1.0.

See also QContactManager::synthesizeContactDisplayLabel().

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.

This function was introduced in Qt Mobility 1.0.

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 QString & type )

Sets the type of the contact to the given type.

This function was introduced in Qt Mobility 1.0.

See also type().

void QContact::setType ( const QContactType & type )

Sets the type of the contact to the given type detail.

This function was introduced in Qt Mobility 1.0.

QStringList QContact::tags () const

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

See also setTags() and QContactTag.

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

This function was introduced in Qt Mobility 1.0.

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.

This function was introduced in Qt Mobility 1.0.

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

Replace the contents of this QContact with other *

This function was introduced in Qt Mobility 1.0.

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

This function was introduced in Qt Mobility 1.0.