QtMobility Reference Documentation

QContactManagerEngine Class Reference

The QContactManagerEngine class provides the interface for implementations of the contact manager backend functionality. More...

 #include <QContactManagerEngine>

Inherits: QObject.

Inherited by: QContactManagerEngineV2.

This class was introduced in Qt Mobility 1.0.

Public Functions

QContactManagerEngine ()
virtual bool cancelRequest ( QContactAbstractRequest * req )
virtual QContact compatibleContact ( const QContact & original, QContactManager::Error * error ) const
virtual QContact contact ( const QContactLocalId & contactId, const QContactFetchHint & fetchHint, QContactManager::Error * error ) const
virtual QList<QContactLocalId> contactIds ( const QContactFilter & filter, const QList<QContactSortOrder> & sortOrders, QContactManager::Error * error ) const
virtual QList<QContact> contacts ( const QContactFilter & filter, const QList<QContactSortOrder> & sortOrders, const QContactFetchHint & fetchHint, QContactManager::Error * error ) const
virtual QContactDetailDefinition detailDefinition ( const QString & definitionName, const QString & contactType, QContactManager::Error * error ) const
virtual QMap<QString, QContactDetailDefinition> detailDefinitions ( const QString & contactType, QContactManager::Error * error ) const
virtual bool hasFeature ( QContactManager::ManagerFeature feature, const QString & contactType ) const
virtual bool isFilterSupported ( const QContactFilter & filter ) const
virtual bool isRelationshipTypeSupported ( const QString & relationshipType, const QString & contactType ) const
virtual QString managerName () const = 0
virtual QMap<QString, QString> managerParameters () const
QString managerUri () const
virtual int managerVersion () const = 0
virtual QList<QContactRelationship> relationships ( const QString & relationshipType, const QContactId & participantId, QContactRelationship::Role role, QContactManager::Error * error ) const
virtual bool removeContact ( const QContactLocalId & contactId, QContactManager::Error * error )
virtual bool removeContacts ( const QList<QContactLocalId> & contactIds, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error )
virtual bool removeDetailDefinition ( const QString & definitionName, const QString & contactType, QContactManager::Error * error )
virtual bool removeRelationship ( const QContactRelationship & relationship, QContactManager::Error * error )
virtual bool removeRelationships ( const QList<QContactRelationship> & relationships, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error )
virtual void requestDestroyed ( QContactAbstractRequest * req )
virtual bool saveContact ( QContact * contact, QContactManager::Error * error )
virtual bool saveContacts ( QList<QContact> * contacts, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error )
virtual bool saveDetailDefinition ( const QContactDetailDefinition & def, const QString & contactType, QContactManager::Error * error )
virtual bool saveRelationship ( QContactRelationship * relationship, QContactManager::Error * error )
virtual bool saveRelationships ( QList<QContactRelationship> * relationships, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error )
virtual QContactLocalId selfContactId ( QContactManager::Error * error ) const
virtual bool setSelfContactId ( const QContactLocalId & contactId, QContactManager::Error * error )
virtual bool startRequest ( QContactAbstractRequest * req )
virtual QStringList supportedContactTypes () const
virtual QList<QVariant::Type> supportedDataTypes () const
virtual QString synthesizedDisplayLabel ( const QContact & contact, QContactManager::Error * error ) const
virtual bool validateContact ( const QContact & contact, QContactManager::Error * error ) const
virtual bool validateDefinition ( const QContactDetailDefinition & definition, QContactManager::Error * error ) const
virtual bool waitForRequestFinished ( QContactAbstractRequest * req, int msecs )
  • 29 public functions inherited from QObject

Signals

void contactsAdded ( const QList<QContactLocalId> & contactIds )
void contactsChanged ( const QList<QContactLocalId> & contactIds )
void contactsRemoved ( const QList<QContactLocalId> & contactIds )
void dataChanged ()
void relationshipsAdded ( const QList<QContactLocalId> & affectedContactIds )
void relationshipsRemoved ( const QList<QContactLocalId> & affectedContactIds )
void selfContactIdChanged ( const QContactLocalId & oldId, const QContactLocalId & newId )

