← Back to branch summary

~chris.gagnon/+junk/qtpim-coverage

« back to all changes in this revision

Viewing changes to src/organizer/doc/src/organizeradvanced.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/organizer/doc/src/organizeradvanced.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
 
 
33
\page organizeradvanced.html
 
34
 
 
35
\title Qt Organizer API Advanced Usage
 
36
\section1 Introduction
 
37
 
 
38
This section provides some detailed information on more advanced topics
 
39
regarding the Qt Organizer API.
 
40
 
 
41
\section2 The Detail Model
 
42
 
 
43
While QOrganizerItem and its subclasses provide methods for data access and
 
44
manipulation which should be sufficient for most purposes, it is actually a
 
45
generic container that can hold arbitrary data in the form of \e details. In fact,
 
46
functions for manipulating items, such as QOrganizerItem::displayLabel() or
 
47
QOrganizerEvent::setRecurrenceRule() are merely convenience functions that
 
48
perform operations on the underlying details of an item. A QOrganizerItem
 
49
consists of nothing more than the details it contains, as well as an id and the
 
50
id of its collection.
 
51
 
 
52
A QOrganizerItemDetail is a single, cohesive unit of information that is stored
 
53
in an item. A detail may have specific meta-data associated with it, as well as
 
54
access constraints which may apply to the detail (e.g., read-only, irremovable,
 
55
etc).
 
56
 
 
57
A list of all standard details defined by this API are listed
 
58
\l{QOrganizerItemDetail Leaf Classes}{here}.
 
59
 
 
60
Some details are read-only (such as the modification timestamp of an item) or
 
61
irremovable (like the type of an item), but most are freely modifiable by
 
62
clients. The QOrganizerItem::details(), QOrganizerItem::detail(),
 
63
QOrganizerItem::saveDetail() and QOrganizerItem::removeDetail() functions can be
 
64
used to manipulate these details.
 
65
 
 
66
It is important to note that details are implicitly shared objects with
 
67
particular semantics surrounding saving, removal and modification.
 
68
 
 
69
\section2 Optimizing Item Retrieval
 
70
 
 
71
Clients can inform the manager that they do not require certain details from an
 
72
item, which can allow a manager to optimize item retrieval. In this way, the
 
73
client can inform the manager that they are not interested in any binary blob
 
74
data (e.g., images) in retrieved items. These restrictions can be specified by
 
75
providing a QOrganizerItemFetchHint as an argument to the retrieval operation.
 
76
 
 
77
Note that if the item already exists in the database, it will be completely
 
78
replaced. This means that clients should not save any item which was retrieved
 
79
with a non-empty fetchHint defined, or data loss may occur.
 
80
 
 
81
\section1 The Organizer Manager and Manager Engines
 
82
\section2 The Organizer Manager
 
83
 
 
84
Access to organizer items is provided by implementations of the Qt Organizer
 
85
\l{QOrganizerManager}{manager} API. Each manager may support different
 
86
capabilities (for example, the ability to store certain datatypes, the ability
 
87
to natively filter on different details or details of different definitions, the
 
88
provision of locking mechanisms, the provision of changelog information, etc)
 
89
which are reported by the manager on request. The manager therefore provides
 
90
access to detail definitions and collections of organizer items stored in
 
91
different datastores, in a platform and datastore independent manner.
 
92
 
 
93
The QOrganizerManager is in fact a client-facing interface through to a
 
94
platform-specific manager engine (which is implemented as a Qt plugin). While
 
95
clients never interact directly with the manager engine, they may need to be
 
96
aware of limitations of individual engines, or differences between engines. The
 
97
API offered through QOrganizerManager allows clients to retrieve this
 
98
information for the engine which provides the functionality exposed through a
 
99
particular QOrganizerManager.
 
100
 
 
101
\section2 Storage Considerations
 
102
 
 
103
A QOrganizerManagerEngine may provide an aggregated view of multiple physical
 
104
datastores, some of which may be remote datastores. Clients of the API are aware
 
105
only that the data is managed by a QOrganizerManagerEngine with a particular
 
106
URI. It is possible that multiple different engines will have overlap in the
 
107
datastores which they aggregate, and in that case the way in which those engines
 
108
were implemented will determine whether operations are thread-safe or not.
 
109
 
 
110
Since the data may physically be stored in a remote datastore, any operations
 
