← Back to branch summary

~chris.gagnon/+junk/qtpim-coverage

« back to all changes in this revision

Viewing changes to src/plugins/organizer/jsondb/qorganizerjsondbengine.h

  • 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/plugins/organizer/jsondb/qorganizerjsondbengine.h
 
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 QtOrganizer module of the Qt Toolkit.
 
7
**
 
8
** $QT_BEGIN_LICENSE:LGPL$
 
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 Lesser General Public License Usage
 
18
** Alternatively, this file may be used under the terms of the GNU Lesser
 
19
** General Public License version 2.1 as published by the Free Software
 
20
** Foundation and appearing in the file LICENSE.LGPL included in the
 
21
** packaging of this file.  Please review the following information to
 
22
** ensure the GNU Lesser General Public License version 2.1 requirements
 
23
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
 
24
**
 
25
** In addition, as a special exception, Digia gives you certain additional
 
26
** rights.  These rights are described in the Digia Qt LGPL Exception
 
27
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
 
28
**
 
29
** GNU General Public License Usage
 
30
** Alternatively, this file may be used under the terms of the GNU
 
31
** General Public License version 3.0 as published by the Free Software
 
32
** Foundation and appearing in the file LICENSE.GPL included in the
 
33
** packaging of this file.  Please review the following information to
 
34
** ensure the GNU General Public License version 3.0 requirements will be
 
35
** met: http://www.gnu.org/copyleft/gpl.html.
 
36
**
 
37
**
 
38
** $QT_END_LICENSE$
 
39
**
 
40
****************************************************************************/
 
41
 
 
42
#ifndef QORGANIZERJSONDBENGINE_H
 
43
#define QORGANIZERJSONDBENGINE_H
 
44
 
 
45
//
 
46
//  W A R N I N G
 
47
//  -------------
 
48
//
 
49
// This file is not part of the Qt API.  It exists purely as an
 
50
// implementation detail.  This header file may change from version to
 
51
// version without notice, or even be removed.
 
52
//
 
53
// We mean it.
 
54
//
 
55
 
 
56
#include <QtOrganizer/qorganizermanagerengine.h>
 
57
 
 
58
QT_BEGIN_NAMESPACE_ORGANIZER
 
59
 
 
60
/*
 
61
 Organizer jsondb backend storage location related documentation
 
62
 (will be moved later to proper location)
 
63
 
 
64
 Storage locations are locations where the organizer data can be stored. Currently there
 
65
 are two locations; UserDataStorage and SystemStorage. These can be seen on the
 
66
 QOrganizerAbstractRequest API's QOrganizerAbstractRequest::StorageLocation.
 
67
 
 
68
 Organizer jsondb backend engine requires storage locations (partitions in qtjsondb-module
 
69
 terminology) to be present. If MissingPlatformRequirementsError is received from requests,
 
70
 it means that the mandatory UserDataStorage storage location is missing or cannot be accessed due
 
71
 to missing security access rights and Organizer jsondb backend cannot work properly.
 
72
 InvalidStorageLocationError is returned in cases when the operation is targeted to non-mandatory, but not
 
73
 accessible storage location.
 
74
 
 
75
 To create missing partitions, create a file named partitions.json having the following lines
 
76
 in it:
 
77
 [
 
78
    { "name" : "com.nokia.mt.User" },
 
79
    { "name" : "com.nokia.mt.System" }
 
80
 ]
 
81
 Then when starting the jsondb process on background, start it with path to partitions.json
 
82
 -file defined like this -> jsondb -config-path /home/me/myjsondbfiles/
 
83
 
 
84
 If you use QOrganizerManagerEngine APIs, please note that the QOrganizerJsonDbEngineData's
 
85
 implementation directs all the operations to UserDataStorage storage location. If you want to
 
86
 target operations to other storage locations, you need to use the asynchronous requests
 
87
 instead.
 
88
 
 
89
 There are some restrictions with organizer data and storing it to storage locations:
 
90
 - Once an item or collection is saved to one storage location, you cannot change it to
 
91
 another storage location. The storage location parameter is ignored on the following updates.
 
92
 - A collection and all the items it contains must also exist in the same storage location.
 
93
 If not, InvalidCollectionError is returned when attempting to save the item.
 
94
 
 
95
 By default items and collections are stored in UserDataStorage storage location and fetched
 
96
 from there.
 
97
 
 
98
 Storage location information is included in the engine item id syntax in following way:
 
99
 [QOrganizerAbstractRequest::StorageLocation]/[jsondb uuid]
 
100
*/
 
101
 
 
102
class QOrganizerJsonDbRequestThread;
 
103
 
 
104
class QOrganizerJsonDbEngine : public QOrganizerManagerEngine
 