Static Public Members

void addSorted ( QList<QContact> * sorted, const QContact & toAdd, const QList<QContactSortOrder> & sortOrders )
QContactFilter canonicalizedFilter ( const QContactFilter & filter )
int compareContact ( const QContact & a, const QContact & b, const QList<QContactSortOrder> & sortOrders )
int compareVariant ( const QVariant & first, const QVariant & second, Qt::CaseSensitivity sensitivity )
QMap<QString, QMap<QString, QContactDetailDefinition> > schemaDefinitions ()
QMap<QString, QMap<QString, QContactDetailDefinition> > schemaDefinitions ( int schemaVersion )
void setContactDisplayLabel ( QContact * contact, const QString & displayLabel )
void setContactRelationships ( QContact * contact, const QList<QContactRelationship> & relationships )
void setDetailAccessConstraints ( QContactDetail * detail, QContactDetail::AccessConstraints constraints )
QList<QContactLocalId> sortContacts ( const QList<QContact> & cs, const QList<QContactSortOrder> & sortOrders )
bool testFilter ( const QContactFilter & filter, const QContact & contact )
void updateContactFetchRequest ( QContactFetchRequest * req, const QList<QContact> & result, QContactManager::Error error, QContactAbstractRequest::State newState )
void updateContactLocalIdFetchRequest ( QContactLocalIdFetchRequest * req, const QList<QContactLocalId> & result, QContactManager::Error error, QContactAbstractRequest::State newState )
void updateContactRemoveRequest ( QContactRemoveRequest * req, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState )
void updateContactSaveRequest ( QContactSaveRequest * req, const QList<QContact> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState )
void updateDefinitionFetchRequest ( QContactDetailDefinitionFetchRequest * req, const QMap<QString, QContactDetailDefinition> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState )
void updateDefinitionRemoveRequest ( QContactDetailDefinitionRemoveRequest * req, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState )
void updateDefinitionSaveRequest ( QContactDetailDefinitionSaveRequest * req, const QList<QContactDetailDefinition> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState )
void updateRelationshipFetchRequest ( QContactRelationshipFetchRequest * req, const QList<QContactRelationship> & result, QContactManager::Error error, QContactAbstractRequest::State newState )
void updateRelationshipRemoveRequest ( QContactRelationshipRemoveRequest * req, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState )
void updateRelationshipSaveRequest ( QContactRelationshipSaveRequest * req, const QList<QContactRelationship> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState )
void updateRequestState ( QContactAbstractRequest * req, QContactAbstractRequest::State state )
  • 4 static public members inherited from QObject

Additional Inherited Members

  • 1 property inherited from QObject
  • 1 public slot inherited from QObject
  • 1 public variable inherited from QObject
  • 7 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

The QContactManagerEngine class provides the interface for implementations of the contact manager backend functionality.

Instances of this class are usually provided by a QContactManagerEngineFactory, which is loaded from a plugin.

The default implementation of this interface provides a basic level of functionality for some functions so that specific engines can simply implement the functionality that is supported by the specific contacts engine that is being adapted.

More information on writing a contacts engine plugin is available in the Qt Contacts Manager Engines documentation.

See also QContactManager and QContactManagerEngineFactory.

Member Function Documentation

QContactManagerEngine::QContactManagerEngine ()

A default, empty constructor.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::addSorted ( QList<QContact> * sorted, const QContact & toAdd, const QList<QContactSortOrder> & sortOrders ) [static]

Performs insertion sort of the contact toAdd into the sorted list, according to the provided sortOrders list. The first QContactSortOrder in the list has the highest priority: if the contact toAdd is deemed equal to another in the sorted list according to the first QContactSortOrder, the second QContactSortOrder in the list is used (and so on until either the contact is inserted or there are no more sort order objects in the list).

If a contact is equal to another contact according to all sort orders, it is inserted after the previously-added contact.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::cancelRequest ( QContactAbstractRequest * req ) [virtual]

Asks the manager engine to cancel the given request req which was previously started and is currently in a cancellable state. Returns true if cancellation of the request was started successfully, otherwise returns false.

