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

KDE's Doxygen guidelines are available online.