Akonadi

collection.h
1/*
2 SPDX-FileCopyrightText: 2006-2007 Volker Krause <vkrause@kde.org>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6
7#pragma once
8
9#include "akonadicore_export.h"
10#include "attribute.h"
11
12#include <QDebug>
13#include <QMetaType>
14#include <QSharedDataPointer>
15
16class QUrl;
17
18namespace Akonadi
19{
20class CachePolicy;
21class CollectionPrivate;
22class CollectionStatistics;
23
24/**
25 * @short Represents a collection of PIM items.
26 *
27 * This class represents a collection of PIM items, such as a folder on a mail- or
28 * groupware-server.
29 *
30 * Collections are hierarchical, i.e., they may have a parent collection.
31 *
32 * @code
33 *
34 * using namespace Akonadi;
35 *
36 * // fetching all collections recursive, starting at the root collection
37 * CollectionFetchJob *job = new CollectionFetchJob( Collection::root(), CollectionFetchJob::Recursive );
38 * connect( job, SIGNAL(result(KJob*)), SLOT(fetchFinished(KJob*)) );
39 *
40 * ...
41 *
42 * MyClass::fetchFinished( KJob *job )
43 * {
44 * if ( job->error() ) {
45 * qDebug() << "Error occurred";
46 * return;
47 * }
48 *
49 * CollectionFetchJob *fetchJob = qobject_cast<CollectionFetchJob*>( job );
50 *
51 * const Collection::List collections = fetchJob->collections();
52 * for ( const Collection &collection : collections ) {
53 * qDebug() << "Name:" << collection.name();
54 * }
55 * }
56 *
57 * @endcode
58 *
59 * @author Volker Krause <vkrause@kde.org>
60 */
61class AKONADICORE_EXPORT Collection
62{
63 Q_GADGET
64 Q_PROPERTY(Id id READ id WRITE setId)
65 Q_PROPERTY(QString remoteIdd READ remoteId WRITE setRemoteId)
66 Q_PROPERTY(bool isValid READ isValid)
67 Q_PROPERTY(QString remoteRevision READ remoteRevision WRITE setRemoteRevision)
68 Q_PROPERTY(bool enabled READ enabled WRITE setEnabled)
69 Q_PROPERTY(bool isVirtual READ isVirtual WRITE setVirtual)
70 Q_PROPERTY(QString name READ name WRITE setName)
71 Q_PROPERTY(QString displayName READ displayName)
72 Q_PROPERTY(Rights rights READ rights WRITE setRights)
73 Q_PROPERTY(QStringList contentMimeTypes READ contentMimeTypes WRITE setContentMimeTypes)
74 Q_PROPERTY(QString resource READ resource WRITE setResource)
75public:
76 /**
77 * Describes the unique id type.
78 */
79 using Id = qint64;
80
81 /**
82 * Describes a list of collections.
83 */
85
86 /**
87 * Describes rights of a collection.
88 */
89 enum Right {
90 ReadOnly = 0x0, ///< Can only read items or subcollection of this collection
91 CanChangeItem = 0x1, ///< Can change items in this collection
92 CanCreateItem = 0x2, ///< Can create new items in this collection
93 CanDeleteItem = 0x4, ///< Can delete items in this collection
94 CanChangeCollection = 0x8, ///< Can change this collection
95 CanCreateCollection = 0x10, ///< Can create new subcollections in this collection
96 CanDeleteCollection = 0x20, ///< Can delete this collection
97 CanLinkItem = 0x40, ///< Can create links to existing items in this virtual collection @since 4.4
98 CanUnlinkItem = 0x80, ///< Can remove links to items in this virtual collection @since 4.4
99 AllRights = (CanChangeItem | CanCreateItem | CanDeleteItem | CanChangeCollection | CanCreateCollection
100 | CanDeleteCollection) ///< Has all rights on this storage collection
101 };
102 Q_DECLARE_FLAGS(Rights, Right)
103 Q_ENUM(Right)
104
105 /**
106 * Creates an invalid collection.
107 */
108 Collection();
109
110 /**
111 * Create a new collection.
112 *
113 * @param id The unique identifier of the collection.
114 */
115 explicit Collection(Id id);
116
117 /**
118 * Destroys the collection.
119 */
121
122 /**
123 * Creates a collection from an @p other collection.
124 */
125 Collection(const Collection &other);
126
127 /**
128 * Move constructor.
129 */
130 Collection(Collection &&other) noexcept;
131
132 /**
133 * Creates a collection from the given @p url.
134 */
135 static Collection fromUrl(const QUrl &url);
136
137 /**
138 * Sets the unique @p identifier of the collection.
139 */
140 void setId(Id identifier);
141
142 /**
143 * Returns the unique identifier of the collection.
144 */
145 [[nodiscard]] Id id() const;
146
147 /**
148 * Sets the remote @p id of the collection.
149 */
150 void setRemoteId(const QString &id);
151
152 /**
153 * Returns the remote id of the collection.
154 */
155 [[nodiscard]] QString remoteId() const;
156
157 /**
158 * Sets the remote @p revision of the collection.
159 * @param revision the collections's remote revision
160 * The remote revision can be used by resources to store some
161 * revision information of the backend to detect changes there.
162 *
163 * @note This method is supposed to be used by resources only.
164 * @since 4.5
165 */
166 void setRemoteRevision(const QString &revision);
167
168 /**
169 * Returns the remote revision of the collection.
170 *
171 * @note This method is supposed to be used by resources only.
172 * @since 4.5
173 */
174 [[nodiscard]] QString remoteRevision() const;
175
176 /**
177 * Returns whether the collection is valid.
178 */
179 [[nodiscard]] bool isValid() const;
180
181 /**
182 * Returns whether this collections's id equals the
183 * id of the @p other collection.
184 */
185 [[nodiscard]] bool operator==(const Collection &other) const;
186
187 /**
188 * Returns whether the collection's id does not equal the id
189 * of the @p other collection.
190 */
191 [[nodiscard]] bool operator!=(const Collection &other) const;
192
193 /**
194 * Assigns the @p other to this collection and returns a reference to this
195 * collection.
196 * @param other the collection to assign
197 */
198 Collection &operator=(const Collection &other);
199
200 /**
201 * @internal For use with containers only.
202 *
203 * @since 4.8
204 */
205 [[nodiscard]] bool operator<(const Collection &other) const;
206
207 /**
208 * Returns the parent collection of this object.
209 * @note This will of course only return a useful value if it was explicitly retrieved
210 * from the Akonadi server.
211 * @since 4.4
212 */
213 [[nodiscard]] Collection parentCollection() const;
214
215 /**
216 * Returns a reference to the parent collection of this object.
217 * @note This will of course only return a useful value if it was explicitly retrieved
218 * from the Akonadi server.
219 * @since 4.4
220 */
221 [[nodiscard]] Collection &parentCollection();
222
223 /**
224 * Set the parent collection of this object.
225 * @note Calling this method has no immediate effect for the object itself,
226 * such as being moved to another collection.
227 * It is mainly relevant to provide a context for RID-based operations
228 * inside resources.
229 * @param parent The parent collection.
230 * @since 4.4
231 */
232 void setParentCollection(const Collection &parent);
233
234 /**
235 * Adds an attribute to the collection.
236 *
237 * If an attribute of the same type name already exists, it is deleted and
238 * replaced with the new one.
239 *
240 * @param attribute The new attribute.
241 *
242 * @note The collection takes the ownership of the attribute.
243 */
244 void addAttribute(Attribute *attribute);
245
246 /**
247 * Removes and deletes the attribute of the given type @p name.
248 */
249 void removeAttribute(const QByteArray &name);
250
251 /**
252 * Returns @c true if the collection has an attribute of the given type @p name,
253 * false otherwise.
254 */
255 bool hasAttribute(const QByteArray &name) const;
256
257 /**
258 * Returns a list of all attributes of the collection.
259 *
260 * @warning Do not modify the attributes returned from this method,
261 * the change will not be reflected when updating the Collection
262 * through CollectionModifyJob.
263 */
264 [[nodiscard]] Attribute::List attributes() const;
265
266 /**
267 * Removes and deletes all attributes of the collection.
268 */
269 void clearAttributes();
270
271 /**
272 * Returns the attribute of the given type @p name if available, 0 otherwise.
273 */
274 Attribute *attribute(const QByteArray &name);
275 const Attribute *attribute(const QByteArray &name) const;
276
277 /**
278 * Describes the options that can be passed to access attributes.
279 */
281 AddIfMissing, ///< Creates the attribute if it is missing
282 DontCreate ///< Default value
283 };
284
285 /**
286 * Returns the attribute of the requested type.
287 * If the collection has no attribute of that type yet, passing AddIfMissing
288 * as an argument will create and add it to the entity
289 *
290 * @param option The create options.
291 */
292 template<typename T>
293 inline T *attribute(CreateOption option = DontCreate);
294
295 /**
296 * Returns the attribute of the requested type or 0 if it is not available.
297 */
298 template<typename T>
299 inline const T *attribute() const;
300
301 /**
302 * Removes and deletes the attribute of the requested type.
303 */
304 template<typename T>
305 inline void removeAttribute();
306
307 /**
308 * Returns whether the collection has an attribute of the requested type.
309 */
310 template<typename T>
311 inline bool hasAttribute() const;
312
313 /**
314 * Returns the i18n'ed name of the collection.
315 */
316 [[nodiscard]] QString name() const;
317
318 /**
319 * Returns the display name (EntityDisplayAttribute::displayName()) if set,
320 * and Collection::name() otherwise. For human-readable strings this is preferred
321 * over Collection::name().
322 *
323 * @since 4.11
324 */
325 [[nodiscard]] QString displayName() const;
326
327 /**
328 * Sets the i18n'ed name of the collection.
329 *
330 * @param name The new collection name.
331 */
332 void setName(const QString &name);
333
334 /**
335 * Returns the rights the user has on the collection.
336 */
337 [[nodiscard]] Rights rights() const;
338
339 /**
340 * Sets the @p rights the user has on the collection.
341 */
342 void setRights(Rights rights);
343
344 /**
345 * Returns a list of possible content mimetypes,
346 * e.g. message/rfc822, x-akonadi/collection for a mail folder that
347 * supports sub-folders.
348 */
349 [[nodiscard]] QStringList contentMimeTypes() const;
350
351 /**
352 * Sets the list of possible content mime @p types.
353 */
354 void setContentMimeTypes(const QStringList &types);
355
356 /**
357 * Returns the root collection.
358 */
359 [[nodiscard]] static Collection root();
360
361 /**
362 * Returns the mimetype used for collections.
363 */
364 [[nodiscard]] static QString mimeType();
365
366 /**
367 * Returns the mimetype used for virtual collections
368 *
369 * @since 4.11
370 */
371 [[nodiscard]] static QString virtualMimeType();
372
373 /**
374 * Returns the identifier of the resource owning the collection.
375 */
376 [[nodiscard]] QString resource() const;
377
378 /**
379 * Sets the @p identifier of the resource owning the collection.
380 */
381 void setResource(const QString &identifier);
382
383 /**
384 * Returns the cache policy of the collection.
385 */
386 [[nodiscard]] CachePolicy cachePolicy() const;
387
388 /**
389 * Sets the cache @p policy of the collection.
390 */
391 void setCachePolicy(const CachePolicy &policy);
392
393 /**
394 * Returns the collection statistics of the collection.
395 */
396 [[nodiscard]] CollectionStatistics statistics() const;
397
398 /**
399 * Sets the collection @p statistics for the collection.
400 */
401 void setStatistics(const CollectionStatistics &statistics);
402
403 /**
404 * Describes the type of url which is returned in url().
405 *
406 * @since 4.7
407 */
408 enum UrlType {
409 UrlShort = 0, ///< A short url which contains the identifier only (equivalent to url())
410 UrlWithName = 1 ///< A url with identifier and name
411 };
412
413 /**
414 * Returns the url of the collection.
415 * @param type the type of url
416 * @since 4.7
417 */
418 [[nodiscard]] QUrl url(UrlType type = UrlShort) const;
419
420 /**
421 * Returns whether the collection is virtual, for example a search collection.
422 *
423 * @since 4.6
424 */
425 [[nodiscard]] bool isVirtual() const;
426
427 /**
428 * Sets whether the collection is virtual or not.
429 * Virtual collections can't be converted to non-virtual and vice versa.
430 * @param isVirtual virtual collection if @c true, otherwise a normal collection
431 * @since 4.10
432 */
433 void setVirtual(bool isVirtual);
434
435 /**
436 * Sets the collection's enabled state.
437 *
438 * Use this mechanism to set if a collection should be available
439 * to the user or not.
440 *
441 * This can be used in conjunction with the local list preference for finer grained control
442 * to define if a collection should be included depending on the purpose.
443 *
444 * For example: A collection is by default enabled, meaning it is displayed to the user, synchronized by the resource,
445 * and indexed by the indexer. A disabled collection on the other hand is not displayed, synchronized or indexed.
446 * The local list preference allows to locally override that default value for each purpose individually.
447 *
448 * The enabled state can be synchronized by backends.
449 * E.g. an imap resource may synchronize this with the subscription state.
450 *
451 * @since 4.14
452 * @see setLocalListPreference, setShouldList
453 */
454 void setEnabled(bool enabled);
455
456 /**
457 * Returns the collection's enabled state.
458 * @since 4.14
459 * @see localListPreference
460 */
461 [[nodiscard]] bool enabled() const;
462
463 /**
464 * Describes the list preference value
465 *
466 * @since 4.14
467 */
469 ListEnabled, ///< Enable collection for specified purpose
470 ListDisabled, ///< Disable collection for specified purpose
471 ListDefault ///< Fallback to enabled state
472 };
473
474 /**
475 * Describes the purpose of the listing
476 *
477 * @since 4.14
478 */
480 ListSync, ///< Listing for synchronization
481 ListDisplay, ///< Listing for display to the user
482 ListIndex ///< Listing for indexing the content
483 };
484
485 /**
486 * Sets the local list preference for the specified purpose.
487 *
488 * The local list preference overrides the enabled state unless set to ListDefault.
489 * In case of ListDefault the enabled state should be taken as fallback (shouldList() implements this logic).
490 *
491 * The default value is ListDefault.
492 *
493 * @since 4.14
494 * @see shouldList, setEnabled
495 */
496 void setLocalListPreference(ListPurpose purpose, ListPreference preference);
497
498 /**
499 * Returns the local list preference for the specified purpose.
500 * @since 4.14
501 * @see setLocalListPreference
502 */
503 [[nodiscard]] ListPreference localListPreference(ListPurpose purpose) const;
504
505 /**
506 * Returns whether the collection should be listed or not for the specified purpose
507 * Takes enabled state and local preference into account.
508 *
509 * @since 4.14
510 * @see setLocalListPreference, setEnabled
511 */
512 [[nodiscard]] bool shouldList(ListPurpose purpose) const;
513
514 /**
515 * Sets whether the collection should be listed or not for the specified purpose.
516 * Takes enabled state and local preference into account.
517 *
518 * Use this instead of sestEnabled and setLocalListPreference to automatically set
519 * the right setting.
520 *
521 * @since 4.14
522 * @see setLocalListPreference, setEnabled
523 */
524 void setShouldList(ListPurpose purpose, bool shouldList);
525
526 /**
527 * Set during sync to indicate that the provided parts are only default values;
528 * @since 4.15
529 */
530 void setKeepLocalChanges(const QSet<QByteArray> &parts);
531
532 /**
533 * Returns what parts are only default values.
534 */
535 QSet<QByteArray> keepLocalChanges() const;
536
537private:
538 friend class CollectionCreateJob;
539 friend class CollectionFetchJob;
540 friend class CollectionModifyJob;
541 friend class ProtocolHelper;
542
543 void markAttributeModified(const QByteArray &type);
544
545 /// @cond PRIVATE
547 friend class CollectionPrivate;
548 /// @endcond
549};
550
551AKONADICORE_EXPORT size_t qHash(const Akonadi::Collection &collection, size_t seed = 0) noexcept;
552
553template<typename T>
554inline T *Akonadi::Collection::attribute(Collection::CreateOption option)
555{
556 const QByteArray type = T().type();
557 markAttributeModified(type); // do this first in case it detaches
558 if (hasAttribute(type)) {
559 if (T *attr = dynamic_cast<T *>(attribute(type))) {
560 return attr;
561 }
562 qWarning() << "Found attribute of unknown type" << type << ". Did you forget to call AttributeFactory::registerAttribute()?";
563 } else if (option == AddIfMissing) {
564 T *attr = new T();
565 addAttribute(attr);
566 return attr;
567 }
568
569 return nullptr;
570}
571
572template<typename T>
573inline const T *Akonadi::Collection::attribute() const
574{
575 const QByteArray type = T().type();
576 if (hasAttribute(type)) {
577 if (const T *attr = dynamic_cast<const T *>(attribute(type))) {
578 return attr;
579 }
580 qWarning() << "Found attribute of unknown type" << type << ". Did you forget to call AttributeFactory::registerAttribute()?";
581 }
582
583 return nullptr;
584}
585
586template<typename T>
588{
589 removeAttribute(T().type());
590}
591
592template<typename T>
594{
595 return hasAttribute(T().type());
596}
597
598} // namespace Akonadi
599
600/**
601 * Allows to output a collection for debugging purposes.
602 */
603AKONADICORE_EXPORT QDebug operator<<(QDebug d, const Akonadi::Collection &collection);
604
605Q_DECLARE_METATYPE(Akonadi::Collection::List)
606Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::Collection::Rights)
607Q_DECLARE_TYPEINFO(Akonadi::Collection, Q_RELOCATABLE_TYPE);
Provides interface for custom attributes for Entity.
Definition attribute.h:132
Represents the caching policy for a collection.
Definition cachepolicy.h:60
Job that creates a new collection in the Akonadi storage.
Job that fetches collections from the Akonadi storage.
Job that modifies a collection in the Akonadi storage.
Provides statistics information of a Collection.
Represents a collection of PIM items.
Definition collection.h:62
~Collection()
Destroys the collection.
qint64 Id
Describes the unique id type.
Definition collection.h:79
UrlType
Describes the type of url which is returned in url().
Definition collection.h:408
ListPurpose
Describes the purpose of the listing.
Definition collection.h:479
@ ListSync
Listing for synchronization.
Definition collection.h:480
@ ListDisplay
Listing for display to the user.
Definition collection.h:481
Collection(Collection &&other) noexcept
Move constructor.
const T * attribute() const
Returns the attribute of the requested type or 0 if it is not available.
Definition collection.h:573
CreateOption
Describes the options that can be passed to access attributes.
Definition collection.h:280
@ AddIfMissing
Creates the attribute if it is missing.
Definition collection.h:281
Right
Describes rights of a collection.
Definition collection.h:89
bool hasAttribute() const
Returns whether the collection has an attribute of the requested type.
Definition collection.h:593
void removeAttribute()
Removes and deletes the attribute of the requested type.
Definition collection.h:587
ListPreference
Describes the list preference value.
Definition collection.h:468
@ ListDisabled
Disable collection for specified purpose.
Definition collection.h:470
@ ListEnabled
Enable collection for specified purpose.
Definition collection.h:469
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 17 2024 11:54:40 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.