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_ITEMFETCHJOB_H |
21 | #define AKONADI_ITEMFETCHJOB_H |
22 | |
23 | #include <akonadi/item.h> |
24 | #include <akonadi/job.h> |
25 | |
26 | namespace Akonadi { |
27 | |
28 | class Collection; |
29 | class ItemFetchJobPrivate; |
30 | class ItemFetchScope; |
31 | |
32 | /** |
33 | * @short Job that fetches items from the Akonadi storage. |
34 | * |
35 | * This class is used to fetch items from the Akonadi storage. |
36 | * Which parts of the items (e.g. headers only, attachments or all) |
37 | * can be specified by the ItemFetchScope. |
38 | * |
39 | * Note that ItemFetchJob does not refresh the Akonadi storage from the |
40 | * backend; this is unnecessary due to the fact that backend updates |
41 | * automatically trigger an update to the Akonadi database whenever they occur |
42 | * (unless the resource is offline). |
43 | * |
44 | * Note that items can not be created in the root collection (Collection::root()) |
45 | * and therefore can not be fetched from there either. That is - an item fetch in |
46 | * the root collection will yield an empty list. |
47 | * |
48 | * |
49 | * Example: |
50 | * |
51 | * @code |
52 | * |
53 | * // Fetch all items with full payload from a collection |
54 | * |
55 | * const Collection collection = getCollection(); |
56 | * |
57 | * Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob(collection); |
58 | * connect(job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*))); |
59 | * job->fetchScope().fetchFullPayload(); |
60 | * |
61 | * ... |
62 | * |
63 | * MyClass::jobFinished(KJob *job) |
64 | * { |
65 | * if (job->error()) { |
66 | * qDebug() << "Error occurred"; |
67 | * return; |
68 | * } |
69 | * |
70 | * Akonadi::ItemFetchJob *fetchJob = qobject_cast<Akonadi::ItemFetchJob*>(job); |
71 | * |
72 | * const Akonadi::Item::List items = fetchJob->items(); |
73 | * foreach (const Akonadi::Item &item, items) { |
74 | * qDebug() << "Item ID:" << item.id(); |
75 | * } |
76 | * } |
77 | * |
78 | * @endcode |
79 | * |
80 | * @author Volker Krause <vkrause@kde.org> |
81 | */ |
82 | class AKONADI_EXPORT ItemFetchJob : public Job |
83 | { |
84 | Q_OBJECT |
85 | Q_FLAGS(DeliveryOptions) |
86 | public: |
87 | /** |
88 | * Creates a new item fetch job that retrieves all items inside the given collection. |
89 | * |
90 | * @param collection The parent collection to fetch all items from. |
91 | * @param parent The parent object. |
92 | */ |
93 | explicit ItemFetchJob(const Collection &collection, QObject *parent = 0); |
94 | |
95 | /** |
96 | * Creates a new item fetch job that retrieves the specified item. |
97 | * If the item has a uid set, this is used to identify the item on the Akonadi |
98 | * server. If only a remote identifier is available, that is used. |
99 | * However, as remote identifiers are not necessarily globally unique, you |
100 | * need to specify the collection to search in in that case, using |
101 | * setCollection(). |
102 | * |
103 | * @internal |
104 | * For internal use only when using remote identifiers, the resource search |
105 | * context can be set globally by ResourceSelectJob. |
106 | * @endinternal |
107 | * |
108 | * @param item The item to fetch. |
109 | * @param parent The parent object. |
110 | */ |
111 | explicit ItemFetchJob(const Item &item, QObject *parent = 0); |
112 | |
113 | /** |
114 | * Creates a new item fetch job that retrieves the specified items. |
115 | * If the items have a uid set, this is used to identify the item on the Akonadi |
116 | * server. If only a remote identifier is available, that is used. |
117 | * However, as remote identifiers are not necessarily globally unique, you |
118 | * need to specify the collection to search in in that case, using |
119 | * setCollection(). |
120 | * |
121 | * @internal |
122 | * For internal use only when using remote identifiers, the resource search |
123 | * context can be set globally by ResourceSelectJob. |
124 | * @endinternal |
125 | * |
126 | * @param items The items to fetch. |
127 | * @param parent The parent object. |
128 | * @since 4.4 |
129 | */ |
130 | explicit ItemFetchJob(const Item::List &items, QObject *parent = 0); |
131 | |
132 | /** |
133 | * Convenience ctor equivalent to ItemFetchJob(const Item::List &items, QObject *parent = 0) |
134 | * @since 4.8 |
135 | */ |
136 | explicit ItemFetchJob(const QList<Item::Id> &items, QObject *parent = 0); |
137 | |
138 | |
139 | /** |
140 | * Creates a new item fetch job that retrieves all items tagged with specified @p tag. |
141 | * |
142 | * @param tag The tag to fetch all items from. |
143 | * @param parent The parent object. |
144 | * |
145 | * @since 4.14 |
146 | */ |
147 | explicit ItemFetchJob(const Tag &tag, QObject *parent = 0); |
148 | |
149 | /** |
150 | * Destroys the item fetch job. |
151 | */ |
152 | virtual ~ItemFetchJob(); |
153 | |
154 | /** |
155 | * Returns the fetched items. |
156 | * |
157 | * This returns an empty list when not using the ItemGetter DeliveryOption. |
158 | * |
159 | * @note The items are invalid before the result(KJob*) |
160 | * signal has been emitted or if an error occurred. |
161 | */ |
162 | Item::List items() const; |
163 | |
164 | /** |
165 | * Save memory by clearing the fetched items. |
166 | * @since 4.12 |
167 | */ |
168 | void clearItems(); |
169 | |
170 | /** |
171 | * Sets the item fetch scope. |
172 | * |
173 | * The ItemFetchScope controls how much of an item's data is fetched |
174 | * from the server, e.g. whether to fetch the full item payload or |
175 | * only meta data. |
176 | * |
177 | * @param fetchScope The new scope for item fetch operations. |
178 | * |
179 | * @see fetchScope() |
180 | */ |
181 | void setFetchScope(ItemFetchScope &fetchScope); // KDE5: remove |
182 | |
183 | /** |
184 | * Sets the item fetch scope. |
185 | * |
186 | * The ItemFetchScope controls how much of an item's data is fetched |
187 | * from the server, e.g. whether to fetch the full item payload or |
188 | * only meta data. |
189 | * |
190 | * @param fetchScope The new scope for item fetch operations. |
191 | * |
192 | * @see fetchScope() |
193 | * @since 4.4 |
194 | */ |
195 | void setFetchScope(const ItemFetchScope &fetchScope); |
196 | |
197 | /** |
198 | * Returns the item fetch scope. |
199 | * |
200 | * Since this returns a reference it can be used to conveniently modify the |
201 | * current scope in-place, i.e. by calling a method on the returned reference |
202 | * without storing it in a local variable. See the ItemFetchScope documentation |
203 | * for an example. |
204 | * |
205 | * @return a reference to the current item fetch scope |
206 | * |
207 | * @see setFetchScope() for replacing the current item fetch scope |
208 | */ |
209 | ItemFetchScope &fetchScope(); |
210 | |
211 | /** |
212 | * Specifies the collection the item is in. |
213 | * This is only required when retrieving an item based on its remote id |
214 | * which might not be unique globally. |
215 | * |
216 | * @internal |
217 | * @see ResourceSelectJob (for internal use only) |
218 | * @endinternal |
219 | */ |
220 | void setCollection(const Collection &collection); |
221 | |
222 | enum DeliveryOption { |
223 | ItemGetter = 0x1, ///< items available through items() |
224 | EmitItemsIndividually = 0x2, ///< emitted via signal upon reception |
225 | EmitItemsInBatches = 0x4, ///< emitted via signal in bulk (collected and emitted delayed via timer) |
226 | Default = ItemGetter | EmitItemsInBatches |
227 | }; |
228 | Q_DECLARE_FLAGS(DeliveryOptions, DeliveryOption) |
229 | |
230 | /** |
231 | * Sets the mechanisms by which the items should be fetched |
232 | * @since 4.13 |
233 | */ |
234 | void setDeliveryOption(DeliveryOptions options); |
235 | |
236 | /** |
237 | * Returns the delivery options |
238 | * @since 4.13 |
239 | */ |
240 | DeliveryOptions deliveryOptions() const; |
241 | |
242 | /** |
243 | * Returns the total number of retrieved items. |
244 | * This works also without the ItemGetter DeliveryOption. |
245 | * @since 4.14 |
246 | */ |
247 | int count() const; |
248 | |
249 | Q_SIGNALS: |
250 | /** |
251 | * This signal is emitted whenever new items have been fetched completely. |
252 | * |
253 | * @note This is an optimization; instead of waiting for the end of the job |
254 | * and calling items(), you can connect to this signal and get the items |
255 | * incrementally. |
256 | * |
257 | * @param items The fetched items. |
258 | */ |
259 | void itemsReceived(const Akonadi::Item::List &items); |
260 | |
261 | protected: |
262 | virtual void doStart(); |
263 | virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data); |
264 | |
265 | private: |
266 | Q_DECLARE_PRIVATE(ItemFetchJob) |
267 | |
268 | //@cond PRIVATE |
269 | Q_PRIVATE_SLOT(d_func(), void timeout()) |
270 | //@endcond |
271 | }; |
272 | |
273 | } |
274 | |
275 | Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::ItemFetchJob::DeliveryOptions) |
276 | |
277 | #endif |
278 | |