Akonadi

itemfetchscope.h
1 /*
2  SPDX-FileCopyrightText: 2008 Kevin Krammer <[email protected]>
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 
16 template<typename T>
17 class QSet;
18 
19 namespace Akonadi
20 {
21 class ItemFetchScopePrivate;
22 class 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 <[email protected]>
56  */
57 class AKONADICORE_EXPORT ItemFetchScope
58 {
59 public:
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  */
81  ItemFetchScope(const ItemFetchScope &other);
82 
83  /**
84  * Destroys the item fetch scope.
85  */
86  ~ItemFetchScope();
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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT bool ignoreRetrievalErrors() const;
274 
275  /**
276  * Returns @c true if there is nothing to fetch.
277  */
278  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT bool fetchVirtualReferences() const;
396 
397  /**
398  * Fetch relations for items.
399  *
400  * The default is @c false.
401  *
402  * @param fetchRelations whether or not to load relations.
403  * @since 4.15
404  */
405  void setFetchRelations(bool fetchRelations);
406 
407  /**
408  * Returns whether relations should be retrieved.
409  *
410  * @see setFetchRelations()
411  * @since 4.15
412  */
413  Q_REQUIRED_RESULT bool fetchRelations() const;
414 
415 private:
416  /// @cond PRIVATE
418  /// @endcond
419 };
420 
421 }
422 
423 Q_DECLARE_METATYPE(Akonadi::ItemFetchScope)
AncestorRetrieval
Describes the ancestor retrieval depth.
Specifies which parts of a tag should be fetched from the Akonadi storage.
Definition: tagfetchscope.h:22
void fetchAttribute(bool fetch=true)
Sets whether the attribute of the requested type should be fetched.
@ None
No ancestor retrieval at all (the default)
Specifies which parts of an item should be fetched from the Akonadi storage.
@ Parent
Only retrieve the immediate parent collection.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 04:01:19 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.