1 | /* |
2 | Copyright (c) 2006 - 2007 Volker Krause <vkrause@kde.org> |
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_COLLECTION_H |
21 | #define AKONADI_COLLECTION_H |
22 | |
23 | #include "akonadi_export.h" |
24 | |
25 | #include <akonadi/entity.h> |
26 | |
27 | #include <QtCore/QMetaType> |
28 | #include <QtCore/QSharedDataPointer> |
29 | |
30 | class KUrl; |
31 | |
32 | namespace Akonadi { |
33 | |
34 | class CachePolicy; |
35 | class CollectionPrivate; |
36 | class CollectionStatistics; |
37 | |
38 | /** |
39 | * @short Represents a collection of PIM items. |
40 | * |
41 | * This class represents a collection of PIM items, such as a folder on a mail- or |
42 | * groupware-server. |
43 | * |
44 | * Collections are hierarchical, i.e., they may have a parent collection. |
45 | * |
46 | * @code |
47 | * |
48 | * using namespace Akonadi; |
49 | * |
50 | * // fetching all collections recursive, starting at the root collection |
51 | * CollectionFetchJob *job = new CollectionFetchJob( Collection::root(), CollectionFetchJob::Recursive ); |
52 | * connect( job, SIGNAL(result(KJob*)), SLOT(fetchFinished(KJob*)) ); |
53 | * |
54 | * ... |
55 | * |
56 | * MyClass::fetchFinished( KJob *job ) |
57 | * { |
58 | * if ( job->error() ) { |
59 | * qDebug() << "Error occurred"; |
60 | * return; |
61 | * } |
62 | * |
63 | * CollectionFetchJob *fetchJob = qobject_cast<CollectionFetchJob*>( job ); |
64 | * |
65 | * const Collection::List collections = fetchJob->collections(); |
66 | * foreach ( const Collection &collection, collections ) { |
67 | * qDebug() << "Name:" << collection.name(); |
68 | * } |
69 | * } |
70 | * |
71 | * @endcode |
72 | * |
73 | * @author Volker Krause <vkrause@kde.org> |
74 | */ |
75 | class AKONADI_EXPORT Collection : public Entity |
76 | { |
77 | public: |
78 | /** |
79 | * Describes a list of collections. |
80 | */ |
81 | typedef QList<Collection> List; |
82 | |
83 | /** |
84 | * Describes rights of a collection. |
85 | */ |
86 | enum Right { |
87 | ReadOnly = 0x0, ///< Can only read items or subcollection of this collection |
88 | CanChangeItem = 0x1, ///< Can change items in this collection |
89 | CanCreateItem = 0x2, ///< Can create new items in this collection |
90 | CanDeleteItem = 0x4, ///< Can delete items in this collection |
91 | CanChangeCollection = 0x8, ///< Can change this collection |
92 | CanCreateCollection = 0x10, ///< Can create new subcollections in this collection |
93 | CanDeleteCollection = 0x20, ///< Can delete this collection |
94 | CanLinkItem = 0x40, ///< Can create links to existing items in this virtual collection @since 4.4 |
95 | CanUnlinkItem = 0x80, ///< Can remove links to items in this virtual collection @since 4.4 |
96 | AllRights = (CanChangeItem | CanCreateItem | CanDeleteItem | |
97 | CanChangeCollection | CanCreateCollection | CanDeleteCollection) ///< Has all rights on this storage collection |
98 | }; |
99 | Q_DECLARE_FLAGS(Rights, Right) |
100 | |
101 | /** |
102 | * Creates an invalid collection. |
103 | */ |
104 | Collection(); |
105 | |
106 | /** |
107 | * Create a new collection. |
108 | * |
109 | * @param id The unique identifier of the collection. |
110 | */ |
111 | explicit Collection(Id id); |
112 | |
113 | /** |
114 | * Destroys the collection. |
115 | */ |
116 | ~Collection(); |
117 | |
118 | /** |
119 | * Creates a collection from an @p other collection. |
120 | */ |
121 | Collection(const Collection &other); |
122 | |
123 | /** |
124 | * Creates a collection from the given @p url. |
125 | */ |
126 | static Collection fromUrl(const KUrl &url); |
127 | |
128 | /** |
129 | * Returns the i18n'ed name of the collection. |
130 | */ |
131 | QString name() const; |
132 | |
133 | /** |
134 | * Returns the display name (EntityDisplayAttribute::displayName()) if set, |
135 | * and Collection::name() otherwise. For human-readable strings this is preferred |
136 | * over Collection::name(). |
137 | * |
138 | * @since 4.11 |
139 | */ |
140 | QString displayName() const; |
141 | |
142 | /** |
143 | * Sets the i18n'ed name of the collection. |
144 | * |
145 | * @param name The new collection name. |
146 | */ |
147 | void setName(const QString &name); |
148 | |
149 | /** |
150 | * Returns the rights the user has on the collection. |
151 | */ |
152 | Rights rights() const; |
153 | |
154 | /** |
155 | * Sets the @p rights the user has on the collection. |
156 | */ |
157 | void setRights(Rights rights); |
158 | |
159 | /** |
160 | * Returns a list of possible content mimetypes, |
161 | * e.g. message/rfc822, x-akonadi/collection for a mail folder that |
162 | * supports sub-folders. |
163 | */ |
164 | QStringList contentMimeTypes() const; |
165 | |
166 | /** |
167 | * Sets the list of possible content mime @p types. |
168 | */ |
169 | void setContentMimeTypes(const QStringList &types); |
170 | |
171 | /** |
172 | * Returns the identifier of the parent collection. |
173 | * @deprecated Use parentCollection() |
174 | */ |
175 | AKONADI_DEPRECATED Id parent() const; |
176 | |
177 | /** |
178 | * Sets the identifier of the @p parent collection. |
179 | * @param parent the parent identifier to set |
180 | * @deprecated Use setParentCollection() |
181 | */ |
182 | AKONADI_DEPRECATED void setParent(Id parent); |
183 | |
184 | /** |
185 | * Sets the parent @p collection. |
186 | * @param collection the parent collection to set |
187 | * @deprecated Use setParentCollection() |
188 | */ |
189 | AKONADI_DEPRECATED void setParent(const Collection &collection); |
190 | |
191 | /** |
192 | * Returns the parent remote identifier. |
193 | * @note This usually returns nothing for collections retrieved from the backend. |
194 | * @deprecated Use parentCollection() |
195 | */ |
196 | AKONADI_DEPRECATED QString parentRemoteId() const; |
197 | |
198 | /** |
199 | * Sets the parent's remote @p identifier. |
200 | * @param identifier the parent's remote identifier to set |
201 | * @deprecated Use setParentCollection() |
202 | */ |
203 | AKONADI_DEPRECATED void setParentRemoteId(const QString &identifier); |
204 | |
205 | /** |
206 | * Returns the root collection. |
207 | */ |
208 | static Collection root(); |
209 | |
210 | /** |
211 | * Returns the mimetype used for collections. |
212 | */ |
213 | static QString mimeType(); |
214 | |
215 | /** |
216 | * Returns the mimetype used for virtual collections |
217 | * |
218 | * @since 4.11 |
219 | */ |
220 | static QString virtualMimeType(); |
221 | |
222 | /** |
223 | * Returns the identifier of the resource owning the collection. |
224 | */ |
225 | QString resource() const; |
226 | |
227 | /** |
228 | * Sets the @p identifier of the resource owning the collection. |
229 | */ |
230 | void setResource(const QString &identifier); |
231 | |
232 | /** |
233 | * Returns the cache policy of the collection. |
234 | */ |
235 | CachePolicy cachePolicy() const; |
236 | |
237 | /** |
238 | * Sets the cache @p policy of the collection. |
239 | */ |
240 | void setCachePolicy(const CachePolicy &policy); |
241 | |
242 | /** |
243 | * Returns the collection statistics of the collection. |
244 | */ |
245 | CollectionStatistics statistics() const; |
246 | |
247 | /** |
248 | * Sets the collection @p statistics for the collection. |
249 | */ |
250 | void setStatistics(const CollectionStatistics &statistics); |
251 | |
252 | /** |
253 | * Returns the url of the collection. |
254 | * |
255 | * @todo KDE5 remove in favor of url( UrlType type = UrlShort ). |
256 | */ |
257 | KUrl url() const; |
258 | |
259 | /** |
260 | * Describes the type of url which is returned in url(). |
261 | * |
262 | * @since 4.7 |
263 | */ |
264 | enum UrlType { |
265 | UrlShort = 0, ///< A short url which contains the identifier only (equivalent to url()) |
266 | UrlWithName = 1 ///< A url with identifier and name |
267 | }; |
268 | |
269 | /** |
270 | * Returns the url of the collection. |
271 | * @param type the type of url |
272 | * @since 4.7 |
273 | */ |
274 | KUrl url(UrlType type) const; |
275 | |
276 | /** |
277 | * Returns whether the collection is virtual, for example a search collection. |
278 | * |
279 | * @since 4.6 |
280 | */ |
281 | bool isVirtual() const; |
282 | |
283 | /** |
284 | * Sets whether the collection is virtual or not. |
285 | * Virtual collections can't be converted to non-virtual and vice versa. |
286 | * @param isVirtual virtual collection if @c true, otherwise a normal collection |
287 | * @since 4.10 |
288 | */ |
289 | void setVirtual(bool isVirtual); |
290 | |
291 | /** |
292 | * Sets the collection's enabled state. |
293 | * |
294 | * Use this mechanism to set if a collection should be available |
295 | * to the user or not. |
296 | * |
297 | * This can be used in conjunction with the local list preference for finer grained control |
298 | * to define if a collection should be included depending on the purpose. |
299 | * |
300 | * For example: A collection is by default enabled, meaning it is displayed to the user, synchronized by the resource, |
301 | * and indexed by the indexer. A disabled collection on the other hand is not displayed, sychronized or indexed. |
302 | * The local list preference allows to locally override that default value for each purpose individually. |
303 | * |
304 | * The enabled state can be synchronized by backends. |
305 | * E.g. an imap resource may synchronize this with the subscription state. |
306 | * |
307 | * @since 4.14 |
308 | * @see setLocalListPreference, setShouldList |
309 | */ |
310 | void setEnabled(bool enabled); |
311 | |
312 | /** |
313 | * Returns the collection's enabled state. |
314 | * @since 4.14 |
315 | * @see localListPreference |
316 | */ |
317 | bool enabled() const; |
318 | |
319 | /** |
320 | * Describes the list preference value |
321 | * |
322 | * @since 4.14 |
323 | */ |
324 | enum ListPreference { |
325 | ListEnabled, ///< Enable collection for specified purpose |
326 | ListDisabled, ///< Disable collectoin for specified purpose |
327 | ListDefault ///< Fallback to enabled state |
328 | }; |
329 | |
330 | /** |
331 | * Describes the purpose of the listing |
332 | * |
333 | * @since 4.14 |
334 | */ |
335 | enum ListPurpose { |
336 | ListSync, ///< Listing for synchronization |
337 | ListDisplay, ///< Listing for display to the user |
338 | ListIndex ///< Listing for indexing the content |
339 | }; |
340 | |
341 | /** |
342 | * Sets the local list preference for the specified purpose. |
343 | * |
344 | * The local list preference overrides the enabled state unless set to ListDefault. |
345 | * In case of ListDefault the enabled state should be taken as fallback (shouldList() implements this logic). |
346 | * |
347 | * The default value is ListDefault. |
348 | * |
349 | * @since 4.14 |
350 | * @see shouldList, setEnabled |
351 | */ |
352 | void setLocalListPreference(ListPurpose purpose, ListPreference preference); |
353 | |
354 | /** |
355 | * Returns the local list preference for the specified purpose. |
356 | * @since 4.14 |
357 | * @see setLocalListPreference |
358 | */ |
359 | ListPreference localListPreference(ListPurpose purpose) const; |
360 | |
361 | /** |
362 | * Returns whether the collection should be listed or not for the specified purpose |
363 | * Takes enabled state and local preference into account. |
364 | * |
365 | * @since 4.14 |
366 | * @see setLocalListPreference, setEnabled |
367 | */ |
368 | bool shouldList(ListPurpose purpose) const; |
369 | |
370 | /** |
371 | * Sets wether the collection should be listed or not for the specified purpose. |
372 | * Takes enabled state and local preference into account. |
373 | * |
374 | * Use this instead of sestEnabled and setLocalListPreference to automatically set |
375 | * the right setting. |
376 | * |
377 | * @since 4.14 |
378 | * @see setLocalListPreference, setEnabled |
379 | */ |
380 | void setShouldList(ListPurpose purpose, bool shouldList); |
381 | |
382 | /** |
383 | * Sets a collection to be referenced. |
384 | * |
385 | * A referenced collection is temporarily shown and synchronized even when disabled. |
386 | * A reference is only valid for the duration of a session, and is automatically removed afterwards. |
387 | * |
388 | * Referenced collections are only visible if explicitly monitored in the ETM. |
389 | * |
390 | * @since 4.14 |
391 | */ |
392 | void setReferenced(bool referenced); |
393 | |
394 | /** |
395 | * Returns the referenced state of the collection. |
396 | * @since 4.14 |
397 | */ |
398 | bool referenced() const; |
399 | |
400 | private: |
401 | AKONADI_DECLARE_PRIVATE(Collection) |
402 | friend class CollectionFetchJob; |
403 | friend class CollectionModifyJob; |
404 | }; |
405 | |
406 | } |
407 | |
408 | AKONADI_EXPORT uint qHash(const Akonadi::Collection &collection); |
409 | /** |
410 | * Allows to output a collection for debugging purposes. |
411 | */ |
412 | AKONADI_EXPORT QDebug operator<<(QDebug d, const Akonadi::Collection &collection); |
413 | |
414 | Q_DECLARE_METATYPE(Akonadi::Collection) |
415 | Q_DECLARE_METATYPE(Akonadi::Collection::List) |
416 | Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::Collection::Rights) |
417 | |
418 | #endif |
419 | |