This function was introduced in Qt Mobility 1.0.

See also startRequest() and QContactAbstractRequest::cancel().

QContactFilter QContactManagerEngine::canonicalizedFilter ( const QContactFilter & filter ) [static]

Given an input filter, returns the canonical version of the filter.

Some of the following transformations may be applied:

This function was introduced in Qt Mobility 1.0.

int QContactManagerEngine::compareContact ( const QContact & a, const QContact & b, const QList<QContactSortOrder> & sortOrders ) [static]

Compares two contacts (a and b) using the given list of sortOrders. Returns a negative number if a should appear before b according to the sort order, a positive number if a should appear after b according to the sort order, and zero if the two are unable to be sorted.

This function was introduced in Qt Mobility 1.0.

int QContactManagerEngine::compareVariant ( const QVariant & first, const QVariant & second, Qt::CaseSensitivity sensitivity ) [static]

Compares first against second. If the types are strings (QVariant::String), the sensitivity argument controls case sensitivity when comparing. Also, when comparing strings, a locale aware comparison is used, and if the sensitivity is CaseSensitive, strings that are identical under a case insensitive sort are then sorted case sensitively within that context.

For example:

aaron Bob Aaron aAron Carol

would sort as:

aaron aAron Aaron Bob Carol

Returns: <0 if first is less than second 0 if first is equal to second >0 if first is greater than second.

The results are undefined if the variants are different types, or cannot be compared.

This function was introduced in Qt Mobility 1.0.

QContact QContactManagerEngine::compatibleContact ( const QContact & original, QContactManager::Error * error ) const [virtual]

Returns a pruned or modified version of the original contact which is valid and can be saved in the manager. The returned contact might have details removed or arbitrarily changed. The cache of relationships in the contact are ignored entirely when considering compatibility with the backend, as they are saved and validated separately. Any error which occurs will be saved to error.

This function was introduced in Qt Mobility 1.0.

QContact QContactManagerEngine::contact ( const QContactLocalId & contactId, const QContactFetchHint & fetchHint, QContactManager::Error * error ) const [virtual]

Returns the contact in the database identified by contactId.

If the contact does not exist, an empty, default constructed QContact will be returned, and the error will be set to QContactManager::DoesNotExistError.

Any operation error which occurs will be saved in error.

The fetchHint parameter describes the optimization hints that a manager may take. If the fetchHint is the default constructed hint, all existing details, relationships and action preferences in the matching contact will be returned. If a client makes changes to an contact which has been retrieved with a fetch hint, they should save it back using a partial save, masked by the same set of detail names in order to avoid information loss.

This function was introduced in Qt Mobility 1.0.

See also QContactFetchHint.

QList<QContactLocalId> QContactManagerEngine::contactIds ( const QContactFilter & filter, const QList<QContactSortOrder> & sortOrders, QContactManager::Error * error ) const [virtual]

Returns a list of contact ids that match the given filter, sorted according to the given list of sortOrders. Depending on the backend, this filtering operation may involve retrieving all the contacts. Any error which occurs will be saved in error.

This function was introduced in Qt Mobility 1.0.

QList<QContact> QContactManagerEngine::contacts ( const QContactFilter & filter, const QList<QContactSortOrder> & sortOrders, const QContactFetchHint & fetchHint, QContactManager::Error * error ) const [virtual]

Returns the list of contacts which match the given filter stored in the manager sorted according to the given list of sortOrders.

Any operation error which occurs will be saved in error.

The fetchHint parameter describes the optimization hints that a manager may take. If the fetchHint is the default constructed hint, all existing details, relationships and action preferences in the matching contacts will be returned.

If a non-default fetch hint is supplied, and the client wishes to make changes to the contacts, they should ensure that only a detail definition hint is supplied and that when saving it back, a definition mask should be used which corresponds to the detail definition hint. This is to ensure that no data is lost by overwriting an existing contact with a restricted version of it.

This function was introduced in Qt Mobility 1.0.

See also QContactFetchHint.

void QContactManagerEngine::contactsAdded ( const QList<QContactLocalId> & contactIds ) [signal]

