Akonadi

specialcollections.h
1 /*
2  SPDX-FileCopyrightText: 2009 Constantin Berzan <[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 "collection.h"
11 #include "item.h"
12 
13 #include <QObject>
14 
15 #include <memory>
16 
18 
19 namespace Akonadi
20 {
21 class AgentInstance;
22 class SpecialCollectionsPrivate;
23 
24 /**
25  @short An interface to special collections.
26 
27  This class is the central interface to special collections like inbox or
28  outbox in a mail resource or recent contacts in a contacts resource.
29  The class is not meant to be used directly, but to inherit the a type
30  specific special collections class from it (e.g. SpecialMailCollections).
31 
32  To check whether a special collection is available, simply use the hasCollection() and
33  hasDefaultCollection() methods. Available special collections are accessible through
34  the collection() and defaultCollection() methods.
35 
36  To create a special collection, use a SpecialCollectionsRequestJob.
37  This will create the special collections you request and automatically
38  register them with SpecialCollections, so that it now knows they are available.
39 
40  This class monitors all special collections known to it, and removes it
41  from the known list if they are deleted. Note that this class does not
42  automatically rebuild the collections that disappeared.
43 
44  The defaultCollectionsChanged() and collectionsChanged() signals are emitted when
45  the special collections for a resource change (i.e. some became available or some
46  become unavailable).
47 
48  @author Constantin Berzan <[email protected]>
49  @since 4.4
50 */
51 class AKONADICORE_EXPORT SpecialCollections : public QObject
52 {
53  Q_OBJECT
54 
55 public:
56  /**
57  * Destroys the special collections object.
58  */
59  ~SpecialCollections() override;
60 
61  /**
62  * Returns whether the given agent @p instance has a special collection of
63  * the given @p type.
64  */
65  Q_REQUIRED_RESULT bool hasCollection(const QByteArray &type, const AgentInstance &instance) const;
66 
67  /**
68  * Returns the special collection of the given @p type in the given agent
69  * @p instance, or an invalid collection if such a collection is unknown.
70  */
71  Q_REQUIRED_RESULT Akonadi::Collection collection(const QByteArray &type, const AgentInstance &instance) const;
72 
73  /**
74  * Registers the given @p collection as a special collection
75  * with the given @p type.
76  * @param type the special type of @c collection
77  * @param collection the given collection to register
78  * The collection must be owned by a valid resource.
79  * Registering a new collection of a previously registered type forgets the
80  * old collection.
81  */
82  bool registerCollection(const QByteArray &type, const Akonadi::Collection &collection);
83 
84  /**
85  * Unregisters the given @p collection as a special collection.
86  * @param type the special type of @c collection
87  * @since 4.12
88  */
89  bool unregisterCollection(const Collection &collection);
90 
91  /**
92  * unsets the special collection attribute which marks @p collection as being a special
93  * collection.
94  * @since 4.12
95  */
96  static void unsetSpecialCollection(const Akonadi::Collection &collection);
97 
98  /**
99  * Sets the special collection attribute which marks @p collection as being a special
100  * collection of type @p type.
101  * This is typically used by configuration dialog for resources, when the user can choose
102  * a specific special collection (ex: IMAP trash).
103  *
104  * @since 4.11
105  */
106  static void setSpecialCollectionType(const QByteArray &type, const Akonadi::Collection &collection);
107 
108  /**
109  * Returns whether the default resource has a special collection of
110  * the given @p type.
111  */
112  Q_REQUIRED_RESULT bool hasDefaultCollection(const QByteArray &type) const;
113 
114  /**
115  * Returns the special collection of given @p type in the default
116  * resource, or an invalid collection if such a collection is unknown.
117  */
118  Q_REQUIRED_RESULT Akonadi::Collection defaultCollection(const QByteArray &type) const;
119 
120 Q_SIGNALS:
121  /**
122  * Emitted when the special collections for a resource have been changed
123  * (for example, some become available, or some become unavailable).
124  *
125  * @param instance The instance of the resource the collection belongs to.
126  */
127  void collectionsChanged(const Akonadi::AgentInstance &instance);
128 
129  /**
130  * Emitted when the special collections for the default resource have
131  * been changed (for example, some become available, or some become unavailable).
132  */
133  void defaultCollectionsChanged();
134 
135 protected:
136  /**
137  * Creates a new special collections object.
138  *
139  * @param config The configuration skeleton that provides the default resource id.
140  * @param parent The parent object.
141  */
142  explicit SpecialCollections(KCoreConfigSkeleton *config, QObject *parent = nullptr);
143 
144 private:
145  /// @cond PRIVATE
146  friend class SpecialCollectionsRequestJob;
147  friend class SpecialCollectionsRequestJobPrivate;
148  friend class SpecialCollectionsPrivate;
149 #ifdef BUILD_TESTING
150  friend class SpecialMailCollectionsTesting;
151  friend class LocalFoldersTest;
152 #endif
153 
154  std::unique_ptr<SpecialCollectionsPrivate> const d;
155  /// @endcond
156 };
157 
158 } // namespace Akonadi
Represents a collection of PIM items.
Definition: collection.h:61
Represents one agent instance and takes care of communication with it.
An interface to special collections.
A representation of an agent instance.
A job to request SpecialCollections.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 04:01:37 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.