1/*
2 Copyright (c) 2009 Constantin Berzan <exit3219@gmail.com>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_SPECIALCOLLECTIONSHELPERJOBS_P_H
21#define AKONADI_SPECIALCOLLECTIONSHELPERJOBS_P_H
22
23#include "akonadiprivate_export.h"
24
25#include <akonadi/collection.h>
26#include <akonadi/specialcollections.h>
27#include <akonadi/transactionsequence.h>
28
29#include <QtCore/QVariant>
30
31namespace Akonadi {
32
33// ===================== ResourceScanJob ============================
34
35/**
36 @internal
37 Helper job for SpecialCollectionsRequestJob.
38
39 A Job that fetches all the collections of a resource, and returns only
40 those that have a SpecialCollectionAttribute.
41
42 @author Constantin Berzan <exit3219@gmail.com>
43 @since 4.4
44*/
45class AKONADI_TESTS_EXPORT ResourceScanJob : public Job
46{
47 Q_OBJECT
48
49public:
50 /**
51 Creates a new ResourceScanJob.
52 */
53 explicit ResourceScanJob(const QString &resourceId, KCoreConfigSkeleton *settings, QObject *parent = 0);
54
55 /**
56 Destroys this ResourceScanJob.
57 */
58 ~ResourceScanJob();
59
60 /**
61 Returns the resource ID of the resource being scanned.
62 */
63 QString resourceId() const;
64
65 /**
66 Sets the resource ID of the resource to scan.
67 */
68 void setResourceId(const QString &resourceId);
69
70 /**
71 Returns the root collection of the resource being scanned.
72 This function relies on there being a single top-level collection owned
73 by this resource.
74 */
75 Akonadi::Collection rootResourceCollection() const;
76
77 /**
78 Returns all the collections of this resource which have a
79 SpecialCollectionAttribute. These might include the root resource collection.
80 */
81 Akonadi::Collection::List specialCollections() const;
82
83protected:
84 /* reimpl */
85 virtual void doStart();
86
87private:
88 class Private;
89 friend class Private;
90 Private *const d;
91
92 Q_PRIVATE_SLOT(d, void fetchResult(KJob *))
93};
94
95// ===================== DefaultResourceJob ============================
96
97class DefaultResourceJobPrivate;
98
99/**
100 @internal
101 Helper job for SpecialCollectionsRequestJob.
102
103 A custom ResourceScanJob for the default local folders resource. This is a
104 maildir resource stored in ~/.local/share/local-mail.
105
106 This job does two things that a regular ResourceScanJob does not do:
107 1) It creates and syncs the resource if it is missing. The resource ID is
108 stored in a config file named specialcollectionsrc.
109 2) If the resource had to be recreated, but the folders existed on disk
110 before that, it recovers the folders based on name. For instance, it will
111 give a folder named outbox a SpecialCollectionAttribute of type Outbox.
112
113 @author Constantin Berzan <exit3219@gmail.com>
114 @since 4.4
115*/
116class AKONADI_TESTS_EXPORT DefaultResourceJob : public ResourceScanJob
117{
118 Q_OBJECT
119
120public:
121 /**
122 * Creates a new DefaultResourceJob.
123 */
124 explicit DefaultResourceJob(KCoreConfigSkeleton *settings, QObject *parent = 0);
125
126 /**
127 * Destroys the DefaultResourceJob.
128 */
129 ~DefaultResourceJob();
130
131 /**
132 * Sets the @p type of the resource that shall be created if the requested
133 * special collection does not exist yet.
134 */
135 void setDefaultResourceType(const QString &type);
136
137 /**
138 * Sets the configuration @p options that shall be applied to the new resource
139 * that is created if the requested special collection does not exist yet.
140 */
141 void setDefaultResourceOptions(const QVariantMap &options);
142
143 /**
144 * Sets the list of well known special collection @p types.
145 */
146 void setTypes(const QList<QByteArray> &types);
147
148 /**
149 * Sets the @p map of special collection types to display names.
150 */
151 void setNameForTypeMap(const QMap<QByteArray, QString> &map);
152
153 /**
154 * Sets the @p map of special collection types to icon names.
155 */
156 void setIconForTypeMap(const QMap<QByteArray, QString> &map);
157
158protected:
159 /* reimpl */
160 virtual void doStart();
161 /* reimpl */
162 virtual void slotResult(KJob *job);
163
164private:
165 friend class DefaultResourceJobPrivate;
166 DefaultResourceJobPrivate *const d;
167
168 Q_PRIVATE_SLOT(d, void resourceCreateResult(KJob *))
169 Q_PRIVATE_SLOT(d, void resourceSyncResult(KJob *))
170 Q_PRIVATE_SLOT(d, void collectionFetchResult(KJob *))
171 Q_PRIVATE_SLOT(d, void collectionModifyResult(KJob *))
172};
173
174// ===================== GetLockJob ============================
175
176/**
177 @internal
178 Helper job for SpecialCollectionsRequestJob.
179
180 If SpecialCollectionsRequestJob needs to create a collection, it sets a lock so
181 that other instances do not interfere. This lock is an
182 org.kde.pim.SpecialCollections name registered on D-Bus. This job is used to get
183 that lock.
184 This job will give the lock immediately if possible, or wait up to three
185 seconds for the lock to be released. If the lock is not released during
186 that time, this job fails. (This is based on the assumption that
187 SpecialCollectionsRequestJob operations should not take long.)
188
189 Use the releaseLock() function to release the lock.
190
191 @author Constantin Berzan <exit3219@gmail.com>
192 @since 4.4
193*/
194class AKONADI_TESTS_EXPORT GetLockJob : public KJob
195{
196 Q_OBJECT
197
198public:
199 /**
200 Creates a new GetLockJob.
201 */
202 explicit GetLockJob(QObject *parent = 0);
203
204 /**
205 Destroys the GetLockJob.
206 */
207 ~GetLockJob();
208
209 /* reimpl */
210 virtual void start();
211
212private:
213 class Private;
214 friend class Private;
215 Private *const d;
216
217 Q_PRIVATE_SLOT(d, void doStart())
218 Q_PRIVATE_SLOT(d, void serviceOwnerChanged(QString, QString, QString))
219 Q_PRIVATE_SLOT(d, void timeout())
220};
221
222// ===================== helper functions ============================
223
224/**
225 * Sets on @p col the required attributes of SpecialCollection type @p type
226 * These are a SpecialCollectionAttribute and an EntityDisplayAttribute.
227 * @param col collection
228 * @param type collection type
229 * @param nameForType collection name for type
230 * @param iconForType collection icon for type
231*/
232void setCollectionAttributes(Akonadi::Collection &col, const QByteArray &type,
233 const QMap<QByteArray, QString> &nameForType,
234 const QMap<QByteArray, QString> &iconForType);
235
236/**
237 Releases the SpecialCollectionsRequestJob lock that was obtained through
238 GetLockJob.
239 @return Whether the lock was released successfully.
240*/
241bool AKONADI_TESTS_EXPORT releaseLock();
242
243} // namespace Akonadi
244
245#endif // AKONADI_SPECIALCOLLECTIONSHELPERJOBS_P_H
246