This signal is emitted some time after a set of contacts has been added to this engine where the dataChanged() signal was not emitted for those changes. As it is possible that other processes (or other devices) may have added the contacts, the timing cannot be determined.

The list of ids of contacts added is given by contactIds. There may be one or more ids in the list.

This function was introduced in Qt Mobility 1.0.

See also dataChanged().

void QContactManagerEngine::contactsChanged ( const QList<QContactLocalId> & contactIds ) [signal]

This signal is emitted some time after a set of contacts has been modified in this engine where the dataChanged() signal was not emitted for those changes. As it is possible that other processes (or other devices) may have modified the contacts, the timing cannot be determined.

The list of ids of changed contacts is given by contactIds. There may be one or more ids in the list.

This function was introduced in Qt Mobility 1.0.

See also dataChanged().

void QContactManagerEngine::contactsRemoved ( const QList<QContactLocalId> & contactIds ) [signal]

This signal is emitted some time after a set of contacts has been removed from this engine where the dataChanged() signal was not emitted for those changes. As it is possible that other processes (or other devices) may have removed the contacts, the timing cannot be determined.

The list of ids of removed contacts is given by contactIds. There may be one or more ids in the list.

This function was introduced in Qt Mobility 1.0.

See also dataChanged().

void QContactManagerEngine::dataChanged () [signal]

This signal is emitted some time after changes occur to the data managed by this engine, and the engine is unable to determine which changes occurred, or if the engine considers the changes to be radical enough to require clients to reload all data.

If this signal is emitted, no other signals may be emitted for the associated changes.

As it is possible that other processes (or other devices) may have caused the changes, the timing can not be determined.

This function was introduced in Qt Mobility 1.0.

See also contactsAdded(), contactsChanged(), and contactsRemoved().

QContactDetailDefinition QContactManagerEngine::detailDefinition ( const QString & definitionName, const QString & contactType, QContactManager::Error * error ) const [virtual]

Returns the definition identified by the given definitionName that is valid for contacts whose type is of the given contactType in this store, or a default-constructed QContactDetailDefinition if no such definition exists

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

QMap<QString, QContactDetailDefinition> QContactManagerEngine::detailDefinitions ( const QString & contactType, QContactManager::Error * error ) const [virtual]

Returns the registered detail definitions which are valid for contacts whose type is of the given contactType in this engine.

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::hasFeature ( QContactManager::ManagerFeature feature, const QString & contactType ) const [virtual]

Returns true if the given feature is supported by this engine for contacts of the given contactType

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::isFilterSupported ( const QContactFilter & filter ) const [virtual]

Returns a whether the supplied filter can be implemented natively by this engine. If not, the base class implementation will emulate the functionality.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::isRelationshipTypeSupported ( const QString & relationshipType, const QString & contactType ) const [virtual]

Returns true if the manager supports the relationship type specified in relationshipType for contacts whose type is the given contactType.

Note that some managers may support the relationship type for a contact in a limited manner (for example, only as the first contact in the relationship, or only as the second contact in the relationship). In this case, it will still return true. It will only return false if the relationship is entirely unsupported for the given type of contact.

This function was introduced in Qt Mobility 1.0.

QString QContactManagerEngine::managerName () const [pure virtual]

Returns the manager name for this QContactManagerEngine

This function was introduced in Qt Mobility 1.0.

QMap<QString, QString> QContactManagerEngine::managerParameters () const [virtual]

Returns the parameters with which this engine was constructed. Note that the engine may have discarded unused or invalid parameters at the time of construction, and these will not be returned.

This function was introduced in Qt Mobility 1.0.

QString QContactManagerEngine::managerUri () const

Returns the unique URI of this manager, which is built from the manager name and the parameters used to construct it.

This function was introduced in Qt Mobility 1.0.

int QContactManagerEngine::managerVersion () const [pure virtual]

Returns the engine backend implementation version number

QList<QContactRelationship> QContactManagerEngine::relationships ( const QString & relationshipType, const QContactId & participantId, QContactRelationship::Role role, QContactManager::Error * error ) const [virtual]

