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 | |
27 | namespace Akonadi { |
28 | |
29 | class CollectionFetchScope; |
30 | class 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 | */ |
53 | class AKONADI_EXPORT CollectionFetchJob : public Job |
54 | { |
55 | Q_OBJECT |
56 | |
57 | public: |
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 | |
195 | Q_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 | |
203 | protected: |
204 | virtual void doStart(); |
205 | virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data); |
206 | |
207 | protected Q_SLOTS: |
208 | //@cond PRIVATE |
209 | void slotResult(KJob *job); |
210 | //@endcond |
211 | |
212 | private: |
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 | |