Akonadi

collection.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 Volker Krause <[email protected]>
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 
16 class QUrl;
17 
18 namespace Akonadi
19 {
20 class CachePolicy;
21 class CollectionPrivate;
22 class 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 <[email protected]>
60  */
61 class 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)
75 public:
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  */
120  ~Collection();
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  */
479  enum ListPurpose {
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 
537 private:
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 
551 AKONADICORE_EXPORT uint qHash(const Akonadi::Collection &collection);
552 
553 template<typename T>
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 
572 template<typename T>
573 inline 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 
586 template<typename T>
588 {
589  removeAttribute(T().type());
590 }
591 
592 template<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  */
603 AKONADICORE_EXPORT QDebug operator<<(QDebug d, const Akonadi::Collection &collection);
604 
605 Q_DECLARE_METATYPE(Akonadi::Collection::List)
606 Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::Collection::Rights)
607 Q_DECLARE_TYPEINFO(Akonadi::Collection, Q_RELOCATABLE_TYPE);
Provides statistics information of a Collection.
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Job that modifies a collection in the Akonadi storage.
Represents a collection of PIM items.
Definition: collection.h:61
Provides interface for custom attributes for Entity.
Definition: attribute.h:131
void removeAttribute()
Removes and deletes the attribute of the requested type.
Definition: collection.h:587
Represents the caching policy for a collection.
Definition: cachepolicy.h:59
bool hasAttribute() const
Returns whether the collection has an attribute of the requested type.
Definition: collection.h:593
Job that fetches collections from the Akonadi storage.
CreateOption
Describes the options that can be passed to access attributes.
Definition: collection.h:280
@ ListEnabled
Enable collection for specified purpose.
Definition: collection.h:469
@ ListDisplay
Listing for display to the user.
Definition: collection.h:481
const T * attribute() const
Returns the attribute of the requested type or 0 if it is not available.
Definition: collection.h:573
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
@ ListSync
Listing for synchronization.
Definition: collection.h:480
@ ListDisabled
Disable collection for specified purpose.
Definition: collection.h:470
Right
Describes rights of a collection.
Definition: collection.h:89
@ AddIfMissing
Creates the attribute if it is missing.
Definition: collection.h:281
UrlType
Describes the type of url which is returned in url().
Definition: collection.h:408
Job that creates a new collection in the Akonadi storage.
qint64 Id
Describes the unique id type.
Definition: collection.h:79
ListPurpose
Describes the purpose of the listing.
Definition: collection.h:479
ListPreference
Describes the list preference value.
Definition: collection.h:468
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sat Dec 9 2023 04:03:56 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.