105
{
 
106
    Q_OBJECT
 
107
 
 
108
public:
 
109
    enum StorageLocation {
 
110
        UserDataStorage = 0x1,
 
111
        SystemStorage = 0x2
 
112
    };
 
113
    Q_DECLARE_FLAGS(StorageLocations, StorageLocation)
 
114
 
 
115
    QOrganizerJsonDbEngine(QOrganizerManager::Error *error);
 
116
    ~QOrganizerJsonDbEngine();
 
117
 
 
118
    /* URI reporting */
 
119
    QString managerName() const;
 
120
    QMap<QString, QString> managerParameters() const;
 
121
 
 
122
    // items
 
123
    QList<QOrganizerItem> items(const QList<QOrganizerItemId> &itemIds, const QOrganizerItemFetchHint &fetchHint,
 
124
                                QMap<int, QOrganizerManager::Error> *errorMap, QOrganizerManager::Error *error);
 
125
 
 
126
    QList<QOrganizerItem> items(const QOrganizerItemFilter &filter, const QDateTime &startDateTime,
 
127
                                const QDateTime &endDateTime, int maxCount,
 
128
                                const QList<QOrganizerItemSortOrder> &sortOrders,
 
129
                                const QOrganizerItemFetchHint &fetchHint, QOrganizerManager::Error *error);
 
130
 
 
131
    QList<QOrganizerItemId> itemIds(const QOrganizerItemFilter &filter, const QDateTime &startDateTime,
 
132
                                    const QDateTime &endDateTime, const QList<QOrganizerItemSortOrder> &sortOrders,
 
133
                                    QOrganizerManager::Error *error);
 
134
 
 
135
    QList<QOrganizerItem> itemOccurrences(const QOrganizerItem &parentItem, const QDateTime &startDateTime,
 
136
                                          const QDateTime &endDateTime, int maxCount,
 
137
                                          const QOrganizerItemFetchHint &fetchHint, QOrganizerManager::Error *error);
 
138
 
 
139
    QList<QOrganizerItem> itemsForExport(const QDateTime &startDateTime, const QDateTime &endDateTime,
 
140
                                         const QOrganizerItemFilter &filter,
 
141
                                         const QList<QOrganizerItemSortOrder> &sortOrders,
 
142
                                         const QOrganizerItemFetchHint &fetchHint, QOrganizerManager::Error *error);
 
143
 
 
144
    bool saveItems(QList<QOrganizerItem> *items, const QList<QOrganizerItemDetail::DetailType> &detailMask,
 
145
                   QMap<int, QOrganizerManager::Error> *errorMap, QOrganizerManager::Error *error);
 
146
 
 
147
    bool removeItems(const QList<QOrganizerItemId> &itemIds, QMap<int, QOrganizerManager::Error> *errorMap,
 
148
                     QOrganizerManager::Error *error);
 
149
 
 
150
    bool removeItems(const QList<QOrganizerItem> *items, QMap<int, QOrganizerManager::Error>* errorMap,
 
151
                     QOrganizerManager::Error* error);
 
152
 
 
153
    // collections
 
154
    QOrganizerCollection defaultCollection(QOrganizerManager::Error* error);
 
155
    QOrganizerCollection collection(const QOrganizerCollectionId& collectionId, QOrganizerManager::Error* error);
 
156
    QList<QOrganizerCollection> collections(QOrganizerManager::Error* error);
 
157
    bool saveCollection(QOrganizerCollection* collection, QOrganizerManager::Error* error);
 
158
    bool removeCollection(const QOrganizerCollectionId& collectionId, QOrganizerManager::Error* error);
 
159
 
 
160
    /* Capabilities reporting */
 
161
    QList<QOrganizerItemFilter::FilterType> supportedFilters() const;
 
162
    QList<QOrganizerItemDetail::DetailType> supportedItemDetails(QOrganizerItemType::ItemType itemType) const;
 
163
    QList<QOrganizerItemType::ItemType> supportedItemTypes() const;
 
164
 
 
165
    /* Asynchronous Request Support */
 
166
    void requestDestroyed(QOrganizerAbstractRequest* req);
 
167
    bool startRequest(QOrganizerAbstractRequest* req);
 
168
    bool cancelRequest(QOrganizerAbstractRequest* req);
 
169
    bool waitForRequestFinished(QOrganizerAbstractRequest* req, int msecs);
 
170
 
 
171
    /* JsonDb Engine internal capability reporting */
 
172
    static const QList<int> supportedDetailFields(QOrganizerItemDetail::DetailType detailType);
 
173
 
 
174
signals:
 
175
    void requestReceived(QOrganizerAbstractRequest* req);
 
176
 
 
177
private:
 
178
    friend class QOrganizerJsonDbEngineFactory;
 
179
    QOrganizerJsonDbRequestThread *m_requestHandlerThread;
 
180
};
 
181
 
 
182
Q_DECLARE_OPERATORS_FOR_FLAGS(QOrganizerJsonDbEngine::StorageLocations)
 
183
 
 
184
QT_END_NAMESPACE_ORGANIZER
 
185
 
 
186
#endif