1/*
2 Copyright (c) 2006 - 2007 Volker Krause <vkrause@kde.org>
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_COLLECTIONFETCHJOB_H
21#define AKONADI_COLLECTIONFETCHJOB_H
22
23#include "akonadi_export.h"
24#include <akonadi/collection.h>
25#include <akonadi/job.h>
26
27namespace Akonadi {
28
29class CollectionFetchScope;
30class CollectionFetchJobPrivate;
31
32/**
33 * @short Job that fetches collections from the Akonadi storage.
34 *
35 * This class can be used to retrieve the complete or partial collection tree
36 * from the Akonadi storage. This fetches collection data, not item data.
37 *
38 * @code
39 *
40 * using namespace Akonadi;
41 *
42 * // fetching all collections containing emails recursively, starting at the root collection
43 * CollectionFetchJob *job = new CollectionFetchJob(Collection::root(), CollectionFetchJob::Recursive, this);
44 * job->fetchScope().setContentMimeTypes(QStringList() << "message/rfc822");
45 * connect(job, SIGNAL(collectionsReceived(Akonadi::Collection::List)),
46 * this, SLOT(myCollectionsReceived(Akonadi::Collection::List)));
47 * connect(job, SIGNAL(result(KJob*)), this, SLOT(collectionFetchResult(KJob*)));
48 *
49 * @endcode
50 *
51 * @author Volker Krause <vkrause@kde.org>
52 */
53class AKONADI_EXPORT CollectionFetchJob : public Job
54{
55 Q_OBJECT
56
57public:
58 /**
59 * Describes the type of fetch depth.
60 */
61 enum Type {
62 Base, ///< Only fetch the base collection.
63 FirstLevel, ///< Only list direct sub-collections of the base collection.
64 Recursive, ///< List all sub-collections.
65 NonOverlappingRoots ///< List the roots of a list of fetched collections. @since 4.7
66 };
67
68 /**
69 * Creates a new collection fetch job. If the given base collection
70 * has a unique identifier, this is used to identify the collection in the
71 * Akonadi server. If only a remote identifier is available the collection
72 * is identified using that, provided that a resource search context has
73 * been specified by calling setResource().
74 *
75 * @internal
76 * For internal use only, if a remote identifier is set, the resource
77 * search context can be set globally using ResourceSelectJob.
78 * @endinternal
79 *
80 * @param collection The base collection for the listing.
81 * @param type The type of fetch depth.
82 * @param parent The parent object.
83 */
84 explicit CollectionFetchJob(const Collection &collection, Type type = FirstLevel, QObject *parent = 0);
85
86 /**
87 * Creates a new collection fetch job to retrieve a list of collections.
88 * If a given collection has a unique identifier, this is used to identify
89 * the collection in the Akonadi server. If only a remote identifier is
90 * available the collection is identified using that, provided that a
91 * resource search context has been specified by calling setResource().
92 *
93 * @internal
94 * For internal use only, if a remote identifier is set, the resource
95 * search context can be set globally using ResourceSelectJob.
96 * @endinternal
97 *
98 * @param collections A list of collections to fetch. Must not be empty.
99 * @param parent The parent object.
100 */
101 explicit CollectionFetchJob(const Collection::List &collections, QObject *parent = 0);
102
103 /**
104 * Creates a new collection fetch job to retrieve a list of collections.
105 * If a given collection has a unique identifier, this is used to identify
106 * the collection in the Akonadi server. If only a remote identifier is
107 * available the collection is identified using that, provided that a
108 * resource search context has been specified by calling setResource().
109 *
110 * @internal
111 * For internal use only, if a remote identifier is set, the resource
112 * search context can be set globally using ResourceSelectJob.
113 * @endinternal
114 *
115 * @param collections A list of collections to fetch. Must not be empty.
116 * @param type The type of fetch depth.
117 * @param parent The parent object.
118 * @todo KDE5 merge with ctor above.
119 * @since 4.7
120 */
121 CollectionFetchJob(const Collection::List &collections, Type type, QObject *parent = 0);
122
123 /**
124 * Convenience ctor equivalent to CollectionFetchJob(const Collection::List &collections, Type type, QObject *parent = 0)
125 * @since 4.8
126 * @param collections list of collection ids
127 * @param type fetch job type
128 * @param parent parent object
129 */
130 explicit CollectionFetchJob(const QList<Collection::Id> &collections, Type type = Base, QObject *parent = 0);
131
132 /**
133 * Destroys the collection fetch job.
134 */
135 virtual ~CollectionFetchJob();
136
137 /**
138 * Returns the list of fetched collection.
139 */
140 Collection::List collections() const;
141
142 /**
143 * Sets a resource identifier to limit collection listing to one resource.
144 *
145 * @param resource The resource identifier.
146 * @deprecated Use CollectionFetchScope instead.
147 */
148 AKONADI_DEPRECATED void setResource(const QString &resource);
149
150 /**
151 * Include also unsubscribed collections.
152 * @deprecated Use CollectionFetchScope instead.
153 * @param include whether to also fetch unsubscribed collections
154 */
155 AKONADI_DEPRECATED void includeUnsubscribed(bool include = true);
156
157 /**
158 * Include also statistics about the collections.
159 *
160 * @since 4.3
161 * @deprecated Use CollectionFetchScope instead.
162 * @param include whether to also fetch statistics
163 */
164 AKONADI_DEPRECATED void includeStatistics(bool include = true);
165
166 /**
167 * Sets the collection fetch scope.
168 *
169 * The CollectionFetchScope controls how much of a collection's data is
170 * fetched from the server as well as a filter to select which collections
171 * to fetch.
172 *
173 * @param fetchScope The new scope for collection fetch operations.
174 *
175 * @see fetchScope()
176 * @since 4.4
177 */
178 void setFetchScope(const CollectionFetchScope &fetchScope);
179
180 /**
181 * Returns the collection fetch scope.
182 *
183 * Since this returns a reference it can be used to conveniently modify the
184 * current scope in-place, i.e. by calling a method on the returned reference
185 * without storing it in a local variable. See the CollectionFetchScope documentation
186 * for an example.
187 *
188 * @return a reference to the current collection fetch scope
189 *
190 * @see setFetchScope() for replacing the current collection fetch scope
191 * @since 4.4
192 */
193 CollectionFetchScope &fetchScope();
194
195Q_SIGNALS:
196 /**
197 * This signal is emitted whenever the job has received collections.
198 *
199 * @param collections The received collections.
200 */
201 void collectionsReceived(const Akonadi::Collection::List &collections);
202
203protected:
204 virtual void doStart();
205 virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data);
206
207protected Q_SLOTS:
208 //@cond PRIVATE
209 void slotResult(KJob *job);
210 //@endcond
211
212private:
213 Q_DECLARE_PRIVATE(CollectionFetchJob)
214
215 //@cond PRIVATE
216 Q_PRIVATE_SLOT(d_func(), void timeout())
217 Q_PRIVATE_SLOT(d_func(), void subJobCollectionReceived(const Akonadi::Collection::List &))
218 //@endcond
219};
220
221}
222
223#endif
224