← Back to branch summary

~chris.gagnon/+junk/qtpim-coverage

« back to all changes in this revision

Viewing changes to src/contacts/doc/src/contactssync.qdoc

  • Committer: chris.gagnon
  • Date: 2013-12-10 23:09:37 UTC
  • Revision ID: chris.gagnon@canonical.com-20131210230937-2akf1ft1edcttk87
first post

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/contacts/doc/src/contactssync.qdoc
 
1
/****************************************************************************
 
2
**
 
3
** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
 
4
** Contact: http://www.qt-project.org/legal
 
5
**
 
6
** This file is part of the documentation of the Qt PIM Module.
 
7
**
 
8
** $QT_BEGIN_LICENSE:FDL$
 
9
** Commercial License Usage
 
10
** Licensees holding valid commercial Qt licenses may use this file in
 
11
** accordance with the commercial license agreement provided with the
 
12
** Software or, alternatively, in accordance with the terms contained in
 
13
** a written agreement between you and Digia.  For licensing terms and
 
14
** conditions see http://qt.digia.com/licensing.  For further information
 
15
** use the contact form at http://qt.digia.com/contact-us.
 
16
**
 
17
** GNU Free Documentation License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Free
 
19
** Documentation License version 1.3 as published by the Free Software
 
20
** Foundation and appearing in the file included in the packaging of
 
21
** this file.  Please review the following information to ensure
 
22
** the GNU Free Documentation License version 1.3 requirements
 
23
** will be met: http://www.gnu.org/copyleft/fdl.html.
 
24
** $QT_END_LICENSE$
 
25
**
 
26
****************************************************************************/
 
