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
30class KCoreConfigSkeleton;
31class KJob;
32
33namespace Akonadi {
34
35class AgentInstance;
36class 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*/
65class AKONADI_EXPORT SpecialCollections : public QObject
66{
67 Q_OBJECT
68
69public:
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
134Q_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
149protected:
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
158private:
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