Returns a list of relationships of the given relationshipType in which the contact identified by the given participantId participates in the given role. If participantId is the default-constructed id, role is ignored and all relationships of the given relationshipType are returned. If relationshipType is empty, relationships of any type are returned. If no relationships of the given relationshipType in which the contact identified by the given participantId is involved in the given role exists, error is set to QContactManager::DoesNotExistError.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::relationshipsAdded ( const QList<QContactLocalId> & affectedContactIds ) [signal]

This signal is emitted some time after a set of contacts has been added to this engine where the dataChanged() signal was not emitted for those changes. As it is possible that other processes (or other devices) may have added the contacts, the timing cannot be determined.

The list of ids of affected contacts is given by affectedContactIds. There may be one or more ids in the list.

This function was introduced in Qt Mobility 1.0.

See also dataChanged().

void QContactManagerEngine::relationshipsRemoved ( const QList<QContactLocalId> & affectedContactIds ) [signal]

This signal is emitted some time after a set of relationships has been removed from this engine where the dataChanged() signal was not emitted for those changes. As it is possible that other processes (or other devices) may have removed the relationships, the timing cannot be determined.

The list of ids of affected contacts is given by affectedContactIds. There may be one or more ids in the list.

This function was introduced in Qt Mobility 1.0.

See also dataChanged().

bool QContactManagerEngine::removeContact ( const QContactLocalId & contactId, QContactManager::Error * error ) [virtual]

Remove the contact identified by contactId from the database, and also removes any relationships in which the contact was involved. Returns true if the contact was removed successfully, otherwise returns false.

Any error which occurs will be saved in error.

The default implementation will convert this into a call to removeContacts.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::removeContacts ( const QList<QContactLocalId> & contactIds, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error ) [virtual]

Remove every contact whose id is contained in the list of contacts ids contactIds. Returns true if all contacts were removed successfully, otherwise false.

Any contact that was removed successfully will have the relationships in which it was involved removed also.

The manager might populate errorMap (the map of indices of the contactIds list to the error which occurred when saving the contact at that index) for every index for which the contact could not be removed, if it is able.

The supplied errorMap parameter may be null, if the client does not desire detailed error information. If supplied, it will be empty upon entry to this function.

The QContactManager::error() function will only return QContactManager::NoError if all contacts were removed successfully.

If the list contains ids which do not identify a valid contact in the manager, the function will remove any contacts which are identified by ids in the contactIds list, insert QContactManager::DoesNotExist entries into the errorMap for the indices of invalid ids in the contactIds list, return false, and set the overall operation error to QContactManager::DoesNotExistError.

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

See also QContactManager::removeContact().

bool QContactManagerEngine::removeDetailDefinition ( const QString & definitionName, const QString & contactType, QContactManager::Error * error ) [virtual]

Removes the definition identified by the given definitionName from the database, where it was valid for contacts whose type was the given contactType.

Returns true if the definition was removed successfully, otherwise returns false.

The backend must emit the appropriate signals to inform clients of changes to the database resulting from this operation.

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::removeRelationship ( const QContactRelationship & relationship, QContactManager::Error * error ) [virtual]

Removes the given relationship from the manager. If the relationship exists in the manager, the relationship will be removed, the error will be set to QContactManager::NoError and this function will return true. If no such relationship exists in the manager, the error will be set to QContactManager::DoesNotExistError and this function will return false.

The default implementation of this function converts the argument into a call to removeRelationships

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::removeRelationships ( const QList<QContactRelationship> & relationships, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error ) [virtual]

Removes the given relationships from the database and returns true if the operation was successful. For any relationship which was unable to be removed, an entry into the errorMap will be created, with the key being the index into the input relationships list, and the value being the error which occurred for that index.

The supplied errorMap parameter may be null, if the client does not desire detailed error information. If supplied, it will be empty upon entry to this function.

The overall operation error will be saved in error.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::requestDestroyed ( QContactAbstractRequest * req ) [virtual]

Notifies the manager engine that the given request req is in the process of being destroyed.