111
may be dominated by the return-trip-time of communications with the remote
 
112
datastore. As such, \b{it is recommended that clients use the asynchronous
 
113
client API to access organizer information from any QOrganizerManager.}
 
114
 
 
115
\section2 Provided Engines
 
116
 
 
117
The Qt Organizer module includes several backends already, some of which are
 
118
designed to interface with the default calendar on their particular platform.
 
119
 
 
120
\section3 In-Memory Example Engine
 
121
 
 
122
The in-memory engine identifies itself as the \c memory engine.
 
123
 
 
124
The in-memory engine supports the default schema, and provides almost all
 
125
functionality available through the Qt Organizer API; however, all data
 
126
is stored in-memory and is not persisted in any way.
 
127
 
 
128
\section1 Manager Settings and Configuration
 
129
 
 
130
Users of the items API can define which backend they wish to access if a manager
 
131
for that backend is available. The list of available managers can be queried
 
132
programmatically at run-time, and the capabilities of different managers can be
 
133
ascertained by inspecting a QOrganizerManager instance. Furthermore, some
 
134
managers can be constructed with parameters which affect the operation of the
 
135
backend.
 
136
 
 
137
\section2 Querying a Manager for Capabilities
 
138
 
 
139
Different managers will support different capabilities and details. Clients can
 
140
use the meta data reporting functions of QOrganizerManager to determine what the
 
141
capabilities of the manager they have instantiated might be.
 
142
 
 
143
\section2 Loading the Manager for a Specific Backend
 
144
 
 
145
The client can choose to load a manager for a specific backend. While the engine
 
146
could be found and retrieved using a more advanced plugin framework (such as the
 
147
Qt Service Framework), this code assumes that the client has prior knowledge of
 
148
the backend in question:
 
149
 
 
150
\code
 
151
     QOrganizerManager specificManager("memory");
 
152
\endcode
 
153
 
 
154
Clients may wish to use this feature of the API if they wish to store or
 
155
retrieve item information to a particular manager (for example, one that
 
156
interfaces with a particular online service).
 
157
 
 
158
\section2 Loading a Manager with Specific Parameters
 
159
 
 
160
The client can load a manager with specific parameters defined. The parameters
 
161
which are available are backend specific, and so the client has to know which
 
162
parameters are valid for a particular backend, and what argument it takes.
 
163
 
 
164
\section2 Meta Data API
 
165
 
 
166
The QOrganizerManager class provides a static function
 
167
QOrganizerManager::availableManagers() which allows clients of the API to
 
168
determine (at run time) which plugins (managers) are available for use.
 
169
 
 
170
Clients of the API also need to be able to determine (at run time) what the
 
171
capabilities of a given plugin (organizer item manager) are. The
 
172
QOrganizerManager class provides API to query the capabilities of a given
 
173
manager with the following synchronous functions:
 
174
 
 
175
\list
 
176
\li \l{QOrganizerManager::supportedFilters()}{supportedFilters()}
 
177
\li \l{QOrganizerManager::supportedItemDetails()}{supportedItemDetails()}
 
178
\li \l{QOrganizerManager::supportedItemTypes()}{supportedItemTypes()}
 
179
\endlist
 
180
 
 
181
A given manager is identified by its URI. The URI consists of the manager's
 
182
name, any relevant parameters which were used during instantiation of the
 
183
manager, and the version of the manager. While the name of the manager
 
184
identifies the plugin which provides the functionality, you cannot guarantee
 
185
that the data available through one manager will be available through another
 
186
with the same name (for example, if one parameter tells the plugin to store and
 
187
retrieve organizer information from a particular online service or local file).
 
188
 
 
189
The synchronous API offered to allow run-time querying of a manager's metadata
 
190
includes:
 
191
 
 
192
\list
 
193
\li \l{QOrganizerManager::managerName()}{managerName}
 
194
\li \l{QOrganizerManager::managerParameters()}{managerParameters}
 
195
\li \l{QOrganizerManager::managerUri()}{managerUri}
 
196
\li \l{QOrganizerManager::parseUri()}{parseUri}
 
197
\li \l{QOrganizerManager::buildUri()}{buildUri}
 
198
\endlist
 
199
 
 
200
The functionality that the above functions provide is only available through
 
201
synchronous API.
 
202
 
 
203
*/