FCL/sf/mw/qtextensions: comparison qtmobility/src/contacts/qcontactmanager.cpp

equal deleted inserted replaced

-:90517678cc4f
+:453da2cfceef
 /*!
 \class QContactManager
 \brief The QContactManager class provides an interface which allows clients with access to contact information stored in a particular backend.
 \ingroup contacts-main
-This class provides adding, updating and removal of contacts.
+This class provides an abstraction of a datastore or aggregation of datastores which contains contact information.
-It also provides definitions for details and fields that can be found in contacts.
+It provides methods to retrieve and manipulate contact information, contact relationship information, and
+supported schema definitions.  It also provides metadata and error information reporting.
+The functions provided by QContactManager are purely synchronous; to access the same functionality in an
+asynchronous manner, clients should use the use-case-specific classes derived from QContactAbstractRequest.
+Some functionality provided by QContactManager directly is not accessible using the asynchronous API; see
+the \l{Contacts Synchronous API}{synchronous} and \l{Contacts Asynchronous API}{asynchronous} API
+information from the \l{Contacts}{contacts module} API documentation.
 */
 /*!
 \fn QContactManager::dataChanged()
 This signal is emitted by the manager if its internal state changes, and it is unable to determine the changes
 /*!
 Return the list of contact ids, sorted according to the given list of \a sortOrders
 */
 QList<QContactLocalId> QContactManager::contactIds(const QList<QContactSortOrder>& sortOrders) const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->contactIds(QContactFilter(), sortOrders, &d->m_error);
 }
 /*!
 Returns a list of contact ids that match the given \a filter, sorted according to the given list of \a sortOrders.
 Depending on the backend, this filtering operation may involve retrieving all the contacts.
 */
 QList<QContactLocalId> QContactManager::contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders) const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->contactIds(filter, sortOrders, &d->m_error);
 }
 /*!
 Returns the list of contacts stored in the manager sorted according to the given list of \a sortOrders.
 The \a fetchHint parameter describes the optimization hints that a manager may take.
-If the \a fetchHint is the default constructed hint, all existing details, relationships and action preferences
+If the \a fetchHint is the default constructed hint, all existing details and relationships
 in the matching contacts will be returned.  A client should not make changes to a contact which has
 been retrieved using a fetch hint other than the default fetch hint.  Doing so will result in information
 loss when saving the contact back to the manager (as the "new" restricted contact will
 replace the previously saved contact in the backend).
 \sa QContactFetchHint
 */
 QList<QContact> QContactManager::contacts(const QList<QContactSortOrder>& sortOrders, const QContactFetchHint& fetchHint) const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->contacts(QContactFilter(), sortOrders, fetchHint, &d->m_error);
 }
 /*!
 Returns a list of contacts that match the given \a filter, sorted according to the given list of \a sortOrders.
 Depending on the manager implementation, this filtering operation might be slow and involve retrieving all the
 contacts and testing them against the supplied filter - see the \l isFilterSupported() function.
 The \a fetchHint parameter describes the optimization hints that a manager may take.
-If the \a fetchHint is the default constructed hint, all existing details, relationships and action preferences
+If the \a fetchHint is the default constructed hint, all existing details and relationships
 in the matching contacts will be returned.  A client should not make changes to a contact which has
 been retrieved using a fetch hint other than the default fetch hint.  Doing so will result in information
 loss when saving the contact back to the manager (as the "new" restricted contact will
 replace the previously saved contact in the backend).
 \sa QContactFetchHint
 */
 QList<QContact> QContactManager::contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders, const QContactFetchHint& fetchHint) const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->contacts(filter, sortOrders, fetchHint, &d->m_error);
 }
 /*!
 Returns the contact in the database identified by \a contactId.
 If the contact does not exist, an empty, default constructed QContact will be returned,
 and the error returned by \l error() will be \c QContactManager::DoesNotExistError.
 The \a fetchHint parameter describes the optimization hints that a manager may take.
-If the \a fetchHint is the default constructed hint, all existing details, relationships and action preferences
+If the \a fetchHint is the default constructed hint, all existing details and relationships
 in the matching contact will be returned.  A client should not make changes to a contact which has
 been retrieved using a fetch hint other than the default fetch hint.  Doing so will result in information
 loss when saving the contact back to the manager (as the "new" restricted contact will
 replace the previously saved contact in the backend).
 \sa QContactFetchHint
 */
 QContact QContactManager::contact(const QContactLocalId& contactId, const QContactFetchHint& fetchHint) const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->contact(contactId, fetchHint, &d->m_error);
 }
 /*!
 Adds the given \a contact to the database if \a contact has a
 \sa managerUri()
 */
 bool QContactManager::saveContact(QContact* contact)
 {
 if (contact) {
+d->m_error = QContactManager::NoError;
 return d->m_engine->saveContact(contact, &d->m_error);
 } else {
 d->m_error = QContactManager::BadArgumentError;
 return false;
 }
 Returns true if the contact was removed successfully, otherwise
 returns false.
 */
 bool QContactManager::removeContact(const QContactLocalId& contactId)
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->removeContact(contactId, &d->m_error);
 }
 /*!
 Adds the list of contacts given by \a contacts list to the database.
 errorMap->clear();
 if (!contacts) {
 d->m_error =QContactManager::BadArgumentError;
 return false;
 }
+d->m_error = QContactManager::NoError;
 return d->m_engine->saveContacts(contacts, errorMap, &d->m_error);
 }
 /*!
 Remove every contact whose id is contained in the list of contacts ids
 \sa QContactManager::removeContact()
 */
 bool QContactManager::removeContacts(const QList<QContactLocalId>& contactIds, QMap<int, QContactManager::Error>* errorMap)
 {
+if (errorMap)
+errorMap->clear();
 if (contactIds.isEmpty()) {
 d->m_error = QContactManager::BadArgumentError;
 return false;
 }
-if (errorMap)
+d->m_error = QContactManager::NoError;
-errorMap->clear();
 return d->m_engine->removeContacts(contactIds, errorMap, &d->m_error);
 }
 /*!
 \preliminary
 This function is preliminary and the behaviour is subject to change!
 */
 QContact QContactManager::compatibleContact(const QContact& original)
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->compatibleContact(original, &d->m_error);
 }
 /*!
-Returns a display label for a \a contact which is synthesized from its details in a platform-specific manner
+Returns a display label for a \a contact which is synthesized from its details in a manager specific
-*/
+manner.
-QString QContactManager::synthesizedDisplayLabel(const QContact& contact) const
-{
+If you want to update the display label stored in the contact, use the synthesizeContactDisplayLabel()
+function instead.
+\sa synthesizeContactDisplayLabel()
+*/
+QString QContactManager::synthesizedContactDisplayLabel(const QContact& contact) const
+{
+d->m_error = QContactManager::NoError;
 return d->m_engine->synthesizedDisplayLabel(contact, &d->m_error);
+}
+/*!
+* Updates the display label of the supplied \a contact, according to the formatting rules
+* of this manager.
+*
+* Different managers can format the display label of a contact in different ways -
+* some managers may only consider first or last name, or might put them in different
+* orders.  Others might consider an organization, a nickname, or a freeform label.
+*
+* This function will update the QContactDisplayLabel of this contact, and the string
+* returned by QContact::displayLabel().
+*
+* If \a contact is null, nothing will happen.
+*
+* See the following example for more information:
+* \snippet doc/src/snippets/qtcontactsdocsample/qtcontactsdocsample.cpp Updating the display label of a contact
+*
+* \sa synthesizedContactDisplayLabel(), QContact::displayLabel()
+*/
+void QContactManager::synthesizeContactDisplayLabel(QContact *contact) const
+{
+if (contact) {
+d->m_error = QContactManager::NoError;
+QContactManagerEngine::setContactDisplayLabel(contact, d->m_engine->synthesizedDisplayLabel(*contact, &d->m_error));
+} else {
+d->m_error = QContactManager::BadArgumentError;
+}
 }
 /*!
 Sets the id of the "self" contact to the given \a contactId.
 Returns true if the "self" contact id was set successfully.
 \c QContactManager::NotSupportedError and the function will
 return false.
 */
 bool QContactManager::setSelfContactId(const QContactLocalId& contactId)
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->setSelfContactId(contactId, &d->m_error);
 }
 /*!
 Returns the id of the "self" contact which has previously been set.
 the concept of a "self" contact, an invalid id will be returned
 and the error will be set to \c QContactManager::DoesNotExistError.
 */
 QContactLocalId QContactManager::selfContactId() const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->selfContactId(&d->m_error);
 }
 /*!
 Returns a list of relationships in which the contact identified by the given \a participantId participates in the given \a role.
 If \a participantId is the default-constructed id, \a role is ignored and all relationships are returned.
 */
 QList<QContactRelationship> QContactManager::relationships(const QContactId& participantId, QContactRelationship::Role role) const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->relationships(QString(), participantId, role, &d->m_error);
 }
 /*!
 Returns a list of relationships of the given \a relationshipType in which the contact identified by the given \a participantId participates in the given \a role.
 If \a participantId is the default-constructed id, \a role is ignored and all relationships of the given \a relationshipType are returned.
 If \a relationshipType is empty, relationships of any type are returned.
 */
 QList<QContactRelationship> QContactManager::relationships(const QString& relationshipType, const QContactId& participantId, QContactRelationship::Role role) const
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->relationships(relationshipType, participantId, role, &d->m_error);
 }
 /*!
 Saves the given \a relationship in the database.  If the relationship already exists in the database, this function will
 the function will return \c false and error will be set to \c QContactManager::NotSupportedError.
 */
 bool QContactManager::saveRelationship(QContactRelationship* relationship)
 {
 if (relationship) {
+d->m_error = QContactManager::NoError;
 return d->m_engine->saveRelationship(relationship, &d->m_error);
 } else {
 d->m_error =QContactManager::BadArgumentError;
 return false;
 }
 with the key being the index into the input relationships list, and the value being the error which
 occurred for that index.
 */
 bool QContactManager::saveRelationships(QList<QContactRelationship>* relationships, QMap<int, QContactManager::Error>* errorMap)
 {
-// check arguments
 if (errorMap)
 errorMap->clear();
 if (!relationships) {
 d->m_error =QContactManager::BadArgumentError;
 return false;
 }
+d->m_error = QContactManager::NoError;
 return d->m_engine->saveRelationships(relationships, errorMap, &d->m_error);
 }
 /*!
 Removes the given \a relationship from the manager.  If the relationship exists in the manager, the relationship
 relationship exists in the manager, the error will be set to \c QContactManager::DoesNotExistError and this function
 will return false.
 */
 bool QContactManager::removeRelationship(const QContactRelationship& relationship)
 {
+d->m_error = QContactManager::NoError;
 return d->m_engine->removeRelationship(relationship, &d->m_error);
 }
 /*!
 Removes the given \a relationships from the database and returns true if the operation was successful.
 */
 bool QContactManager::removeRelationships(const QList<QContactRelationship>& relationships, QMap<int, QContactManager::Error>* errorMap)
 {
 if (errorMap)
 errorMap->clear();
+d->m_error = QContactManager::NoError;
 return d->m_engine->removeRelationships(relationships, errorMap, &d->m_error);
 }
 /*!
 Returns a map of identifier to detail definition for the registered detail definitions which are valid for contacts whose type is the given \a contactType
 if (!supportedContactTypes().contains(contactType)) {
 d->m_error =QContactManager::InvalidContactTypeError;
 return QMap<QString, QContactDetailDefinition>();
 }
+d->m_error = QContactManager::NoError;
 return d->m_engine->detailDefinitions(contactType, &d->m_error);
 }
 /*! Returns the definition identified by the given \a definitionName that is valid for the contacts whose type is the given \a contactType in this store, or a default-constructed QContactDetailDefinition if no such definition exists */
 QContactDetailDefinition QContactManager::detailDefinition(const QString& definitionName, const QString& contactType) const
 if (!supportedContactTypes().contains(contactType)) {
 d->m_error =QContactManager::InvalidContactTypeError;
 return QContactDetailDefinition();
 }
+d->m_error = QContactManager::NoError;
 return d->m_engine->detailDefinition(definitionName, contactType, &d->m_error);
 }
 /*! Persists the given definition \a def in the database, which is valid for contacts whose type is the given \a contactType.  Returns true if the definition was saved successfully, otherwise returns false */
 bool QContactManager::saveDetailDefinition(const QContactDetailDefinition& def, const QString& contactType)
 if (!supportedContactTypes().contains(contactType)) {
 d->m_error =QContactManager::InvalidContactTypeError;
 return false;
 }