The request pointer req is still valid during this function call, but before returning from this call the engine should ensure that it no longer holds any references to the req pointer (for example, in a queue in another thread) because directly following this call the request will be deleted and this pointer will become invalid. In a multithreaded engine, this may mean blocking the calling thread while other threads clean up.

If a request is still in progress at this point, it is undefined what will happen to the operation requested, but in general it should either be fully completed or fully aborted. In any case, the client has signalled that they do not care about the outcome (by deleting the request).

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::saveContact ( QContact * contact, QContactManager::Error * error ) [virtual]

Adds the given contact to the database if contact has a default-constructed id, or an id with the manager URI set to the URI of this manager and a local id of zero, otherwise updates the contact in the database which has the same id to be the given contact. If the id is non-zero but does not identify any contact stored in the manager, the function will return false and error will be set to QContactManager::DoesNotExistError.

Returns true if the save operation completed successfully, otherwise returns false. Any error which occurs will be saved in error.

The default implementation will convert this into a call to saveContacts.

This function was introduced in Qt Mobility 1.0.

See also managerUri().

bool QContactManagerEngine::saveContacts ( QList<QContact> * contacts, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error ) [virtual]

Adds the list of contacts given by contacts list to the database. Returns true if the contacts were saved successfully, otherwise false.

The manager might populate errorMap (the map of indices of the contacts list to the error which occurred when saving the contact at that index) for every index for which the contact could not be saved, if it is able.

The supplied errorMap parameter may be null, if the client does not desire detailed error information. If supplied, it will be empty upon entry to this function.

The QContactManager::error() function will only return QContactManager::NoError if all contacts were saved successfully.

For each newly saved contact that was successful, the id of the contact in the contacts list will be updated with the new value. If a failure occurs when saving a new contact, the id will be cleared.

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

See also QContactManager::saveContact().

bool QContactManagerEngine::saveDetailDefinition ( const QContactDetailDefinition & def, const QString & contactType, QContactManager::Error * error ) [virtual]

Persists the given definition def in the database, which is valid for contacts whose type is the given contactType.

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

The backend must emit the appropriate signals to inform clients of changes to the database resulting from this operation.

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::saveRelationship ( QContactRelationship * relationship, QContactManager::Error * error ) [virtual]

Saves the given relationship in the database. If the relationship already exists in the database, this function will return false and the error will be set to QContactManager::AlreadyExistsError. If the relationship is saved successfully, this function will return true and error will be set to QContactManager::NoError. Note that relationships cannot be updated directly using this function; in order to update a relationship, you must remove the old relationship, make the required modifications, and then save it.

The given relationship is invalid if it is circular (the first contact is the second contact), or if it references a non-existent local contact (either the first or second contact). If the given relationship is invalid, the function will return false and the error will be set to QContactManager::InvalidRelationshipError.

The default implementation of this function converts the argument into a call to saveRelationships.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::saveRelationships ( QList<QContactRelationship> * relationships, QMap<int, QContactManager::Error> * errorMap, QContactManager::Error * error ) [virtual]

Saves the given relationships in the database and returns true if the operation was successful. For any relationship which was unable to be saved, an entry into the errorMap will be created, with the key being the index into the input relationships list, and the value being the error which occurred for that index.

The supplied errorMap parameter may be null, if the client does not desire detailed error information. If supplied, it will be empty upon entry to this function.

The overall operation error will be saved in error.

This function was introduced in Qt Mobility 1.0.

QMap<QString, QMap<QString, QContactDetailDefinition> > QContactManagerEngine::schemaDefinitions () [static]

Returns the schema definitions for version 1 of the API. This function is provided for engine implementors and should not be called by clients. Engine implementors using version 1.1 or later of the Qt Mobility project should use the related function which takes a schema version as a parameter instead.

This function was introduced in Qt Mobility 1.0.

QMap<QString, QMap<QString, QContactDetailDefinition> > QContactManagerEngine::schemaDefinitions ( int schemaVersion ) [static]

Returns the schema definitions for the given schemaVersion version of the API. Note that as of QtMobility 1.1 the current schema version is 2.

This function is provided for engine implementors and should not be called by clients.

