// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only


/*!

\page contactsasync.html

\title Qt Contacts Asynchronous API

\tableofcontents

    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 \l{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:
\list
  \li Manipulating contacts
  \li Manipulating relationships
\endlist

    \section1 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
\l{Qt Contacts Synchronous API}.

There are four different types of operation which are supported by the asynchronous API:
\list
  \li Fetch contact ids
  \li Fetch contacts
  \li Save contacts (create or update)
  \li Remove contacts
\endlist

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:
\list
  \li contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
  \li contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
  \li contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
  \li contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
  \li saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap)
  \li removeContacts(QList<QContactId>* contactIds, QMap<int, QContactManager::Error>* errorMap)
\endlist

\section1 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
\l{Qt Contacts Synchronous API}.
Support for relationships is backend specific.
There are three different types of operation which are supported by the asynchronous API:
\list
  \li Fetch relationships
  \li Save relationships (create or update, if supported by the backend)
  \li Remove relationships (if supported by the backend)
\endlist

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:
\list
  \li relationships(const QContactId& participantId, QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
  \li relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
  \li saveRelationship(QContactRelationship* relationship);
  \li saveRelationships(QList<QContactRelationship>* relationships);
  \li removeRelationship(const QContactRelationship& relationship);
  \li removeRelationships(const QList<QContactRelationship>& relationships);
\endlist

\section1 Examples of Usage

\section2 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.

    \snippet qtcontactsdocsample/qtcontactsdocsample.cpp Asynchronous contact request

\section2 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.

*/
