1 | /* |
2 | Copyright (c) 2009 Constantin Berzan <exit3219@gmail.com> |
3 | |
4 | This library is free software; you can redistribute it and/or modify it |
5 | under the terms of the GNU Library General Public License as published by |
6 | the Free Software Foundation; either version 2 of the License, or (at your |
7 | option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, but WITHOUT |
10 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
11 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
12 | License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to the |
16 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
17 | 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef AKONADI_SPECIALCOLLECTIONS_H |
21 | #define AKONADI_SPECIALCOLLECTIONS_H |
22 | |
23 | #include "akonadi_export.h" |
24 | |
25 | #include <QtCore/QObject> |
26 | |
27 | #include "akonadi/collection.h" |
28 | #include <akonadi/item.h> |
29 | |
30 | class KCoreConfigSkeleton; |
31 | class KJob; |
32 | |
33 | namespace Akonadi { |
34 | |
35 | class AgentInstance; |
36 | class SpecialCollectionsPrivate; |
37 | |
38 | /** |
39 | @short An interface to special collections. |
40 | |
41 | This class is the central interface to special collections like inbox or |
42 | outbox in a mail resource or recent contacts in a contacts resource. |
43 | The class is not meant to be used directly, but to inherit the a type |
44 | specific special collections class from it (e.g. SpecialMailCollections). |
45 | |
46 | To check whether a special collection is available, simply use the hasCollection() and |
47 | hasDefaultCollection() methods. Available special collections are accessible through |
48 | the collection() and defaultCollection() methods. |
49 | |
50 | To create a special collection, use a SpecialCollectionsRequestJob. |
51 | This will create the special collections you request and automatically |
52 | register them with SpecialCollections, so that it now knows they are available. |
53 | |
54 | This class monitors all special collections known to it, and removes it |
55 | from the known list if they are deleted. Note that this class does not |
56 | automatically rebuild the collections that disappeared. |
57 | |
58 | The defaultCollectionsChanged() and collectionsChanged() signals are emitted when |
59 | the special collections for a resource change (i.e. some became available or some |
60 | become unavailable). |
61 | |
62 | @author Constantin Berzan <exit3219@gmail.com> |
63 | @since 4.4 |
64 | */ |
65 | class AKONADI_EXPORT SpecialCollections : public QObject |
66 | { |
67 | Q_OBJECT |
68 | |
69 | public: |
70 | /** |
71 | * Destroys the special collections object. |
72 | */ |
73 | ~SpecialCollections(); |
74 | |
75 | /** |
76 | * Returns whether the given agent @p instance has a special collection of |
77 | * the given @p type. |
78 | */ |
79 | bool hasCollection(const QByteArray &type, const AgentInstance &instance) const; |
80 | |
81 | /** |
82 | * Returns the special collection of the given @p type in the given agent |
83 | * @p instance, or an invalid collection if such a collection is unknown. |
84 | */ |
85 | Akonadi::Collection collection(const QByteArray &type, const AgentInstance &instance) const; |
86 | |
87 | /** |
88 | * Registers the given @p collection as a special collection |
89 | * with the given @p type. |
90 | * @param type the special type of @c collection |
91 | * @param collection the given collection to register |
92 | * The collection must be owned by a valid resource. |
93 | * Registering a new collection of a previously registered type forgets the |
94 | * old collection. |
95 | */ |
96 | bool registerCollection(const QByteArray &type, const Akonadi::Collection &collection); |
97 | |
98 | /** |
99 | * Unregisters the given @p collection as a spec ial collection. |
100 | * @param type the special type of @c collection |
101 | * @since 4.12 |
102 | */ |
103 | bool unregisterCollection(const Collection &collection); |
104 | |
105 | /** |
106 | * unsets the special collection attribute which marks @p collection as being a special |
107 | * collection. |
108 | * @since 4.12 |
109 | */ |
110 | static void unsetSpecialCollection(const Akonadi::Collection &collection); |
111 | |
112 | /** |
113 | * Sets the special collection attribute which marks @p collection as being a special |
114 | * collection of type @p type. |
115 | * This is typically used by configuration dialog for resources, when the user can choose |
116 | * a specific special collection (ex: IMAP trash). |
117 | * |
118 | * @since 4.11 |
119 | */ |
120 | static void setSpecialCollectionType(const QByteArray &type, const Akonadi::Collection &collection); |
121 | |
122 | /** |
123 | * Returns whether the default resource has a special collection of |
124 | * the given @p type. |
125 | */ |
126 | bool hasDefaultCollection(const QByteArray &type) const; |
127 | |
128 | /** |
129 | * Returns the special collection of given @p type in the default |
130 | * resource, or an invalid collection if such a collection is unknown. |
131 | */ |
132 | Akonadi::Collection defaultCollection(const QByteArray &type) const; |
133 | |
134 | Q_SIGNALS: |
135 | /** |
136 | * Emitted when the special collections for a resource have been changed |
137 | * (for example, some become available, or some become unavailable). |
138 | * |
139 | * @param instance The instance of the resource the collection belongs to. |
140 | */ |
141 | void collectionsChanged(const Akonadi::AgentInstance &instance); |
142 | |
143 | /** |
144 | * Emitted when the special collections for the default resource have |
145 | * been changed (for example, some become available, or some become unavailable). |
146 | */ |
147 | void defaultCollectionsChanged(); |
148 | |
149 | protected: |
150 | /** |
151 | * Creates a new special collections object. |
152 | * |
153 | * @param config The configuration skeleton that provides the default resource id. |
154 | * @param parent The parent object. |
155 | */ |
156 | explicit SpecialCollections(KCoreConfigSkeleton *config, QObject *parent = 0); |
157 | |
158 | private: |
159 | //@cond PRIVATE |
160 | friend class SpecialCollectionsRequestJob; |
161 | friend class SpecialCollectionsRequestJobPrivate; |
162 | friend class SpecialCollectionsPrivate; |
163 | |
164 | #if 1 // TODO do this only if building tests: |
165 | friend class SpecialMailCollectionsTesting; |
166 | friend class LocalFoldersTest; |
167 | #endif |
168 | |
169 | SpecialCollectionsPrivate *const d; |
170 | |
171 | Q_PRIVATE_SLOT(d, void collectionRemoved(const Akonadi::Collection &)) |
172 | Q_PRIVATE_SLOT(d, void collectionStatisticsChanged(Akonadi::Collection::Id, const Akonadi::CollectionStatistics &)) |
173 | Q_PRIVATE_SLOT(d, void collectionFetchJobFinished(KJob *)) |
174 | //@endcond |
175 | }; |
176 | |
177 | } // namespace Akonadi |
178 | |
179 | #endif // AKONADI_SPECIALCOLLECTIONS_H |
180 | |