1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
/****************************************************************************
**
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** GNU Free Documentation License
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.
**
** Other Usage
** Alternatively, this file may be used in accordance with the terms
** and conditions contained in a signed written agreement between you
** and Nokia.
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page contactsasync.html
\title Contacts Asynchronous API
\tableofcontents
\section1 Introduction
The Contacts Asynchronous API enables a client to asynchronously fetch, update, or remove
contact, relationship or schema data from a contact manager. Use of the asynchronous API
offers the programmer greater flexibility when requesting information from remote or
slow local datastores.
\section1 Using the API
The asynchronous API offered by the Contacts module is available through classes
derived from the QContactAbstractRequest class. It consists of three major sections:
\list
\o Contact Manipulation
\o Relationship Manipulation
\o Schema Manipulation
\endlist
The functionality offered by the synchronous API in these three categories is also
available through the asynchronous API. There is one category of functionality
which is not provided by the asynchronous API which is provided by the synchronous
API: some information and reporting functionality is only provided through the
synchronous API.
For detailed information about the information and reporting functionality provided,
please refer to the documentation for the \l{Contacts Synchronous API}.
The functions to set and retrieve the id of the self-contact are also only provided by
the synchronous API.
\section2 Contact Manipulation
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{Contacts Synchronous API}.
There are four different types of operation which are supported by the asynchronous API:
\list
\o Fetch contact ids
\o Fetch contacts
\o Save contacts (create or update)
\o Remove contacts
\endlist
These operations are supported via the QContactLocalIdFetchRequest, 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
\o contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
\o contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
\o contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
\o contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
\o saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap)
\o removeContacts(QList<QContactLocalId>* contactIds, QMap<int, QContactManager::Error>* errorMap)
\endlist
\section3 Relationship Manipulation
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{Contacts Synchronous API}.
There are three different types of operation which are supported by the asynchronous API:
\list
\o Fetch relationships
\o Save relationships (create or update, if supported by the backend)
\o 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
\o relationships(const QContactId& participantId, QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
\o relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
\o saveRelationship(QContactRelationship* relationship);
\o saveRelationships(QList<QContactRelationship>* relationships);
\o removeRelationship(const QContactRelationship& relationship);
\o removeRelationships(const QList<QContactRelationship>& relationships);
\endlist
\section2 Schema Manipulation
The schema supported by a plugin is the list of detail definitions which are supported by the plugin.
For in-depth information about the schema, please refer to the \l{Contacts Synchronous API}.
There are three different types of operation which are supported by the asynchronous API:
\list
\o Fetch detail definitions
\o Save detail definitions (create or update, if supported by the backend)
\o Remove detail definitions (if supported by the backend)
\endlist
These operations are supported via the the QContactDetailDefinitionFetchRequest,
QContactDetailDefinitionSaveRequest and QContactDetailDefinitionRemoveRequest classes,
respectively.
The synchronous API offered by the QContactManager class to allow manipulation of the schema consists
of the following functions:
\list
\o detailDefinitions(const QString& contactType = QContactType::TypeContact) const
\o detailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact) const
\o saveDetailDefinition(const QContactDetailDefinition& def, const QString& contactType = QContactType::TypeContact)
\o removeDetailDefinition(const QString& definitionName, const QString& contactType = QContactType::TypeContact)
\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 snippets/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.
*/
|
