Akonadi

collectionfetchscope.h
1/*
2 SPDX-FileCopyrightText: 2008 Kevin Krammer <kevin.krammer@gmx.at>
3 SPDX-FileCopyrightText: 2009 Volker Krause <vkrause@kde.org>
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
17namespace Akonadi
18{
19class 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 <vkrause@kde.org>
53 * @since 4.4
54 */
55class AKONADICORE_EXPORT CollectionFetchScope
56{
57public:
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 */
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 [[nodiscard]] ListFilter listFilter() const;
119
120 /**
121 * Returns whether collection statistics should be included in the retrieved results.
122 *
123 * @see setIncludeStatistics()
124 */
125 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] 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 [[nodiscard]] bool ignoreRetrievalErrors() const;
259
260 /**
261 * Returns @c true if there is nothing to fetch.
262 */
263 [[nodiscard]] bool isEmpty() const;
264
265private:
266 /// @cond PRIVATE
268 /// @endcond
269};
270
271}
Specifies which parts of a collection should be fetched from the Akonadi storage.
void fetchAttribute(bool fetch=true)
Sets whether the attribute of the requested type should be fetched.
ListFilter
Describes the list filter.
@ NoFilter
No filtering, retrieve all collections.
@ Index
Only retrieve collections for indexing, taking the local preference and enabled into account.
@ Display
Only retrieve collections for display, taking the local preference and enabled into account.
@ Sync
Only retrieve collections for synchronization, taking the local preference and enabled into account.
AncestorRetrieval
Describes the ancestor retrieval depth.
@ Parent
Only retrieve the immediate parent collection.
@ 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-2024 The KDE developers.
Generated on Fri May 17 2024 11:54:40 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.