The QContact class represents an addressbook contact. More...
#include <QContact>This class was introduced in Qt Mobility 1.0.
| QContact () | |
| QContact ( const QContact & other ) | |
| ~QContact () | |
| void | addTag ( const QString & tag ) |
| QList<QContactActionDescriptor> | availableActions ( const QString & serviceName = QString() ) const |
| void | clearDetails () |
| void | clearTags () |
| QContactDetail | detail ( const QString & definitionName ) const |
| QContactDetail | detail ( const QLatin1Constant & definitionName ) const |
| T | detail () const |
| QList<QContactDetail> | details ( const QString & definitionName = QString() ) const |
| QList<QContactDetail> | details ( const QString & definitionName, const QString & fieldName, const QString & value ) const |
| QList<QContactDetail> | details ( const QLatin1Constant & definitionName ) const |
| QList<QContactDetail> | details ( const QLatin1Constant & definitionName, const QLatin1Constant & fieldName, const QString & value ) |
| QList<T> | details () const |
| QList<T> | details ( const QString & fieldName, const QString & value ) const |
| QString | displayLabel () const |
| QContactId | id () const |
| bool | isEmpty () const |
| bool | isPreferredDetail ( const QString & actionName, const QContactDetail & detail ) const |
| QContactLocalId | localId () const |
| QContactDetail | preferredDetail ( const QString & actionName ) const |
| QMap<QString, QContactDetail> | preferredDetails () const |
| QList<QContactId> | relatedContacts ( const QString & relationshipType = QString(), QContactRelationship::Role role = QContactRelationship::Either ) const |
| QList<QContactRelationship> | relationships ( const QString & relationshipType = QString() ) const |
| bool | removeDetail ( QContactDetail * detail ) |
| bool | saveDetail ( QContactDetail * detail ) |
| void | setId ( const QContactId & id ) |
| bool | setPreferredDetail ( const QString & actionName, const QContactDetail & preferredDetail ) |
| void | setTags ( const QStringList & tags ) |
| void | setType ( const QString & type ) |
| void | setType ( const QContactType & type ) |
| QStringList | tags () const |
| QString | type () const |
| bool | operator!= ( const QContact & other ) const |
| QContact & | operator= ( const QContact & other ) |
| bool | operator== ( const QContact & other ) const |
| uint | qHash ( const QContact & key ) |
The QContact class represents an addressbook contact.
Individual contacts, groups, and other types of contacts are represented with a QContact object. In addition to the type, a QContact consists of information that belongs to the contact, some information about the relationships that the contact has, and the preferred ways to interact with the contact.
A QContact object has a collection of details (like a name, phone numbers and email addresses). Each detail (which can have multiple fields) is stored in an appropriate subclass of QContactDetail, and the QContact allows retrieving these details in various ways.
Depending on the details of the QContact, certain actions are available for a contact. An instance of a QContact can return a list of actions that can be performed on it, and a list of details supported by a specific action can be retrieved (for example - a list of phone numbers supported by a specific "Call" action). It is also possible to store one detail for each type of action that is the "preferred" detail to use.
A QContact may have zero or more relationships with other contacts. For example, a group contact would have a "HasMember" relationship with the QContacts that are its members. Spouses, managers and assistants can also be represented this way.
A QContact instance represents the in-memory version of an addressbook contact, and has no tie to a specific QContactManager. It is possible for the contents of a QContact to change independently of the contents that are stored persistently in a QContactManager. A QContact has an ID associated with it when it is first retrieved from a QContactManager, or after it has been first saved, and this allows clients to track changes using the signals in QContactManager.
A QContact has a number of mandatory details:
If you have edited the contents of a QContact (via saving or removing details), you will need to ask a specific QContactManager for the new display label for the contact, since system settings (like the order of first or last names) can vary between managers.
See also QContactManager and QContactDetail.
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.
Initializes this QContact from other
Frees the memory used by this QContact
Adds the tag to this contact.
See also QContactTag.
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.
Removes all details of the contact. This function does not modify the id of the contact. Calling isEmpty() after calling this function will return true.
This function was introduced in Qt Mobility 1.0.
Removes all tags associated with the contact.
See also QContactTag.
Returns the first detail stored in the contact with the given definitionName
This function was introduced in Qt Mobility 1.0.
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.
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.
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.
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.
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.
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.
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.
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.
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().
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().
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.
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().
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().
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().
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.
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().
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().
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.
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().
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().
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().
Sets the list of tags associated with the contact to tags.
See also tags() and QContactTag.
Sets the type of the contact to the given type.
This function was introduced in Qt Mobility 1.0.
See also type().
Sets the type of the contact to the given type detail.
This function was introduced in Qt Mobility 1.0.
Returns the list of tags for this contact. Tags are used for non-exclusive categorization.
See also setTags() and QContactTag.
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().
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.
Replace the contents of this QContact with other *
This function was introduced in Qt Mobility 1.0.
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.
Returns the hash value for key.
This function was introduced in Qt Mobility 1.0.