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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT QString remoteRevision() const;
175 
176  /**
177  * Returns whether the collection is valid.
178  */
179  Q_REQUIRED_RESULT bool isValid() const;
180 
181  /**
182  * Returns whether this collections's id equals the
183  * id of the @p other collection.
184  */
185  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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> inline T *attribute(CreateOption option = DontCreate);
293 
294  /**
295  * Returns the attribute of the requested type or 0 if it is not available.
296  */
297  template<typename T> inline const T *attribute() const;
298 
299  /**
300  * Removes and deletes the attribute of the requested type.
301  */
302  template<typename T> inline void removeAttribute();
303 
304  /**
305  * Returns whether the collection has an attribute of the requested type.
306  */
307  template<typename T> inline bool hasAttribute() const;
308 
309  /**
310  * Returns the i18n'ed name of the collection.
311  */
312  Q_REQUIRED_RESULT QString name() const;
313 
314  /**
315  * Returns the display name (EntityDisplayAttribute::displayName()) if set,
316  * and Collection::name() otherwise. For human-readable strings this is preferred
317  * over Collection::name().
318  *
319  * @since 4.11
320  */
321  Q_REQUIRED_RESULT QString displayName() const;
322 
323  /**
324  * Sets the i18n'ed name of the collection.
325  *
326  * @param name The new collection name.
327  */
328  void setName(const QString &name);
329 
330  /**
331  * Returns the rights the user has on the collection.
332  */
333  Q_REQUIRED_RESULT Rights rights() const;
334 
335  /**
336  * Sets the @p rights the user has on the collection.
337  */
338  void setRights(Rights rights);
339 
340  /**
341  * Returns a list of possible content mimetypes,
342  * e.g. message/rfc822, x-akonadi/collection for a mail folder that
343  * supports sub-folders.
344  */
345  Q_REQUIRED_RESULT QStringList contentMimeTypes() const;
346 
347  /**
348  * Sets the list of possible content mime @p types.
349  */
350  void setContentMimeTypes(const QStringList &types);
351 
352  /**
353  * Returns the root collection.
354  */
355  Q_REQUIRED_RESULT static Collection root();
356 
357  /**
358  * Returns the mimetype used for collections.
359  */
360  Q_REQUIRED_RESULT static QString mimeType();
361 
362  /**
363  * Returns the mimetype used for virtual collections
364  *
365  * @since 4.11
366  */
367  Q_REQUIRED_RESULT static QString virtualMimeType();
368 
369  /**
370  * Returns the identifier of the resource owning the collection.
371  */
372  Q_REQUIRED_RESULT QString resource() const;
373 
374  /**
375  * Sets the @p identifier of the resource owning the collection.
376  */
377  void setResource(const QString &identifier);
378 
379  /**
380  * Returns the cache policy of the collection.
381  */
382  Q_REQUIRED_RESULT CachePolicy cachePolicy() const;
383 
384  /**
385  * Sets the cache @p policy of the collection.
386  */
387  void setCachePolicy(const CachePolicy &policy);
388 
389  /**
390  * Returns the collection statistics of the collection.
391  */
392  Q_REQUIRED_RESULT CollectionStatistics statistics() const;
393 
394  /**
395  * Sets the collection @p statistics for the collection.
396  */
397  void setStatistics(const CollectionStatistics &statistics);
398 
399  /**
400  * Describes the type of url which is returned in url().
401  *
402  * @since 4.7
403  */
404  enum UrlType {
405  UrlShort = 0, ///< A short url which contains the identifier only (equivalent to url())
406  UrlWithName = 1 ///< A url with identifier and name
407  };
408 
409  /**
410  * Returns the url of the collection.
411  * @param type the type of url
412  * @since 4.7
413  */
414  Q_REQUIRED_RESULT QUrl url(UrlType type = UrlShort) const;
415 
416  /**
417  * Returns whether the collection is virtual, for example a search collection.
418  *
419  * @since 4.6
420  */
421  Q_REQUIRED_RESULT bool isVirtual() const;
422 
423  /**
424  * Sets whether the collection is virtual or not.
425  * Virtual collections can't be converted to non-virtual and vice versa.
426  * @param isVirtual virtual collection if @c true, otherwise a normal collection
427  * @since 4.10
428  */
429  void setVirtual(bool isVirtual);
430 
431  /**
432  * Sets the collection's enabled state.
433  *
434  * Use this mechanism to set if a collection should be available
435  * to the user or not.
436  *
437  * This can be used in conjunction with the local list preference for finer grained control
438  * to define if a collection should be included depending on the purpose.
439  *
440  * For example: A collection is by default enabled, meaning it is displayed to the user, synchronized by the resource,
441  * and indexed by the indexer. A disabled collection on the other hand is not displayed, synchronized or indexed.
442  * The local list preference allows to locally override that default value for each purpose individually.
443  *
444  * The enabled state can be synchronized by backends.
445  * E.g. an imap resource may synchronize this with the subscription state.
446  *
447  * @since 4.14
448  * @see setLocalListPreference, setShouldList
449  */
450  void setEnabled(bool enabled);
451 
452  /**
453  * Returns the collection's enabled state.
454  * @since 4.14
455  * @see localListPreference
456  */
457  Q_REQUIRED_RESULT bool enabled() const;
458 
459  /**
460  * Describes the list preference value
461  *
462  * @since 4.14
463  */
465  ListEnabled, ///< Enable collection for specified purpose
466  ListDisabled, ///< Disable collection for specified purpose
467  ListDefault ///< Fallback to enabled state
468  };
469 
470  /**
471  * Describes the purpose of the listing
472  *
473  * @since 4.14
474  */
475  enum ListPurpose {
476  ListSync, ///< Listing for synchronization
477  ListDisplay, ///< Listing for display to the user
478  ListIndex ///< Listing for indexing the content
479  };
480 
481  /**
482  * Sets the local list preference for the specified purpose.
483  *
484  * The local list preference overrides the enabled state unless set to ListDefault.
485  * In case of ListDefault the enabled state should be taken as fallback (shouldList() implements this logic).
486  *
487  * The default value is ListDefault.
488  *
489  * @since 4.14
490  * @see shouldList, setEnabled
491  */
492  void setLocalListPreference(ListPurpose purpose, ListPreference preference);
493 
494  /**
495  * Returns the local list preference for the specified purpose.
496  * @since 4.14
497  * @see setLocalListPreference
498  */
499  Q_REQUIRED_RESULT ListPreference localListPreference(ListPurpose purpose) const;
500 
501  /**
502  * Returns whether the collection should be listed or not for the specified purpose
503  * Takes enabled state and local preference into account.
504  *
505  * @since 4.14
506  * @see setLocalListPreference, setEnabled
507  */
508  Q_REQUIRED_RESULT bool shouldList(ListPurpose purpose) const;
509 
510  /**
511  * Sets whether the collection should be listed or not for the specified purpose.
512  * Takes enabled state and local preference into account.
513  *
514  * Use this instead of sestEnabled and setLocalListPreference to automatically set
515  * the right setting.
516  *
517  * @since 4.14
518  * @see setLocalListPreference, setEnabled
519  */
520  void setShouldList(ListPurpose purpose, bool shouldList);
521 
522  /**
523  * Set during sync to indicate that the provided parts are only default values;
524  * @since 4.15
525  */
526  void setKeepLocalChanges(const QSet<QByteArray> &parts);
527 
528  /**
529  * Returns what parts are only default values.
530  */
531  QSet<QByteArray> keepLocalChanges() const;
532 
533 private:
534  friend class CollectionCreateJob;
535  friend class CollectionFetchJob;
536  friend class CollectionModifyJob;
537  friend class ProtocolHelper;
538 
539  void markAttributeModified(const QByteArray &type);
540 
541  /// @cond PRIVATE
543  friend class CollectionPrivate;
544  /// @endcond
545 };
546 
547 AKONADICORE_EXPORT uint qHash(const Akonadi::Collection &collection);
548 
549 template<typename T> inline T *Akonadi::Collection::attribute(Collection::CreateOption option)
550 {
551  const QByteArray type = T().type();
552  markAttributeModified(type); // do this first in case it detaches
553  if (hasAttribute(type)) {
554  if (T *attr = dynamic_cast<T *>(attribute(type))) {
555  return attr;
556  }
557  qWarning() << "Found attribute of unknown type" << type << ". Did you forget to call AttributeFactory::registerAttribute()?";
558  } else if (option == AddIfMissing) {
559  T *attr = new T();
560  addAttribute(attr);
561  return attr;
562  }
563 
564  return nullptr;
565 }
566 
567 template<typename T> inline const T *Akonadi::Collection::attribute() const
568 {
569  const QByteArray type = T().type();
570  if (hasAttribute(type)) {
571  if (const T *attr = dynamic_cast<const T *>(attribute(type))) {
572  return attr;
573  }
574  qWarning() << "Found attribute of unknown type" << type << ". Did you forget to call AttributeFactory::registerAttribute()?";
575  }
576 
577  return nullptr;
578 }
579 
580 template<typename T> inline void Akonadi::Collection::removeAttribute()
581 {
582  removeAttribute(T().type());
583 }
584 
585 template<typename T> inline bool Akonadi::Collection::hasAttribute() const
586 {
587  return hasAttribute(T().type());
588 }
589 
590 } // namespace Akonadi
591 
592 /**
593  * Allows to output a collection for debugging purposes.
594  */
595 AKONADICORE_EXPORT QDebug operator<<(QDebug d, const Akonadi::Collection &collection);
596 
597 Q_DECLARE_METATYPE(Akonadi::Collection)
598 Q_DECLARE_METATYPE(Akonadi::Collection::List)
599 Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::Collection::Rights)
600 Q_DECLARE_TYPEINFO(Akonadi::Collection, Q_MOVABLE_TYPE);
601 
Provides statistics information of a Collection.
Job that modifies a collection in the Akonadi storage.
Represents a collection of PIM items.
Definition: collection.h:61
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
Provides interface for custom attributes for Entity.
Definition: attribute.h:124
void removeAttribute()
Removes and deletes the attribute of the requested type.
Definition: collection.h:580
Definition: item.h:32
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:585
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:465
@ ListDisplay
Listing for display to the user.
Definition: collection.h:477
const T * attribute() const
Returns the attribute of the requested type or 0 if it is not available.
Definition: collection.h:567
KCALENDARCORE_EXPORT uint qHash(const KCalendarCore::Period &key)
@ ListSync
Listing for synchronization.
Definition: collection.h:476
@ ListDisabled
Disable collection for specified purpose.
Definition: collection.h:466
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:404
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:475
ListPreference
Describes the list preference value.
Definition: collection.h:464
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jul 2 2022 06:41:47 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.