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
30class KUrl;
31
32namespace Akonadi {
33
34class CachePolicy;
35class CollectionPrivate;
36class 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 */
75class AKONADI_EXPORT Collection : public Entity
76{
77public:
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
400private:
401 AKONADI_DECLARE_PRIVATE(Collection)
402 friend class CollectionFetchJob;
403 friend class CollectionModifyJob;
404};
405
406}
407
408AKONADI_EXPORT uint qHash(const Akonadi::Collection &collection);
409/**
410 * Allows to output a collection for debugging purposes.
411 */
412AKONADI_EXPORT QDebug operator<<(QDebug d, const Akonadi::Collection &collection);
413
414Q_DECLARE_METATYPE(Akonadi::Collection)
415Q_DECLARE_METATYPE(Akonadi::Collection::List)
416Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::Collection::Rights)
417
418#endif
419