1/*
2 Copyright (c) 2008 Kevin Krammer <kevin.krammer@gmx.at>
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 ITEMFETCHSCOPE_H
21#define ITEMFETCHSCOPE_H
22
23#include "akonadi_export.h"
24
25#include <QtCore/QSharedDataPointer>
26#include <KDE/KDateTime>
27
28class QStringList;
29template <typename T> class QSet;
30
31namespace Akonadi {
32
33class ItemFetchScopePrivate;
34
35/**
36 * @short Specifies which parts of an item should be fetched from the Akonadi storage.
37 *
38 * When items are fetched from server either by using ItemFetchJob explicitly or
39 * when it is being used internally by other classes, e.g. ItemModel, the scope
40 * of the fetch operation can be tailored to the application's current needs.
41 *
42 * There are two supported ways of changing the currently active ItemFetchScope
43 * of classes:
44 * - in-place: modify the ItemFetchScope object the other class holds as a member
45 * - replace: replace the other class' member with a new scope object
46 *
47 * Example: modifying an ItemFetchJob's scope @c in-place
48 * @code
49 * Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob( collection );
50 * job->fetchScope().fetchFullPayload();
51 * job->fetchScope().fetchAttribute<MyAttribute>();
52 * @endcode
53 *
54 * Example: @c replacing an ItemFetchJob's scope
55 * @code
56 * Akonadi::ItemFetchScope scope;
57 * scope.fetchFullPayload();
58 * scope.fetchAttribute<MyAttribute>();
59 *
60 * Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob( collection );
61 * job->setFetchScope( scope );
62 * @endcode
63 *
64 * This class is implicitly shared.
65 *
66 * @author Kevin Krammer <kevin.krammer@gmx.at>
67 */
68class AKONADI_EXPORT ItemFetchScope
69{
70public:
71 /**
72 * Describes the ancestor retrieval depth.
73 * @since 4.4
74 */
75 enum AncestorRetrieval {
76 None, ///< No ancestor retrieval at all (the default)
77 Parent, ///< Only retrieve the immediate parent collection
78 All ///< Retrieve all ancestors, up to Collection::root()
79 };
80
81 /**
82 * Creates an empty item fetch scope.
83 *
84 * Using an empty scope will only fetch the very basic meta data of items,
85 * e.g. local id, remote id and mime type
86 */
87 ItemFetchScope();
88
89 /**
90 * Creates a new item fetch scope from an @p other.
91 */
92 ItemFetchScope(const ItemFetchScope &other);
93
94 /**
95 * Destroys the item fetch scope.
96 */
97 ~ItemFetchScope();
98
99 /**
100 * Assigns the @p other to this scope and returns a reference to this scope.
101 */
102 ItemFetchScope &operator=(const ItemFetchScope &other);
103
104 /**
105 * Returns the payload parts that should be fetched.
106 *
107 * @see fetchPayloadPart()
108 */
109 QSet<QByteArray> payloadParts() const;
110
111 /**
112 * Sets which payload parts shall be fetched.
113 *
114 * @param part The payload part identifier.
115 * Valid values depend on the item type.
116 * @param fetch @c true to fetch this part, @c false otherwise.
117 */
118 void fetchPayloadPart(const QByteArray &part, bool fetch = true);
119
120 /**
121 * Returns whether the full payload should be fetched.
122 *
123 * @see fetchFullPayload()
124 */
125 bool fullPayload() const;
126
127 /**
128 * Sets whether the full payload shall be fetched.
129 * The default is @c false.
130 *
131 * @param fetch @c true if the full payload should be fetched, @c false otherwise.
132 */
133 void fetchFullPayload(bool fetch = true);
134
135 /**
136 * Returns all explicitly fetched attributes.
137 *
138 * Undefined if fetchAllAttributes() returns true.
139 *
140 * @see fetchAttribute()
141 */
142 QSet<QByteArray> attributes() const;
143
144 /**
145 * Sets whether the attribute of the given @p type should be fetched.
146 *
147 * @param type The attribute type to fetch.
148 * @param fetch @c true if the attribute should be fetched, @c false otherwise.
149 */
150 void fetchAttribute(const QByteArray &type, bool fetch = true);
151
152 /**
153 * Sets whether the attribute of the requested type should be fetched.
154 *
155 * @param fetch @c true if the attribute should be fetched, @c false otherwise.
156 */
157 template <typename T> inline void fetchAttribute(bool fetch = true)
158 {
159 T dummy;
160 fetchAttribute(dummy.type(), fetch);
161 }
162
163 /**
164 * Returns whether all available attributes should be fetched.
165 *
166 * @see fetchAllAttributes()
167 */
168 bool allAttributes() const;
169
170 /**
171 * Sets whether all available attributes should be fetched.
172 * The default is @c false.
173 *
174 * @param fetch @c true if all available attributes should be fetched, @c false otherwise.
175 */
176 void fetchAllAttributes(bool fetch = true);
177
178 /**
179 * Returns whether payload data should be requested from remote sources or just
180 * from the local cache.
181 *
182 * @see setCacheOnly()
183 */
184 bool cacheOnly() const;
185
186 /**
187 * Sets whether payload data should be requested from remote sources or just
188 * from the local cache.
189 *
190 * @param cacheOnly @c true if no remote data should be requested,
191 * @c false otherwise (the default).
192 */
193 void setCacheOnly(bool cacheOnly);
194
195 /**
196 * Sets whether payload will be fetched or there will be only a test performed if the
197 * requested payload is in the cache. Calling it calls @see setCacheOnly with true automatically.
198 * Default is fetching the data.
199 *
200 * @since 4.11
201 */
202 void setCheckForCachedPayloadPartsOnly(bool check = true);
203
204 /**
205 * Returns whether payload data should be fetched or only checked for presence in the cache.
206 *
207 * @see setCheckForCachedPayloadPartsOnly()
208 *
209 * @since 4.11
210 */
211 bool checkForCachedPayloadPartsOnly() const;
212
213 /**
214 * Sets how many levels of ancestor collections should be included in the retrieval.
215 * The default is AncestorRetrieval::None.
216 *
217 * @param ancestorDepth The desired ancestor retrieval depth.
218 * @since 4.4
219 */
220 void setAncestorRetrieval(AncestorRetrieval ancestorDepth);
221
222 /**
223 * Returns the ancestor retrieval depth.
224 *
225 * @see setAncestorRetrieval()
226 * @since 4.4
227 */
228 AncestorRetrieval ancestorRetrieval() const;
229
230 /**
231 * Enables retrieval of the item modification time.
232 * This is enabled by default for backward compatibility reasons.
233 *
234 * @param retrieveMtime @c true to retrieve the modification time, @c false otherwise
235 * @since 4.6
236 */
237 void setFetchModificationTime(bool retrieveMtime);
238
239 /**
240 * Returns whether item modification time should be retrieved.
241 *
242 * @see setFetchModificationTime()
243 * @since 4.6
244 */
245 bool fetchModificationTime() const;
246
247 /**
248 * Enables retrieval of the item GID.
249 * This is disabled by default.
250 *
251 * @param retrieveGID @c true to retrieve the GID, @c false otherwise
252 * @since 4.12
253 */
254 void setFetchGid(bool retrieveGID);
255
256 /**
257 * Returns whether item GID should be retrieved.
258 *
259 * @see setFetchGid()
260 * @since 4.12
261 */
262 bool fetchGid() const;
263
264 /**
265 * Ignore retrieval errors while fetching items, and always deliver what is available.
266 * If items have missing parts and the part can't be retrieved from the resource (i.e. because the system is offline),
267 * the fetch job would normally just fail. By setting this flag, the errors are ignored,
268 * and all items which could be fetched completely are returned.
269 * Note that all items that are returned are completely fetched, and incomplete items are simply ignored.
270 * This flag is useful for displaying everything that is available, where it is not crucial to have all items.
271 * Never use this for things like data migration or alike.
272 *
273 * @since 4.10
274 */
275 void setIgnoreRetrievalErrors(bool enabled);
276
277 /**
278 * Returns whether retrieval errors should be ignored.
279 *
280 * @see setIgnoreRetrievalErrors()
281 * @since 4.10
282 */
283 bool ignoreRetrievalErrors() const;
284
285 /**
286 * Returns @c true if there is nothing to fetch.
287 */
288 bool isEmpty() const;
289
290 /**
291 * Only fetch items that were added or modified after given timestamp
292 *
293 * When this property is set, all results are filtered, i.e. even when you
294 * request an item with a specific ID, it will not be fetched unless it was
295 * modified after @p changedSince timestamp.
296 *
297 * @param changedSince The timestamp of oldest modified item to fetch
298 * @since 4.11
299 */
300 void setFetchChangedSince(const KDateTime &changedSince);
301
302 /**
303 * Returns timestamp of the oldest item to fetch.
304 */
305 KDateTime fetchChangedSince() const;
306
307 /**
308 * Fetch remote identification for items.
309 *
310 * These include Akonadi::Item::remoteId() and Akonadi::Item::remoteRevision(). This should
311 * be off for normal clients usually, to save memory (not to mention normal clients should
312 * not be concerned with these information anyway). It is however crucial for resource agents.
313 * For backward compatibility the default is @c true.
314 *
315 * @param retrieveRid whether or not to load remote identification.
316 * @since 4.12
317 */
318 void setFetchRemoteIdentification(bool retrieveRid);
319
320 /**
321 * Returns whether item remote identification should be retrieved.
322 *
323 * @see setFetchRemoteIdentification()
324 * @since 4.12
325 */
326 bool fetchRemoteIdentification() const;
327
328 /**
329 * Fetch tags for items.
330 *
331 * The fetched tags have only the Tag::id() set and need to be fetched first to access further attributes.
332 *
333 * The default is @c false.
334 *
335 * @param fetchTags whether or not to load tags.
336 * @since 4.13
337 */
338 void setFetchTags(bool fetchTags);
339
340 /**
341 * Returns whether tags should be retrieved.
342 *
343 * @see setFetchTags()
344 * @since 4.13
345 */
346 bool fetchTags() const;
347
348 /**
349 * Returns whether to fetch list of virtual collections the item is linked to
350 *
351 * @param fetchVRefs whether or not to fetch virtualc references
352 * @since 4.14
353 */
354 void setFetchVirtualReferences(bool fetchVRefs);
355
356 /**
357 * Returns whether virtual references should be retrieved.
358 *
359 * @see setFetchVirtualReferences()
360 * @since 4.14
361 */
362 bool fetchVirtualReferences() const;
363
364private:
365 //@cond PRIVATE
366 QSharedDataPointer<ItemFetchScopePrivate> d;
367 //@endcond
368};
369
370}
371
372Q_DECLARE_METATYPE(Akonadi::ItemFetchScope)
373
374#endif
375