1 /*
2     SPDX-FileCopyrightText: 2009 Constantin Berzan <exit3219@gmail.com>
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 
17 class KCoreConfigSkeleton;
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 <exit3219@gmail.com>
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
159 
160