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
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.
QContactDetail QContact::detail ( const QString & definitionName ) const
Returns the first detail stored in the contact with the given definitionName
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>();
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 ( 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.
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.
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>();
Returns a list of details of the given definitionName, with fields named fieldName and with value value.
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>();
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");
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:
QContact c = manager->contact(myId);
qDebug() << "Current display label" << c.displayLabel();
QContactName name = c.detail<QContactName>();
name.setFirstName("Abigail");
name.setLastName("Arkansas");
c.saveDetail(&name);
manager->synthesizeContactDisplayLabel(&c);
qDebug() << "Now the label is:" << c.displayLabel();
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.
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.
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().
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.
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().
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.
QList<QContactId> groupMembers = groupContact.relatedContacts(QContactRelationship::HasMember, QContactRelationship::Second);
QList<QContactId> contactGroups = contact.relatedContacts(QContactRelationship::HasMember, QContactRelationship::First);
QList<QContactId> spouses = contact.relatedContacts(QContactRelationship::HasSpouse, QContactRelationship::Either);
if (spouses.count() > 1) {
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);
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.
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.
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.
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::setType ( const QString & type )
Sets the type of the contact to the given type.
See also type().
void QContact::setType ( const QContactType & type )
Sets the type of the contact to the given type detail.
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.
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
