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 
No ancestor retrieval at all (the default)
Specifies which parts of a tag should be fetched from the Akonadi storage.
Definition: tagfetchscope.h:20
AncestorRetrieval
Describes the ancestor retrieval depth.
Only retrieve the immediate parent collection.
void fetchAttribute(bool fetch=true)
Sets whether the attribute of the requested type should be fetched.
Specifies which parts of an item should be fetched from the Akonadi storage.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Tue Aug 3 2021 23:17:55 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.