27
 
 
28
 
 
29
 
 
30
/*!
 
31
 
 
32
\page contactssync.html
 
33
 
 
34
\title Qt Contacts Synchronous API
 
35
 
 
36
\tableofcontents
 
37
 
 
38
    The Qt Contacts Synchronous API provides the simplest way to access or
 
39
    modify the contact information managed by a particular backend. It has the
 
40
    disadvantage that calls block until completion and is therefore most
 
41
    suitable only for applications which interact with local, high-speed
 
42
    datastores.
 
43
 
 
44
Most operations that may be performed using the synchronous API may also be
 
45
performed using the Qt Contacts Asynchronous API.  It is recommended for most
 
46
applications that the asynchronous API be used where possible.
 
47
 
 
48
The Qt Contacts Synchronous API is available through the QContactManager
 
49
class. It has the following main use cases:
 
50
\list
 
51
  \li Reporting Errors
 
52
  \li Manipulating Contacts
 
53
  \li Manipulating Relationships
 
54
\endlist
 
55
 
 
56
 
 
57
\section1 Reporting Errors
 
58
 
 
59
When a synchronous operation fails, clients need to be able to retrieve error information associated
 
60
with that synchronous operation.  The QContactManager::error() function provides this information to clients.
 
61
 
 
62
For some synchronous operations (for example, batch save or remove operations) it is possible that
 
63
multiple errors may occur during the operation.  In those cases, the synchronous function takes
 
64
a pointer to a map of input index to error, which is filled by the function as required.
 
65
The QContactManager::error() function then reports the overall operation error.
 
66
 
 
67
Error reporting is handled slightly differently in the asynchronous API, in that each instance of
 
68
an asynchronous request is able to report any overall operation error as well as the finer-grained
 
69
map of errors, for the operation which it requested.
 
70
 
 
71
 
 
72
\section1 Manipulating Contacts
 
73
 
 
74
The most common type of operation that clients perform involves retrieval or modification of contacts.
 
75
The QContactManager class offers synchronous API to retrieve, create, update and delete contacts.  The create
 
76
and update operations are provided through the same interface.  Both singular and batch operations are offered
 
77
by the API.
 
78
 
 
79
A contact is identified by its QContactId.  This id consists of two parts: a URI which identifies the contact manager
 
80
which stores the contact, and the local id of the contact in that manager.  Some operations which take a pointer
 
81
to a contact as an argument may modify the contact during the operation; updating the contact id is a common example.
 
82
 
 
83
The QContactManager class provides API for accessing the IDs of contacts which are stored in the manager:
 
84
\list
 
85
  \li contactIds(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
 
86
  \li contactIds(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>()) const
 
87
\endlist
 
88
 
 
89
The contact id retrieval functionality is also provided via asynchronous API through the QContactIdFetchRequest class.
 
90
 
 
91
The synchronous, singular contact manipulation functions offered by the QContactManager class are:
 
92
\list
 
93
  \li contact(const QContactId& contactId, const QContactFetchHint& fetchHint = QContactFetchHint()) const
 
94
  \li saveContact(QContact* contact)
 
95
  \li removeContact(const QContactId& contactId)
 
96
\endlist
 
97
 
 
98
The (optional) fetch argument to the contact accessor function allows clients to tell the plugin
 
99
which types of information they wish to retrieve.  This argument is a hint only, and may be ignored safely by the plugin,
 
100
or used by the plugin to optimize the performance of the retrieve operation.
 
101
 
 
102
The save operation entails a validation step, where the contact's details are checked against the supported schema.
 
103
If the contact is valid, it is saved.  Note that if the contact already exists in the database (determined by
 
104
the id of the contact) it is replaced with the contact contained in the argument.  This means that clients should
 
105
not save any contact which was retrieved with a non-empty fetchHint defined, or data loss may occur.
 
106
 
 
107
Any error which occurs during such singular contact manipulation functions may be accessed by calling QContactManager::error()
 
108
directly after the original synchronous call.
 
109
 
 
110
The synchronous, batch contact manipulation functions offered by the QContactManager class are:
 
111
\list
 
112
  \li contacts(const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
 
113
  \li contacts(const QContactFilter& filter, const QList<QContactSortOrder>& sortOrders = QList<QContactSortOrder>(), const QContactFetchHint& fetchHint = QContactFetchHint()) const
 
114
  \li saveContacts(QList<QContact>* contacts, QMap<int, QContactManager::Error>* errorMap)
 
115
  \li removeContacts(QList<QContactId>* contactIds, QMap<int, QContactManager::Error>* errorMap)
 
116
\endlist
 
117
 
 
118
The batch save and remove functions both take an (optional) pointer to a map of errors.  If the pointer is non-null,
 
119
this map is filled out with any errors which occur.  The overall operation error of any batch manipulation operation
 
120
may be accessed by calling QContactManager::error() directly after the original synchronous call.
 
121
 
 
122
The contact manipulation functionality is also provided via asynchronous API through the QContactFetchRequest,
 
123
QContactSaveRequest, and QContactRemoveRequest classes.
 
124
 
 
125
The \e self contact is a special concept, which has dedicated API.  A client may instruct any backend which supports the
 
126
concept of a self contact that a particular, previously saved contact is the self contact.  Any backend which implements
 
127
this functionality should report that it supports the QContactManager::SelfContact feature.
 
128
 
 
129
The API which provides the self-contact functionality consists of:
 
130
\list
 
131
  \li setSelfContactId(const QContactId& contactId)
 
132
  \li selfContactId() const
 
133
\endlist
 
134
 
 
135
In order to unset the self contact, a client may either delete the contact which is currently set as the self contact,
 
136
or set the self contact id to be null id (constructed via QContactId()).
 
137
The self-contact manipulation functionality is only available via the synchronous API.
 
138
 
 
139
 
 
140
\section2 Adding Contacts
 
141
 
 
142
The client creates a new contact, adds a name and a phone number, and
 
143
saves it to the default store of the default manager.
 
144
 
 
145
We assume the existence of a specialized leaf-class that allows simple
 
146
access to details of the definition identified by the "PhoneNumber"
 
147
identifier, and another that allows simple access to details of the
 
148
definition identified by the "Name" identifier.  These specialized leaf
 
149
classes may be written by anyone, and simply wrap the functionality
 
150
provided by QContactDetail in order to allow simpler access to fields
 
151
supported by a particular definition.
 
152
 
 
153
    \snippet qtcontactsdocsample/qtcontactsdocsample.cpp Creating a new contact
 
154
 
 
155
\section2 Filtering by Detail Definition and Value
 
156
 
 
157
The client utilizes a default manager and asks for any contacts with a
 
158
particular phone number.  The example assumes that the default manager
 
159
supports the provided QContactPhoneNumber detail leaf class (which
 
160
implements the default definition for phone number details).
 
161
 
 
162
    \snippet qtcontactsdocsample/qtcontactsdocsample.cpp Filtering by definition and value
 
163
 
 
164
 
 
165
\section2 Modifying Contact Details
 
166
 
 
167
The client retrieves a contact, modifies one of its details, adds a new
 
168
detail, and then saves the contact back to the manager.
 
169
 
 
170
    \snippet qtcontactsdocsample/qtcontactsdocsample.cpp Modifying an existing contact
 
171
 
 
172
\section1 Manipulating Relationships
 
173
 
 
174
Contacts may be related in various ways.  The contacts API allows clients to define relationships between contacts
 
175
if the plugin providing the functionality supports such relationships.
 
176
Some plugins support arbitrary relationship types.  Clients can define custom relationships between contacts saved
 
177
in such plugins.
 
178
 
 
179
The API which provides the relationship manipulation functionality consists of:
 
180
\list
 
181
  \li relationships(const QContactId& participantId, QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
 
182
  \li relationships(const QString& relationshipType = QString(), const QContactId& participantId = QContactId(), QContactRelationshipFilter::Role role = QContactRelationshipFilter::Either) const;
 
183
  \li saveRelationship(QContactRelationship* relationship);
 
184
  \li saveRelationships(QList<QContactRelationship>* relationships);
 
185
  \li removeRelationship(const QContactRelationship& relationship);
 
186
  \li removeRelationships(const QList<QContactRelationship>& relationships);
 
187
\endlist
 
188
 
 
189
The relationship manipulation functionality is also provided via asynchronous API through the QContactRelationshipFetchRequest,
 
190
QContactRelationshipSaveRequest, and QContactRelationshipRemoveRequest classes.
 
191
 
 
192
*/
 
193