Engine implementations using this function to build their supported detail definitions should call this function with the schemaVersion number which corresponds to the version of the Qt Mobility project which was used to develop the engine plugin.

The following schema versions are as follows:

  • 1 Corresponds to version 1.0 of the Qt Mobility project
  • 2 Corresponds to version 1.1 of the Qt Mobility project

This function was introduced in Qt Mobility 1.0.

QContactLocalId QContactManagerEngine::selfContactId ( QContactManager::Error * error ) const [virtual]

Returns the id of the "self" contact which has previously been set. If no "self" contact has been set, or if the self contact was removed from the manager after being set, or if the backend does not support the concept of a "self" contact, an invalid id will be returned and the error will be set to QContactManager::DoesNotExistError.

This function was introduced in Qt Mobility 1.0.

See also setSelfContactId().

void QContactManagerEngine::selfContactIdChanged ( const QContactLocalId & oldId, const QContactLocalId & newId ) [signal]

This signal is emitted at some point after the id of the self-contact is changed from oldId to newId in the manager. If the newId is the invalid, zero id, then the self contact was deleted or no self contact exists. This signal must not be emitted if the dataChanged() signal was previously emitted for this change. As it is possible that other processes (or other devices) may have removed or changed the self contact, the timing cannot be determined.

This function was introduced in Qt Mobility 1.0.

See also dataChanged().

void QContactManagerEngine::setContactDisplayLabel ( QContact * contact, const QString & displayLabel ) [static]

Sets the contact display label of contact to the supplied displayLabel.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::setContactRelationships ( QContact * contact, const QList<QContactRelationship> & relationships ) [static]

Sets the cached relationships in the given contact to relationships

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::setDetailAccessConstraints ( QContactDetail * detail, QContactDetail::AccessConstraints constraints ) [static]

Sets the access constraints of detail to the supplied constraints.

This function is provided to allow engine implementations to report the access constraints of retrieved details, without generally allowing the access constraints to be modified after retrieval.

Application code should not call this function, since validation of the detail will happen in the engine in any case.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::setSelfContactId ( const QContactLocalId & contactId, QContactManager::Error * error ) [virtual]

Sets the id of the "self" contact to the given contactId. Returns true if the "self" contact id was set successfully. If the given contactId does not identify a contact stored in this manager, the error will be set to QContactManager::DoesNotExistError and the function will return false; if the backend does not support the concept of a "self" contact, the error will be set to QContactManager::NotSupportedError and the function will return false.

This function was introduced in Qt Mobility 1.0.

See also selfContactId().

QList<QContactLocalId> QContactManagerEngine::sortContacts ( const QList<QContact> & cs, const QList<QContactSortOrder> & sortOrders ) [static]

Sorts the given list of contacts cs according to the provided sortOrders

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::startRequest ( QContactAbstractRequest * req ) [virtual]

Asks the manager engine to begin the given request req which is currently in a (re)startable state. Returns true if the request was started successfully, else returns false.

This function was introduced in Qt Mobility 1.0.

See also QContactAbstractRequest::start().

QStringList QContactManagerEngine::supportedContactTypes () const [virtual]

Returns the list of contact types which are supported by this engine. This is a convenience function, equivalent to retrieving the allowable values for the QContactType::FieldType field of the QContactType definition which is valid in this engine.

This function was introduced in Qt Mobility 1.0.

QList<QVariant::Type> QContactManagerEngine::supportedDataTypes () const [virtual]

Returns the list of data types supported by this engine.

This function was introduced in Qt Mobility 1.0.

QString QContactManagerEngine::synthesizedDisplayLabel ( const QContact & contact, QContactManager::Error * error ) const [virtual]

Synthesizes the display label of the given contact in a platform specific manner. Any error that occurs will be stored in error. Returns the synthesized display label.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::testFilter ( const QContactFilter & filter, const QContact & contact ) [static]

Returns true if the supplied contact contact matches the supplied filter filter.

This function will test each condition in the filter, possibly recursing.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateContactFetchRequest ( QContactFetchRequest * req, const QList<QContact> & result, QContactManager::Error error, QContactAbstractRequest::State newState ) [static]

