- Qt 5.0
- Qt Contacts Asynchronous API
- Qt 5.0.0 Reference Documentation

# Qt Contacts Asynchronous API

The Qt Contacts Asynchronous API enables a client to asynchronously fetch, update, or remove contact and relationship data from a contact manager. It offers mostly the same functionality as the Qt Contacts Synchronous API, but with greater flexibility when requesting information from remote datastores or slow local datastores. However, some information and reporting functionality, as well as the functions to set and retrieve the id of the self-contact are only provided through the synchronous API.

The Qt Contacts Asynchronous API is available through classes derived from the QContactAbstractRequest class. It has the following main use cases:

- Manipulating contacts
- Manipulating relationships

## Manipulating Contacts

The most common type of operation that clients will perform involves retrieval or modification of contacts. For in-depth information about contact manipulation, please refer to the Qt Contacts Synchronous API.

There are four different types of operation which are supported by the asynchronous API:

- Fetch contact ids
- Fetch contacts
- Save contacts (create or update)
- Remove contacts

These operations are supported via the QContactIdFetchRequest, QContactFetchRequest, QContactSaveRequest and QContactRemoveRequest classes, respectively.

The synchronous API offered by the QContactManager class to allow manipulation of contacts consists of the following functions:

- contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
- contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
- contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
- contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
- saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap)
- removeContacts(QList<QContactId>* contactIds, QMap<int, QContactManager::Error>* errorMap)

## Manipulating Relationships

Contacts may be related in various ways. The contacts API allows clients to define relationships between contacts. For in-depth information about relationship manipulation, please refer to the Qt Contacts Synchronous API. Support for relationships is backend specific. There are three different types of operation which are supported by the asynchronous API:

- Fetch relationships
- Save relationships (create or update, if supported by the backend)
- Remove relationships (if supported by the backend)

These operations are supported via the QContactRelationshipFetchRequest, QContactRelationshipSaveRequest and QContactRelationshipRemoveRequest classes respectively.

The synchronous API offered by the QContactManager class to allow manipulation of relationships consists of the following functions:

- relationships(const QContactId& participantId, QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
- relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
- saveRelationship(QContactRelationship* relationship);
- saveRelationships(QList<QContactRelationship>* relationships);
- removeRelationship(const QContactRelationship& relationship);
- removeRelationships(const QList<QContactRelationship>& relationships);

## Examples of Usage

### Fetching Contacts

The client sets up a request for contacts matching a specific criteria from a particular manager.

Results from the request will be displayed to the user as they are received.

     void RequestExample::performRequest()
     {
         // retrieve any contact whose first name is "Alice"
         QContactDetailFilter dfil;
         dfil.setDetailType(QContactName::Type, QContactName::FieldFirstName);
         dfil.setValue("Alice");
         dfil.setMatchFlags(QContactFilter::MatchExactly);

         // m_fetchRequest was created with m_fetchRequest = new QContactFetchRequest() in the ctor.
         m_fetchRequest->setManager(this->m_manager); // m_manager is a QContactManager*.
         m_fetchRequest->setFilter(dfil);
         connect(m_fetchRequest, SIGNAL(resultsAvailable()), this, SLOT(printContacts()));
         connect(m_fetchRequest, SIGNAL(stateChanged(QContactAbstractRequest::State)),
                 this, SLOT(stateChanged(QContactAbstractRequest::State)));
         if (!m_fetchRequest->start()) {
             qDebug() << "Unable to request contacts!";
             QCoreApplication::exit(0);
         } else {
             qDebug() << "Requested contacts; awaiting results...";
         }
     }

     void RequestExample::printContacts()
     {
         QList<QContact> results = m_fetchRequest->contacts();
         for (m_previousLastIndex = 0; m_previousLastIndex < results.size(); ++m_previousLastIndex) {
             qDebug() << "Found an Alice:" << results.at(m_previousLastIndex);
         }
     }

     void RequestExample::stateChanged(QContactAbstractRequest::State state)
     {
         // once we've finished retrieving results, stop processing events.
         if (state == QContactAbstractRequest::FinishedState
             || state == QContactAbstractRequest::CanceledState) {
             qDebug() << "Finished displaying asynchronously retrieved contacts!";
             QCoreApplication::exit(0);
         }
     }

### Other Asynchronous Operations

All other asynchronous operations are performed in a similar manner to the previous example. A request of the desired type (which is derived from QContactAbstractRequest) is created, certain criteria are set which determine the intent of the request, and the signals of the request are connected to slots which deals with the results. The request can then be started.