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

KDE's Doxygen guidelines are available online.