+d->m_error = QContactManager::NoError;
 return d->m_engine->saveDetailDefinition(def, contactType, &d->m_error);
 }
 /*! Removes the detail definition identified by \a definitionName from the database, which is valid for contacts whose type is the given \a contactType.  Returns true if the definition was removed successfully, otherwise returns false */
 bool QContactManager::removeDetailDefinition(const QString& definitionName, const QString& contactType)
 if (!supportedContactTypes().contains(contactType)) {
 d->m_error =QContactManager::InvalidContactTypeError;
 return false;
 }
+d->m_error = QContactManager::NoError;
 return d->m_engine->removeDetailDefinition(definitionName, contactType, &d->m_error);
 }
 /*!
 \enum QContactManager::ManagerFeature
 This enum describes the possible features that a particular manager may support
-\value Groups The manager supports all QContactGroup related operations, and emits the appropriate signals
+\value Groups The manager supports saving contacts of the \c QContactType::TypeGroup type
-\value ActionPreferences The manager supports saving preferred details per action per contact
+\omitvalue ActionPreferences The manager supports saving preferred details per action per contact
 \value DetailOrdering When a contact is retrieved, the manager will return the details in the same order in which they were saved
 \value Relationships The manager supports at least some types of relationships between contacts
 \value ArbitraryRelationshipTypes The manager supports relationships of arbitrary types between contacts
 \value MutableDefinitions The manager supports saving, updating or removing detail definitions.  Some built-in definitions may still be immutable
 \value SelfContact The manager supports the concept of saving a contact which represents the current user

changeset 5	453da2cfceef
parent 4	90517678cc4f
child 8	71781823f776