Akonadi

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

KDE's Doxygen guidelines are available online.