1
/****************************************************************************
3
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4
** All rights reserved.
5
** OrganizerItem: Nokia Corporation (qt-info@nokia.com)
7
** This file is part of the Qt Mobility Components.
9
** $QT_BEGIN_LICENSE:LGPL$
11
** Licensees holding valid Qt Commercial licenses may use this file in
12
** accordance with the Qt Solutions Commercial License Agreement provided
13
** with the Software or, alternatively, in accordance with the terms
14
** contained in a written agreement between you and Nokia.
16
** GNU Lesser General Public License Usage
17
** Alternatively, this file may be used under the terms of the GNU Lesser
18
** General Public License version 2.1 as published by the Free Software
19
** Foundation and appearing in the file LICENSE.LGPL included in the
20
** packaging of this file. Please review the following information to
21
** ensure the GNU Lesser General Public License version 2.1 requirements
22
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24
** In addition, as a special exception, Nokia gives you certain additional
25
** rights. These rights are described in the Nokia Qt LGPL Exception
26
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28
** GNU General Public License Usage
29
** Alternatively, this file may be used under the terms of the GNU
30
** General Public License version 3.0 as published by the Free Software
31
** Foundation and appearing in the file LICENSE.GPL included in the
32
** packaging of this file. Please review the following information to
33
** ensure the GNU General Public License version 3.0 requirements will be
34
** met: http://www.gnu.org/copyleft/gpl.html.
36
** Please note Third Party Software included with Qt Solutions may impose
37
** additional restrictions and it is the user's responsibility to ensure
38
** that they have met the licensing requirements of the GPL, LGPL, or Qt
39
** Solutions Commercial license and the relevant license of the Third
40
** Party Software they are using.
42
** If you are unsure which license is appropriate for your use, please
43
** contact the sales department at qt-sales@nokia.com.
46
****************************************************************************/
48
#include "qorganizeritemmanager.h"
50
#include "qorganizeritem_p.h"
51
#include "qorganizeritemfilter.h"
52
#include "qorganizeritemdetaildefinition.h"
53
#include "qorganizeritemmanager_p.h"
54
#include "qorganizeritemfetchhint.h"
56
#include <QSharedData>
63
\class QOrganizerItemManager
64
\brief The QOrganizerItemManager class provides an interface which allows clients with access to organizer item information stored in a particular backend.
67
\ingroup organizer-main
69
This class provides an abstraction of a datastore or aggregation of datastores which contains organizer item information.
70
It provides methods to retrieve and manipulate organizer item information and supported schema definitions.
71
It also provides metadata and error information reporting.
73
The functions provided by QOrganizerItemManager are purely synchronous; to access the same functionality in an
74
asynchronous manner, clients should use the use-case-specific classes derived from QOrganizerItemAbstractRequest.
76
Some functionality provided by QOrganizerItemManager directly is not accessible using the asynchronous API; see
77
the \l{Organizer Synchronous API}{synchronous} and \l{Organizer Asynchronous API}{asynchronous} API
78
information from the \l{Organizer}{organizer module} API documentation.
82
\fn QOrganizerItemManager::dataChanged()
83
This signal is emitted by the manager if its internal state changes, and it is unable to determine the changes
84
which occurred, or if the manager considers the changes to be radical enough to require clients to reload all data.
85
If this signal is emitted, no other signals will be emitted for the associated changes.
89
\fn QOrganizerItemManager::itemsAdded(const QList<QOrganizerItemLocalId>& organizeritemIds)
90
This signal is emitted at some point once the organizeritems identified by \a organizeritemIds have been added to a datastore managed by this manager.
91
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
95
\fn QOrganizerItemManager::itemsChanged(const QList<QOrganizerItemLocalId>& organizeritemIds)
96
This signal is emitted at some point once the organizeritems identified by \a organizeritemIds have been modified in a datastore managed by this manager.
97
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
101
\fn QOrganizerItemManager::itemsRemoved(const QList<QOrganizerItemLocalId>& organizeritemIds)
102
This signal is emitted at some point once the organizeritems identified by \a organizeritemIds have been removed from a datastore managed by this manager.
103
This signal must not be emitted if the dataChanged() signal was previously emitted for these changes.
108
#define makestr(x) (#x)
109
#define makename(x) makestr(x)
112
Returns a list of available manager ids that can be used when constructing
113
a QOrganizerItemManager. If an empty id is specified to the constructor, the
114
first value in this list will be used instead.
116
QStringList QOrganizerItemManager::availableManagers()
119
ret << QLatin1String("memory") << QLatin1String("invalid");
120
QOrganizerItemManagerData::loadFactories();
121
ret.append(QOrganizerItemManagerData::m_engines.keys());
123
// now swizzle the default engine to pole position
124
#if defined(Q_ORGANIZER_DEFAULT_ENGINE)
125
if (ret.removeAll(QLatin1String(makename(Q_ORGANIZER_DEFAULT_ENGINE)))) {
126
ret.prepend(QLatin1String(makename(Q_ORGANIZER_DEFAULT_ENGINE)));
134
Splits the given \a uri into the manager, store, and parameters that it describes, and places the information into the memory addressed by \a pManagerId and \a pParams respectively. Returns true if \a uri could be split successfully, otherwise returns false
136
bool QOrganizerItemManager::parseUri(const QString& uri, QString* pManagerId, QMap<QString, QString>* pParams)
138
// Format: qtorganizer:<managerid>:<key>=<value>&<key>=<value>
139
// 1) parameters are currently a qstringlist.. should they be a map?
140
// 2) is the uri going to be escaped? my guess would be "probably not"
141
// 3) hence, do we assume that the prefix, managerid and storeid cannot contain `:'
142
// 4) similarly, that neither keys nor values can contain `=' or `&'
144
QStringList colonSplit = uri.split(QLatin1Char(':'));
145
QString prefix = colonSplit.value(0);
147
if (prefix != QLatin1String("qtorganizer"))
150
QString managerName = colonSplit.value(1);
152
if (managerName.trimmed().isEmpty())
155
QString firstParts = prefix + QLatin1Char(':') + managerName + QLatin1Char(':');
156
QString paramString = uri.mid(firstParts.length());
158
QMap<QString, QString> outParams;
160
// Now we have to decode each parameter
161
if (!paramString.isEmpty()) {
162
QStringList params = paramString.split(QRegExp(QLatin1String("&(?!(amp;|equ;))")), QString::KeepEmptyParts);
163
// If we have an empty string for paramstring, we get one entry in params,
164
// so skip that case.
165
for(int i = 0; i < params.count(); i++) {
166
/* This should be something like "foo&bar&equ;=grob&" */
167
QStringList paramChunk = params.value(i).split(QLatin1String("="), QString::KeepEmptyParts);
169
if (paramChunk.count() != 2)
172
QString arg = paramChunk.value(0);
173
QString param = paramChunk.value(1);
174
arg.replace(QLatin1String("&equ;"), QLatin1String("="));
175
arg.replace(QLatin1String("&"), QLatin1String("&"));
176
param.replace(QLatin1String("&equ;"), QLatin1String("="));
177
param.replace(QLatin1String("&"), QLatin1String("&"));
180
outParams.insert(arg, param);
185
*pParams = outParams;
187
*pManagerId = managerName;
191
/*! Returns a URI that completely describes a manager implementation, datastore, and the parameters with which to instantiate the manager, from the given \a managerName, \a params and an optional \a implementationVersion */
192
QString QOrganizerItemManager::buildUri(const QString& managerName, const QMap<QString, QString>& params, int implementationVersion)
194
QString ret(QLatin1String("qtorganizer:%1:%2"));
195
// we have to escape each param
196
QStringList escapedParams;
197
QStringList keys = params.keys();
198
for (int i=0; i < keys.size(); i++) {
199
QString key = keys.at(i);
200
QString arg = params.value(key);
201
arg = arg.replace(QLatin1Char('&'), QLatin1String("&"));
202
arg = arg.replace(QLatin1Char('='), QLatin1String("&equ;"));
203
key = key.replace(QLatin1Char('&'), QLatin1String("&"));
204
key = key.replace(QLatin1Char('='), QLatin1String("&equ;"));
205
key = key + QLatin1Char('=') + arg;
206
escapedParams.append(key);
209
if (implementationVersion != -1) {
210
QString versionString = QString(QLatin1String(QTORGANIZER_IMPLEMENTATION_VERSION_NAME));
211
versionString += QString::fromAscii("=");
212
versionString += QString::number(implementationVersion);
213
escapedParams.append(versionString);
216
return ret.arg(managerName, escapedParams.join(QLatin1String("&")));
220
Constructs a QOrganizerItemManager whose implementation, store and parameters are specified in the given \a storeUri,
221
and whose parent object is \a parent.
223
QOrganizerItemManager* QOrganizerItemManager::fromUri(const QString& storeUri, QObject* parent)
225
if (storeUri.isEmpty()) {
226
return new QOrganizerItemManager(QString(), QMap<QString, QString>(), parent);
229
QMap<QString, QString> parameters;
230
if (parseUri(storeUri, &id, ¶meters)) {
231
return new QOrganizerItemManager(id, parameters, parent);
234
return new QOrganizerItemManager(QLatin1String("invalid"), QMap<QString, QString>(), parent);
240
Constructs a QOrganizerItemManager whose parent QObject is \a parent.
241
The default implementation for the platform will be created.
243
QOrganizerItemManager::QOrganizerItemManager(QObject* parent)
246
createEngine(QString(), QMap<QString, QString>());
250
Constructs a QOrganizerItemManager whose implementation is identified by \a managerName with the given \a parameters.
252
The \a parent QObject will be used as the parent of this QOrganizerItemManager.
254
If an empty \a managerName is specified, the default implementation for the platform will
257
QOrganizerItemManager::QOrganizerItemManager(const QString& managerName, const QMap<QString, QString>& parameters, QObject* parent)
259
d(new QOrganizerItemManagerData)
261
createEngine(managerName, parameters);
264
void QOrganizerItemManager::createEngine(const QString& managerName, const QMap<QString, QString>& parameters)
266
d->createEngine(managerName, parameters);
267
connect(d->m_engine, SIGNAL(dataChanged()), this, SIGNAL(dataChanged()));
268
connect(d->m_engine, SIGNAL(itemsAdded(QList<QOrganizerItemLocalId>)), this, SIGNAL(itemsAdded(QList<QOrganizerItemLocalId>)));
269
connect(d->m_engine, SIGNAL(itemsChanged(QList<QOrganizerItemLocalId>)), this, SIGNAL(itemsChanged(QList<QOrganizerItemLocalId>)));
270
connect(d->m_engine, SIGNAL(itemsRemoved(QList<QOrganizerItemLocalId>)), this, SIGNAL(itemsRemoved(QList<QOrganizerItemLocalId>)));
271
connect(d->m_engine, SIGNAL(collectionsAdded(QList<QOrganizerCollectionLocalId>)), this, SIGNAL(collectionsAdded(QList<QOrganizerCollectionLocalId>)));
272
connect(d->m_engine, SIGNAL(collectionsChanged(QList<QOrganizerCollectionLocalId>)), this, SIGNAL(collectionsChanged(QList<QOrganizerCollectionLocalId>)));
273
connect(d->m_engine, SIGNAL(collectionsRemoved(QList<QOrganizerCollectionLocalId>)), this, SIGNAL(collectionsRemoved(QList<QOrganizerCollectionLocalId>)));
277
Constructs a QOrganizerItemManager whose backend has the name \a managerName and version \a implementationVersion, where the manager
278
is constructed with the provided \a parameters.
280
The \a parent QObject will be used as the parent of this QOrganizerItemManager.
282
If an empty \a managerName is specified, the default implementation for the platform will be instantiated.
283
If the specified implementation version is not available, the manager with the name \a managerName with the default implementation version is instantiated.
285
QOrganizerItemManager::QOrganizerItemManager(const QString& managerName, int implementationVersion, const QMap<QString, QString>& parameters, QObject* parent)
287
d(new QOrganizerItemManagerData)
289
QMap<QString, QString> params = parameters;
290
params[QString(QLatin1String(QTORGANIZER_IMPLEMENTATION_VERSION_NAME))] = QString::number(implementationVersion);
291
createEngine(managerName, params);
294
/*! Frees the memory used by the QOrganizerItemManager */
295
QOrganizerItemManager::~QOrganizerItemManager()
301
\enum QOrganizerItemManager::Error
303
This enum specifies an error that occurred during the most recent operation:
305
\value NoError The most recent operation was successful
306
\value DoesNotExistError The most recent operation failed because the requested organizer item or detail definition does not exist
307
\value AlreadyExistsError The most recent operation failed because the specified organizer item or detail definition already exists
308
\value InvalidDetailError The most recent operation failed because the specified organizer item contains details which do not conform to their definition
309
\value InvalidItemTypeError The most recent operation failed because the organizer item type specified was not valid for the operation
310
\value LockedError The most recent operation failed because the datastore specified is currently locked
311
\value DetailAccessError The most recent operation failed because a detail was modified or removed and its access method does not allow that
312
\value PermissionsError The most recent operation failed because the caller does not have permission to perform the operation
313
\value OutOfMemoryError The most recent operation failed due to running out of memory
314
\value VersionMismatchError The most recent operation failed because the backend of the manager is not of the required version
315
\value LimitReachedError The most recent operation failed because the limit for that type of object has been reached
316
\value NotSupportedError The most recent operation failed because the requested operation is not supported in the specified store
317
\value BadArgumentError The most recent operation failed because one or more of the parameters to the operation were invalid
318
\value UnspecifiedError The most recent operation failed for an undocumented reason
319
\value InvalidOccurrenceError The most recent operation failed because it was an attempt to save an occurrence without a correct InstanceOrigin detail
322
/*! Return the error code of the most recent operation */
323
QOrganizerItemManager::Error QOrganizerItemManager::error() const
329
Return the list of organizer item instances which match the given \a filter, sorted according to the given \a sortOrders.
330
The client may instruct the manager that it does not require all possible information about each instance by specifying a fetch hint \a fetchHint;
331
the manager can choose to ignore the fetch hint, but if it does so, it must return all possible information about each instance.
333
QList<QOrganizerItem> QOrganizerItemManager::itemInstances(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders, const QOrganizerItemFetchHint& fetchHint) const
335
d->m_error = QOrganizerItemManager::NoError;
336
return d->m_engine->itemInstances(filter, sortOrders, fetchHint, &d->m_error);
340
Return the list of a maximum of \a maxCount organizer item instances which are occurrences of the given \a generator recurring item, which
341
occur between the given \a periodStart date and the given \a periodEnd date.
343
If \a periodStart is after \a periodEnd, the operation will fail.
344
If \a maxCount is negative, it is backend specific as to how many occurrences will be returned.
345
Some backends may return no instances, others may return some limited number of occurrences.
347
QList<QOrganizerItem> QOrganizerItemManager::itemInstances(const QOrganizerItem& generator, const QDateTime& periodStart, const QDateTime& periodEnd, int maxCount) const
349
d->m_error = QOrganizerItemManager::NoError;
350
return d->m_engine->itemInstances(generator, periodStart, periodEnd, maxCount, &d->m_error);
355
Return the list of organizer item ids, sorted according to the given list of \a sortOrders
357
QList<QOrganizerItemLocalId> QOrganizerItemManager::itemIds(const QList<QOrganizerItemSortOrder>& sortOrders) const
359
d->m_error = QOrganizerItemManager::NoError;
360
return d->m_engine->itemIds(QOrganizerItemFilter(), sortOrders, &d->m_error);
364
Returns a list of organizer item ids that match the given \a filter, sorted according to the given list of \a sortOrders.
365
Depending on the backend, this filtering operation may involve retrieving all the organizeritems.
367
QList<QOrganizerItemLocalId> QOrganizerItemManager::itemIds(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders) const
369
d->m_error = QOrganizerItemManager::NoError;
370
return d->m_engine->itemIds(filter, sortOrders, &d->m_error);
374
Returns the list of organizeritems stored in the manager sorted according to the given list of \a sortOrders.
376
The \a fetchHint parameter describes the optimization hints that a manager may take.
377
If the \a fetchHint is the default constructed hint, all existing details and relationships
378
in the matching organizeritems will be returned. A client should not make changes to an organizer item which has
379
been retrieved using a fetch hint other than the default fetch hint. Doing so will result in information
380
loss when saving the organizer item back to the manager (as the "new" restricted organizer item will
381
replace the previously saved organizer item in the backend).
383
\sa QOrganizerItemFetchHint
385
QList<QOrganizerItem> QOrganizerItemManager::items(const QList<QOrganizerItemSortOrder>& sortOrders, const QOrganizerItemFetchHint& fetchHint) const
387
d->m_error = QOrganizerItemManager::NoError;
388
return d->m_engine->items(QOrganizerItemFilter(), sortOrders, fetchHint, &d->m_error);
392
Returns a list of organizeritems that match the given \a filter, sorted according to the given list of \a sortOrders.
394
Depending on the manager implementation, this filtering operation might be slow and involve retrieving all the
395
organizeritems and testing them against the supplied filter - see the \l isFilterSupported() function.
397
The \a fetchHint parameter describes the optimization hints that a manager may take.
398
If the \a fetchHint is the default constructed hint, all existing details and relationships
399
in the matching organizeritems will be returned. A client should not make changes to an organizer item which has
400
been retrieved using a fetch hint other than the default fetch hint. Doing so will result in information
401
loss when saving the organizer item back to the manager (as the "new" restricted organizer item will
402
replace the previously saved organizer item in the backend).
404
\sa QOrganizerItemFetchHint
406
QList<QOrganizerItem> QOrganizerItemManager::items(const QOrganizerItemFilter& filter, const QList<QOrganizerItemSortOrder>& sortOrders, const QOrganizerItemFetchHint& fetchHint) const
408
d->m_error = QOrganizerItemManager::NoError;
409
return d->m_engine->items(filter, sortOrders, fetchHint, &d->m_error);
413
Returns the organizer item in the database identified by \a organizeritemId.
415
If the organizer item does not exist, an empty, default constructed QOrganizerItem will be returned,
416
and the error returned by \l error() will be \c QOrganizerItemManager::DoesNotExistError.
418
The \a fetchHint parameter describes the optimization hints that a manager may take.
419
If the \a fetchHint is the default constructed hint, all existing details and relationships
420
in the matching organizer item will be returned. A client should not make changes to an organizer item which has
421
been retrieved using a fetch hint other than the default fetch hint. Doing so will result in information
422
loss when saving the organizer item back to the manager (as the "new" restricted organizer item will
423
replace the previously saved organizer item in the backend).
425
\sa QOrganizerItemFetchHint
427
QOrganizerItem QOrganizerItemManager::item(const QOrganizerItemLocalId& organizeritemId, const QOrganizerItemFetchHint& fetchHint) const
429
d->m_error = QOrganizerItemManager::NoError;
430
return d->m_engine->item(organizeritemId, fetchHint, &d->m_error);
434
Adds the given \a organizeritem to the database if \a organizeritem has a
435
default-constructed id, or an id with the manager URI set to the URI of
436
this manager and a local id of zero. It will be saved in the collection specified
437
by \a collectionId if the specified collection exists, or if no \a collectionId is
438
specified, or the \a collectionId is the default (zero) collection id, it will be
439
saved in the collection in which the item is currently saved (if it is not a new
440
item) or in the default collection (if it is a new item).
442
Each collection may have a different schema, so if the item cannot be saved
443
in the given collection due to invalid details, the function will return false.
444
An item which is valid in one collection may be invalid in another collection, in the
447
If the manager URI of the id of the \a organizeritem is neither empty nor equal to the URI of
448
this manager, or local id of the \a organizeritem is non-zero but does not exist in the
449
manager, the operation will fail and calling error() will return
450
\c QOrganizerItemManager::DoesNotExistError.
452
Alternatively, the function will update the existing organizer item in the database if \a organizeritem
453
has a non-zero id and currently exists in the database.
455
If the \a organizeritem contains one or more details whose definitions have
456
not yet been saved with the manager, the operation will fail and calling
457
error() will return \c QOrganizerItemManager::UnsupportedError.
459
Returns false on failure, or true on
460
success. On successful save of an organizer item with an id of zero, its
461
id will be set to a new, valid id with the manager URI set to the URI of
462
this manager, and the local id set to a new, valid local id.
463
The manager will automatically synthesize the display label of the organizer item when it is saved.
464
The manager is not required to fetch updated details of the organizer item on save,
465
and as such, clients should fetch an organizer item if they want the most up-to-date information
466
by calling \l QOrganizerItemManager::item().
470
bool QOrganizerItemManager::saveItem(QOrganizerItem* organizeritem, const QOrganizerCollectionLocalId& collectionId)
473
d->m_error = QOrganizerItemManager::NoError;
474
return d->m_engine->saveItem(organizeritem, collectionId, &d->m_error);
476
d->m_error = QOrganizerItemManager::BadArgumentError;
482
Remove the organizer item identified by \a organizeritemId from the database.
483
Returns true if the organizer item was removed successfully, otherwise
486
bool QOrganizerItemManager::removeItem(const QOrganizerItemLocalId& organizeritemId)
488
d->m_error = QOrganizerItemManager::NoError;
489
return d->m_engine->removeItem(organizeritemId, &d->m_error);
493
Adds the list of organizeritems given by \a organizeritems list to the database, in
494
the collection identified by the given \a collectionId.
495
Returns true if the organizeritems were saved successfully, otherwise false.
497
If the given \a collectionId does not exist, the function will return false.
498
If the given \a collectionId is the default (zero) id, the items will be saved
499
in the collection in which they are currently saved (if they are not new items) or
500
in the default collection (if they are new items).
501
If the given \a collectionId does exist, all items will be saved in the collection
502
identified by the given \a collectionId.
504
Each collection may have a different schema, so if any of the items cannot be saved
505
in the given collection due to invalid details, the function will return false.
506
An item which is valid in one collection may be invalid in another collection, in the
509
The manager might populate \a errorMap (the map of indices of the \a organizeritems list to
510
the error which occurred when saving the organizer item at that index) for
511
every index for which the organizer item could not be saved, if it is able.
512
The \l QOrganizerItemManager::error() function will only return \c QOrganizerItemManager::NoError
513
if all organizeritems were saved successfully.
515
For each newly saved organizer item that was successful, the id of the organizeritem
516
in the \a organizeritems list will be updated with the new value. If a failure occurs
517
when saving a new organizeritem, the id will be cleared.
519
\sa QOrganizerItemManager::saveItem()
521
bool QOrganizerItemManager::saveItems(QList<QOrganizerItem>* organizeritems, const QOrganizerCollectionLocalId& collectionId, QMap<int, QOrganizerItemManager::Error>* errorMap)
525
if (!organizeritems) {
526
d->m_error = QOrganizerItemManager::BadArgumentError;
530
d->m_error = QOrganizerItemManager::NoError;
531
return d->m_engine->saveItems(organizeritems, collectionId, errorMap, &d->m_error);
535
Remove every organizer item whose id is contained in the list of organizeritems ids
536
\a organizeritemIds. Returns true if all organizeritems were removed successfully,
539
The manager might populate \a errorMap (the map of indices of the \a organizeritemIds list to
540
the error which occurred when saving the organizer item at that index) for every
541
index for which the organizer item could not be removed, if it is able.
542
The \l QOrganizerItemManager::error() function will
543
only return \c QOrganizerItemManager::NoError if all organizeritems were removed
546
If the given list of organizer item ids \a organizeritemIds is empty, the function will return false
547
and calling error() will return \c QOrganizerItemManager::BadArgumentError. If the list is non-empty
548
and contains ids which do not identify a valid organizer item in the manager, the function will
549
remove any organizeritems which are identified by ids in the \a organizeritemIds list, insert
550
\c QOrganizerItemManager::DoesNotExist entries into the \a errorMap for the indices of invalid ids
551
in the \a organizeritemIds list, return false, and set the overall operation error to
552
\c QOrganizerItemManager::DoesNotExistError.
554
\sa QOrganizerItemManager::removeItem()
556
bool QOrganizerItemManager::removeItems(const QList<QOrganizerItemLocalId>& organizeritemIds, QMap<int, QOrganizerItemManager::Error>* errorMap)
560
if (organizeritemIds.isEmpty()) {
561
d->m_error = QOrganizerItemManager::BadArgumentError;
565
d->m_error = QOrganizerItemManager::NoError;
566
return d->m_engine->removeItems(organizeritemIds, errorMap, &d->m_error);
570
Returns the id of the default collection managed by this manager
572
QOrganizerCollectionLocalId QOrganizerItemManager::defaultCollectionId() const
574
d->m_error = QOrganizerItemManager::NoError;
575
return d->m_engine->defaultCollectionId(&d->m_error);
579
Returns the ids of collections managed by this manager.
581
QList<QOrganizerCollectionLocalId> QOrganizerItemManager::collectionIds() const
583
d->m_error = QOrganizerItemManager::NoError;
584
return d->m_engine->collectionIds(&d->m_error);
588
Returns the collections managed by this manager which
589
have an id contained in the list of collection ids \a collectionIds.
590
If the list of collection ids \a collectionIds is empty or
591
not specified, this function will return
592
all collections managed by this manager.
594
QList<QOrganizerCollection> QOrganizerItemManager::collections(const QList<QOrganizerCollectionLocalId>& collectionIds) const
596
d->m_error = QOrganizerItemManager::NoError;
597
return d->m_engine->collections(collectionIds, &d->m_error);
601
Saves the given \a collection in the manager.
602
Returns true on success, false on failure.
604
Some managers do not allow modifications to collections,
605
and thus attempting to save a collection will always fail
606
when attempted in such a manager.
608
Some managers do not allow adding new collections,
609
and thus attempting to save a new collection will always fail
610
when attempted in such a manager.
612
Some managers provide front-ends to read-only datastores, and
613
attempting to save a new collection in such a manager will
616
bool QOrganizerItemManager::saveCollection(QOrganizerCollection* collection)
618
d->m_error = QOrganizerItemManager::NoError;
619
return d->m_engine->saveCollection(collection, &d->m_error);
623
Removes the collection identified by the given \a collectionId (and all items in the collection)
624
from the manager if the given \a collectionId exists.
625
Returns true on success, false on failure.
628
What happens if you attempt to remove the default collection?
629
Fails? Or sets next collection to be the default? Or..?
630
Do we need functions: setDefaultCollection(collection)?
633
bool QOrganizerItemManager::removeCollection(const QOrganizerCollectionLocalId& collectionId)
635
d->m_error = QOrganizerItemManager::NoError;
636
return d->m_engine->removeCollection(collectionId, &d->m_error);
640
Returns a pruned or modified version of the \a original organizer item which is valid and can be saved in the manager.
641
The returned organizer item might have entire details removed or arbitrarily changed. The cache of relationships
642
in the organizer item are ignored entirely when considering compatibility with the backend, as they are
643
saved and validated separately.
645
QOrganizerItem QOrganizerItemManager::compatibleItem(const QOrganizerItem& original)
647
d->m_error = QOrganizerItemManager::NoError;
648
return d->m_engine->compatibleItem(original, &d->m_error);
652
Returns a map of identifier to detail definition for the registered detail definitions which are valid for organizeritems whose type is the given \a organizeritemType
653
which are valid for the organizeritems in this store
655
QMap<QString, QOrganizerItemDetailDefinition> QOrganizerItemManager::detailDefinitions(const QString& organizeritemType) const
657
if (!supportedItemTypes().contains(organizeritemType)) {
658
d->m_error = QOrganizerItemManager::InvalidItemTypeError;
659
return QMap<QString, QOrganizerItemDetailDefinition>();
662
d->m_error = QOrganizerItemManager::NoError;
663
return d->m_engine->detailDefinitions(organizeritemType, &d->m_error);
666
/*! Returns the definition identified by the given \a definitionName that is valid for the organizeritems whose type is the given \a organizeritemType in this store, or a default-constructed QOrganizerItemDetailDefinition if no such definition exists */
667
QOrganizerItemDetailDefinition QOrganizerItemManager::detailDefinition(const QString& definitionName, const QString& organizeritemType) const
669
if (!supportedItemTypes().contains(organizeritemType)) {
670
d->m_error = QOrganizerItemManager::InvalidItemTypeError;
671
return QOrganizerItemDetailDefinition();
674
d->m_error = QOrganizerItemManager::NoError;
675
return d->m_engine->detailDefinition(definitionName, organizeritemType, &d->m_error);
678
/*! Persists the given definition \a def in the database, which is valid for organizeritems whose type is the given \a organizeritemType. Returns true if the definition was saved successfully, otherwise returns false */
679
bool QOrganizerItemManager::saveDetailDefinition(const QOrganizerItemDetailDefinition& def, const QString& organizeritemType)
681
if (!supportedItemTypes().contains(organizeritemType)) {
682
d->m_error = QOrganizerItemManager::InvalidItemTypeError;
686
d->m_error = QOrganizerItemManager::NoError;
687
return d->m_engine->saveDetailDefinition(def, organizeritemType, &d->m_error);
690
/*! Removes the detail definition identified by \a definitionName from the database, which is valid for organizeritems whose type is the given \a organizeritemType. Returns true if the definition was removed successfully, otherwise returns false */
691
bool QOrganizerItemManager::removeDetailDefinition(const QString& definitionName, const QString& organizeritemType)
693
if (!supportedItemTypes().contains(organizeritemType)) {
694
d->m_error = QOrganizerItemManager::InvalidItemTypeError;
698
d->m_error = QOrganizerItemManager::NoError;
699
return d->m_engine->removeDetailDefinition(definitionName, organizeritemType, &d->m_error);
703
\enum QOrganizerItemManager::ManagerFeature
704
This enum describes the possible features that a particular manager may support
705
\value MutableDefinitions The manager supports saving, updating or removing detail definitions. Some built-in definitions may still be immutable
706
\value ChangeLogs The manager supports reporting of timestamps of changes, and filtering and sorting by those timestamps
707
\value Anonymous The manager is isolated from other managers
711
Returns true if the given feature \a feature is supported by the manager, for the specified type of organizer item \a organizeritemType
713
bool QOrganizerItemManager::hasFeature(QOrganizerItemManager::ManagerFeature feature, const QString& organizeritemType) const
715
return d->m_engine->hasFeature(feature, organizeritemType);
719
Returns the list of data types supported by the manager
721
QList<QVariant::Type> QOrganizerItemManager::supportedDataTypes() const
723
return d->m_engine->supportedDataTypes();
727
Returns true if the given \a filter is supported natively by the
728
manager, and false if the filter behaviour would be emulated.
730
Note: In some cases, the behaviour of an unsupported filter
731
cannot be emulated. For example, a filter that requests organizeritems
732
that have changed since a given time depends on having that information
733
available. In these cases, the filter will fail.
735
bool QOrganizerItemManager::isFilterSupported(const QOrganizerItemFilter& filter) const
737
return d->m_engine->isFilterSupported(filter);
741
Returns the list of organizer item types which are supported by this manager.
742
This is a convenience function, equivalent to retrieving the allowable values
743
for the \c QOrganizerItemType::FieldType field of the QOrganizerItemType definition
744
which is valid in this manager.
746
QStringList QOrganizerItemManager::supportedItemTypes() const
748
return d->m_engine->supportedItemTypes();
752
Returns the engine backend implementation version number
754
int QOrganizerItemManager::managerVersion() const
756
return d->m_engine->managerVersion();
759
/*! Returns the manager name for this QOrganizerItemManager */
760
QString QOrganizerItemManager::managerName() const
762
return d->m_engine->managerName();
765
/*! Return the parameters relevant to the creation of this QOrganizerItemManager */
766
QMap<QString, QString> QOrganizerItemManager::managerParameters() const
768
QMap<QString, QString> params = d->m_engine->managerParameters();
770
params.remove(QString::fromAscii(QTORGANIZER_VERSION_NAME));
771
params.remove(QString::fromAscii(QTORGANIZER_IMPLEMENTATION_VERSION_NAME));
776
Return the uri describing this QOrganizerItemManager, consisting of the manager name and any parameters.
778
QString QOrganizerItemManager::managerUri() const
780
return d->m_engine->managerUri();
783
#include "moc_qorganizeritemmanager.cpp"
added
removed
src/organizer/qorganizeritemmanager.cpp