Updates the given QContactFetchRequest req with the latest results result, and operation error error. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateContactLocalIdFetchRequest ( QContactLocalIdFetchRequest * req, const QList<QContactLocalId> & result, QContactManager::Error error, QContactAbstractRequest::State newState ) [static]

Updates the given QContactLocalIdFetchRequest req with the latest results result, and operation error error. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateContactRemoveRequest ( QContactRemoveRequest * req, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState ) [static]

Updates the given QContactRemoveRequest req with the operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateContactSaveRequest ( QContactSaveRequest * req, const QList<QContact> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState ) [static]

Updates the given QContactSaveRequest req with the latest results result, operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateDefinitionFetchRequest ( QContactDetailDefinitionFetchRequest * req, const QMap<QString, QContactDetailDefinition> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState ) [static]

Updates the given QContactDetailDefinitionFetchRequest req with the latest results result, operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateDefinitionRemoveRequest ( QContactDetailDefinitionRemoveRequest * req, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState ) [static]

Updates the given QContactDetailDefinitionRemoveRequest req with the operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateDefinitionSaveRequest ( QContactDetailDefinitionSaveRequest * req, const QList<QContactDetailDefinition> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState ) [static]

Updates the given QContactDetailDefinitionSaveRequest req with the latest results result, operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateRelationshipFetchRequest ( QContactRelationshipFetchRequest * req, const QList<QContactRelationship> & result, QContactManager::Error error, QContactAbstractRequest::State newState ) [static]

Updates the given QContactRelationshipFetchRequest req with the latest results result, and operation error error. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateRelationshipRemoveRequest ( QContactRelationshipRemoveRequest * req, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState ) [static]

Updates the given QContactRelationshipRemoveRequest req with the operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateRelationshipSaveRequest ( QContactRelationshipSaveRequest * req, const QList<QContactRelationship> & result, QContactManager::Error error, const QMap<int, QContactManager::Error> & errorMap, QContactAbstractRequest::State newState ) [static]

Updates the given QContactRelationshipSaveRequest req with the latest results result, operation error error, and map of input index to individual error errorMap. In addition, the state of the request will be changed to newState.

It then causes the request to emit its resultsAvailable() signal to notify clients of the request progress.

If the new request state is different from the previous state, the stateChanged() signal will also be emitted from the request.

This function was introduced in Qt Mobility 1.0.

void QContactManagerEngine::updateRequestState ( QContactAbstractRequest * req, QContactAbstractRequest::State state ) [static]

Updates the given asynchronous request req by setting the new state of the request. If the new state is different, the stateChanged() signal will be emitted by the request.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::validateContact ( const QContact & contact, QContactManager::Error * error ) const [virtual]

Checks that the given contact contact does not have details which don't conform to a valid definition, violate uniqueness constraints, or contain values for nonexistent fields, and that the values contained are of the correct type for each field, and are allowable values for that field.

Note that this function is unable to ensure that the access constraints (such as CreateOnly and ReadOnly) are observed; backend specific code must be written if you wish to enforce these constraints.

Returns true if the contact is valid according to the definitions for its details, otherwise returns false.

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::validateDefinition ( const QContactDetailDefinition & definition, QContactManager::Error * error ) const [virtual]

Checks that the given detail definition definition seems valid, with a correct id, defined fields, and any specified value types are supported by this engine. This function is called before trying to save a definition.

Returns true if the definition seems valid, otherwise returns false.

Any errors encountered during this operation should be stored to error.

This function was introduced in Qt Mobility 1.0.

bool QContactManagerEngine::waitForRequestFinished ( QContactAbstractRequest * req, int msecs ) [virtual]

Blocks until the manager engine has completed the given request req which was previously started, or until msecs milliseconds have passed. Returns true if the request was cancelled or completed, and false if the request was not in the QContactAbstractRequest::Active state or no progress could be reported.

This function was introduced in Qt Mobility 1.0.

See also startRequest().

X

Thank you for giving your feedback.

Make sure it is related to this specific page. For more general bugs and requests, please use the Qt Bug Tracker.