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
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** 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 organizerasync.html
\title Organizer Asynchronous API
\tableofcontents
\section1 Introduction
The Organizer Asynchronous API enables a client to asynchronously fetch,
update, or remove calendar, scheduling and personal data from an organizer
item 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 Organizer module is available through classes
derived from the QOrganizerAbstractRequest class. It consists of three major
categories:
\list
\o Organizer Item Manipulation
\o Item Collection Manipulation
\o Schema Manipulation
\endlist
\section2 Organizer Item Manipulation
The most common type of operation that clients will perform involves retrieval
or modification of organizer items. For in-depth information about item
manipulation, please refer to the main \l{Organizer} API page.
There are six different types of operation which are supported by the asynchronous API:
\list
\o Fetch item ids
\o Fetch persistent items (for export)
\o Fetch items (including generated occurrences) in a time period
\o Fetch the occurrences of a specific item
\o Save items (create or update)
\o Remove items
\endlist
These operations are supported via the classes:
\list
\o QOrganizerItemIdFetchRequest
\o QOrganizerItemFetchForExportRequest
\o QOrganizerItemFetchRequest
\o QOrganizerItemOccurrenceFetchRequest
\o QOrganizerItemSaveRequest
\o QOrganizerItemRemoveRequest
\endlist
\section2 Item Collection Manipulation
Every item is saved in a collection in a manager. Each collection has various
properties which, if the manager supports such operations, may be modified
by clients. For in-depth information about collections, please refer to the
main \l{Organizer} API page.
There are three different types of operation which are supported by the asynchronous API:
\list
\o Fetch collections (that is, the object which defines the properties of a collection)
\o Save collections (create or update)
\o Remove collections
\endlist
These operations are supported via the classes:
\list
\o QOrganizerCollectionFetchRequest
\o QOrganizerCollectionSaveRequest
\o QOrganizerCollectionRemoveRequest
\endlist
\section2 Schema Manipulation
The schema supported by a engine is the list of detail definitions which are
supported by the engine. For in-depth information about the schema, please
refer to the main \l{Qt Organizer Schema} page.
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 classes:
\list
\o QOrganizerItemDetailDefinitionFetchRequest
\o QOrganizerItemDetailDefinitionSaveRequest
\o QOrganizerItemDetailDefinitionRemoveRequest
\endlist
\section1 Usage
All asynchronous operations are performed in a similar pattern:
a request of the desired type (which is derived from
QOrganizerAbstractRequest) is created, certain criteria are set which
determine the intent of the request, QOrganizerAbstractRequest::stateChanged()
signal of the request is connected to a slot which deals with the results.
The request can then be started.
Note that if the client is interested in receiving the results of the request
as they become available, rather than only the final set of results once the
request changes state (to \c FinishedState, for example), the client should
instead connect the QOrganizerAbstractRequest::resultsAvailable() signal to the
slot which deals with the results.
\section2 Error Reporting
When a asynchronous operation fails, clients need to be able to retrieve error
information associated with that asynchronous operation. It is possible to
retrieve this error information by calling the
QOrganizerAbstractRequest::error() function on the corresponding request.
For some asynchronous operations (for example, batch save or remove operations)
it is possible that multiple errors may occur during the operation. In those
cases, clients can call the errorMap() function on the request object to
retrieve a map of input index to error. See, for instance,
QOrganizerItemSaveRequest::errorMap().
*/
|
