Akonadi

collectionfetchscope.h
1 /*
2  SPDX-FileCopyrightText: 2008 Kevin Krammer <[email protected]>
3  SPDX-FileCopyrightText: 2009 Volker Krause <[email protected]>
4 
5  SPDX-License-Identifier: LGPL-2.0-or-later
6 */
7 
8 #pragma once
9 
10 #include "akonadicore_export.h"
11 
12 #include <QSet>
13 #include <QSharedDataPointer>
14 
15 #include <QStringList>
16 
17 namespace Akonadi
18 {
19 class CollectionFetchScopePrivate;
20 
21 /**
22  * @short Specifies which parts of a collection should be fetched from the Akonadi storage.
23  *
24  * When collections are fetched from the server either by using CollectionFetchJob
25  * explicitly or when it is being used internally by other classes, e.g. Akonadi::Monitor,
26  * the scope of the fetch operation can be tailored to the application's current needs.
27  *
28  * Note that CollectionFetchScope always includes fetching collection attributes.
29  *
30  * There are two supported ways of changing the currently active CollectionFetchScope
31  * of classes:
32  * - in-place: modify the CollectionFetchScope object the other class holds as a member
33  * - replace: replace the other class' member with a new scope object
34  *
35  * Example: modifying a CollectionFetchJob's scope @c in-place
36  * @code
37  * Akonadi::CollectionFetchJob *job = new Akonadi::CollectionFetchJob( collection );
38  * job->fetchScope().setIncludeUnsubscribed( true );
39  * @endcode
40  *
41  * Example: @c replacing a CollectionFetchJob's scope
42  * @code
43  * Akonadi::CollectionFetchScope scope;
44  * scope.setIncludeUnsubscribed( true );
45  *
46  * Akonadi::CollectionFetchJob *job = new Akonadi::CollectionFetchJob( collection );
47  * job->setFetchScope( scope );
48  * @endcode
49  *
50  * This class is implicitly shared.
51  *
52  * @author Volker Krause <[email protected]>
53  * @since 4.4
54  */
55 class AKONADICORE_EXPORT CollectionFetchScope
56 {
57 public:
58  /**
59  * Describes the ancestor retrieval depth.
60  */
62  None, ///< No ancestor retrieval at all (the default)
63  Parent, ///< Only retrieve the immediate parent collection
64  All ///< Retrieve all ancestors, up to Collection::root()
65  };
66 
67  /**
68  * Creates an empty collection fetch scope.
69  *
70  * Using an empty scope will only fetch the very basic meta data of collections,
71  * e.g. local id, remote id and content mimetypes.
72  */
74 
75  /**
76  * Creates a new collection fetch scope from an @p other.
77  */
79 
80  /**
81  * Destroys the collection fetch scope.
82  */
84 
85  /**
86  * Assigns the @p other to this scope and returns a reference to this scope.
87  */
88  CollectionFetchScope &operator=(const CollectionFetchScope &other);
89 
90  /**
91  * Describes the list filter
92  *
93  * @since 4.14
94  */
95  enum ListFilter {
96  NoFilter, ///< No filtering, retrieve all collections
97  Display, ///< Only retrieve collections for display, taking the local preference and enabled into account.
98  Sync, ///< Only retrieve collections for synchronization, taking the local preference and enabled into account.
99  Index, ///< Only retrieve collections for indexing, taking the local preference and enabled into account.
100  Enabled ///< Only retrieve enabled collections, ignoring the local preference.
101  };
102 
103  /**
104  * Sets a filter for the collections to be listed.
105  *
106  * Note that collections that do not match the filter are included if required to complete the tree.
107  *
108  * @since 4.14
109  */
110  void setListFilter(ListFilter);
111 
112  /**
113  * Returns the list filter.
114  *
115  * @see setListFilter()
116  * @since 4.14
117  */
118  Q_REQUIRED_RESULT ListFilter listFilter() const;
119 
120  /**
121  * Returns whether collection statistics should be included in the retrieved results.
122  *
123  * @see setIncludeStatistics()
124  */
125  Q_REQUIRED_RESULT bool includeStatistics() const;
126 
127  /**
128  * Sets whether collection statistics should be included in the retrieved results.
129  *
130  * @param include @c true to include collection statistics, @c false otherwise (the default).
131  */
132  void setIncludeStatistics(bool include);
133 
134  /**
135  * Returns the resource identifier that is used as filter.
136  *
137  * @see setResource()
138  */
139  Q_REQUIRED_RESULT QString resource() const;
140 
141  /**
142  * Sets a resource filter, that is only collections owned by the specified resource are
143  * retrieved.
144  *
145  * @param resource The resource identifier.
146  */
147  void setResource(const QString &resource);
148 
149  /**
150  * Sets a content mimetypes filter, that is only collections that contain at least one of the
151  * given mimetypes (or their parents) are retrieved.
152  *
153  * @param mimeTypes A list of mime types
154  */
155  void setContentMimeTypes(const QStringList &mimeTypes);
156 
157  /**
158  * Returns the content mimetypes filter.
159  *
160  * @see setContentMimeTypes()
161  */
162  Q_REQUIRED_RESULT QStringList contentMimeTypes() const;
163 
164  /**
165  * Sets how many levels of ancestor collections should be included in the retrieval.
166  *
167  * Only the ID and the remote ID of the ancestor collections are fetched. If
168  * you want more information about the ancestor collections, like their name,
169  * you will need to do an additional CollectionFetchJob for them.
170  *
171  * @param ancestorDepth The desired ancestor retrieval depth.
172  */
173  void setAncestorRetrieval(AncestorRetrieval ancestorDepth);
174 
175  /**
176  * Returns the ancestor retrieval depth.
177  *
178  * @see setAncestorRetrieval()
179  */
180  Q_REQUIRED_RESULT AncestorRetrieval ancestorRetrieval() const;
181 
182  /**
183  * Sets the fetch scope for ancestor retrieval.
184  *
185  * @see setAncestorRetrieval()
186  */
187  void setAncestorFetchScope(const CollectionFetchScope &scope);
188 
189  /**
190  * Returns the fetch scope for ancestor retrieval.
191  */
192  Q_REQUIRED_RESULT CollectionFetchScope ancestorFetchScope() const;
193 
194  /**
195  * Returns the fetch scope for ancestor retrieval.
196  */
197  CollectionFetchScope &ancestorFetchScope();
198 
199  /**
200  * Returns all explicitly fetched attributes.
201  *
202  * @see fetchAttribute()
203  */
204  Q_REQUIRED_RESULT QSet<QByteArray> attributes() const;
205 
206  /**
207  * Sets whether the attribute of the given @p type should be fetched.
208  *
209  * @param type The attribute type to fetch.
210  * @param fetch @c true if the attribute should be fetched, @c false otherwise.
211  */
212  void fetchAttribute(const QByteArray &type, bool fetch = true);
213 
214  /**
215  * Sets whether the attribute of the requested type should be fetched.
216  *
217  * @param fetch @c true if the attribute should be fetched, @c false otherwise.
218  */
219  template<typename T>
220  inline void fetchAttribute(bool fetch = true)
221  {
222  T dummy;
223  fetchAttribute(dummy.type(), fetch);
224  }
225 
226  /**
227  * Sets whether only the id or the complete tag should be fetched.
228  *
229  * The default is @c false.
230  *
231  * @since 4.15
232  */
233  void setFetchIdOnly(bool fetchIdOnly);
234 
235  /**
236  * Sets whether only the id of the tags should be retrieved or the complete tag.
237  *
238  * @see tagFetchScope()
239  * @since 4.15
240  */
241  Q_REQUIRED_RESULT bool fetchIdOnly() const;
242 
243  /**
244  * Ignore retrieval errors while fetching collections, and always deliver what is available.
245  *
246  * This flag is useful to fetch a list of collections, where some might no longer be available.
247  *
248  * @since KF6
249  */
250  void setIgnoreRetrievalErrors(bool enabled);
251 
252  /**
253  * Returns whether retrieval errors should be ignored.
254  *
255  * @see setIgnoreRetrievalErrors()
256  * @since KF6
257  */
258  Q_REQUIRED_RESULT bool ignoreRetrievalErrors() const;
259 
260  /**
261  * Returns @c true if there is nothing to fetch.
262  */
263  Q_REQUIRED_RESULT bool isEmpty() const;
264 
265 private:
266  /// @cond PRIVATE
268  /// @endcond
269 };
270 
271 }
@ Parent
Only retrieve the immediate parent collection.
@ Sync
Only retrieve collections for synchronization, taking the local preference and enabled into account.
void fetchAttribute(bool fetch=true)
Sets whether the attribute of the requested type should be fetched.
@ Display
Only retrieve collections for display, taking the local preference and enabled into account.
@ NoFilter
No filtering, retrieve all collections.
Specifies which parts of a collection should be fetched from the Akonadi storage.
ListFilter
Describes the list filter.
@ Index
Only retrieve collections for indexing, taking the local preference and enabled into account.
AncestorRetrieval
Describes the ancestor retrieval depth.
@ None
No ancestor retrieval at all (the default)
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 22 2023 03:51:42 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.