1 | /* |
2 | Copyright (c) 2008 Kevin Krammer <kevin.krammer@gmx.at> |
3 | |
4 | This library is free software; you can redistribute it and/or modify it |
5 | under the terms of the GNU Library General Public License as published by |
6 | the Free Software Foundation; either version 2 of the License, or (at your |
7 | option) any later version. |
8 | |
9 | This library is distributed in the hope that it will be useful, but WITHOUT |
10 | ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
11 | FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public |
12 | License for more details. |
13 | |
14 | You should have received a copy of the GNU Library General Public License |
15 | along with this library; see the file COPYING.LIB. If not, write to the |
16 | Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA |
17 | 02110-1301, USA. |
18 | */ |
19 | |
20 | #ifndef ITEMFETCHSCOPE_H |
21 | #define ITEMFETCHSCOPE_H |
22 | |
23 | #include "akonadi_export.h" |
24 | |
25 | #include <QtCore/QSharedDataPointer> |
26 | #include <KDE/KDateTime> |
27 | |
28 | class QStringList; |
29 | template <typename T> class QSet; |
30 | |
31 | namespace Akonadi { |
32 | |
33 | class ItemFetchScopePrivate; |
34 | |
35 | /** |
36 | * @short Specifies which parts of an item should be fetched from the Akonadi storage. |
37 | * |
38 | * When items are fetched from server either by using ItemFetchJob explicitly or |
39 | * when it is being used internally by other classes, e.g. ItemModel, the scope |
40 | * of the fetch operation can be tailored to the application's current needs. |
41 | * |
42 | * There are two supported ways of changing the currently active ItemFetchScope |
43 | * of classes: |
44 | * - in-place: modify the ItemFetchScope object the other class holds as a member |
45 | * - replace: replace the other class' member with a new scope object |
46 | * |
47 | * Example: modifying an ItemFetchJob's scope @c in-place |
48 | * @code |
49 | * Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob( collection ); |
50 | * job->fetchScope().fetchFullPayload(); |
51 | * job->fetchScope().fetchAttribute<MyAttribute>(); |
52 | * @endcode |
53 | * |
54 | * Example: @c replacing an ItemFetchJob's scope |
55 | * @code |
56 | * Akonadi::ItemFetchScope scope; |
57 | * scope.fetchFullPayload(); |
58 | * scope.fetchAttribute<MyAttribute>(); |
59 | * |
60 | * Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob( collection ); |
61 | * job->setFetchScope( scope ); |
62 | * @endcode |
63 | * |
64 | * This class is implicitly shared. |
65 | * |
66 | * @author Kevin Krammer <kevin.krammer@gmx.at> |
67 | */ |
68 | class AKONADI_EXPORT ItemFetchScope |
69 | { |
70 | public: |
71 | /** |
72 | * Describes the ancestor retrieval depth. |
73 | * @since 4.4 |
74 | */ |
75 | enum AncestorRetrieval { |
76 | None, ///< No ancestor retrieval at all (the default) |
77 | Parent, ///< Only retrieve the immediate parent collection |
78 | All ///< Retrieve all ancestors, up to Collection::root() |
79 | }; |
80 | |
81 | /** |
82 | * Creates an empty item fetch scope. |
83 | * |
84 | * Using an empty scope will only fetch the very basic meta data of items, |
85 | * e.g. local id, remote id and mime type |
86 | */ |
87 | ItemFetchScope(); |
88 | |
89 | /** |
90 | * Creates a new item fetch scope from an @p other. |
91 | */ |
92 | ItemFetchScope(const ItemFetchScope &other); |
93 | |
94 | /** |
95 | * Destroys the item fetch scope. |
96 | */ |
97 | ~ItemFetchScope(); |
98 | |
99 | /** |
100 | * Assigns the @p other to this scope and returns a reference to this scope. |
101 | */ |
102 | ItemFetchScope &operator=(const ItemFetchScope &other); |
103 | |
104 | /** |
105 | * Returns the payload parts that should be fetched. |
106 | * |
107 | * @see fetchPayloadPart() |
108 | */ |
109 | QSet<QByteArray> payloadParts() const; |
110 | |
111 | /** |
112 | * Sets which payload parts shall be fetched. |
113 | * |
114 | * @param part The payload part identifier. |
115 | * Valid values depend on the item type. |
116 | * @param fetch @c true to fetch this part, @c false otherwise. |
117 | */ |
118 | void fetchPayloadPart(const QByteArray &part, bool fetch = true); |
119 | |
120 | /** |
121 | * Returns whether the full payload should be fetched. |
122 | * |
123 | * @see fetchFullPayload() |
124 | */ |
125 | bool fullPayload() const; |
126 | |
127 | /** |
128 | * Sets whether the full payload shall be fetched. |
129 | * The default is @c false. |
130 | * |
131 | * @param fetch @c true if the full payload should be fetched, @c false otherwise. |
132 | */ |
133 | void fetchFullPayload(bool fetch = true); |
134 | |
135 | /** |
136 | * Returns all explicitly fetched attributes. |
137 | * |
138 | * Undefined if fetchAllAttributes() returns true. |
139 | * |
140 | * @see fetchAttribute() |
141 | */ |
142 | QSet<QByteArray> attributes() const; |
143 | |
144 | /** |
145 | * Sets whether the attribute of the given @p type should be fetched. |
146 | * |
147 | * @param type The attribute type to fetch. |
148 | * @param fetch @c true if the attribute should be fetched, @c false otherwise. |
149 | */ |
150 | void fetchAttribute(const QByteArray &type, bool fetch = true); |
151 | |
152 | /** |
153 | * Sets whether the attribute of the requested type should be fetched. |
154 | * |
155 | * @param fetch @c true if the attribute should be fetched, @c false otherwise. |
156 | */ |
157 | template <typename T> inline void fetchAttribute(bool fetch = true) |
158 | { |
159 | T dummy; |
160 | fetchAttribute(dummy.type(), fetch); |
161 | } |
162 | |
163 | /** |
164 | * Returns whether all available attributes should be fetched. |
165 | * |
166 | * @see fetchAllAttributes() |
167 | */ |
168 | bool allAttributes() const; |
169 | |
170 | /** |
171 | * Sets whether all available attributes should be fetched. |
172 | * The default is @c false. |
173 | * |
174 | * @param fetch @c true if all available attributes should be fetched, @c false otherwise. |
175 | */ |
176 | void fetchAllAttributes(bool fetch = true); |
177 | |
178 | /** |
179 | * Returns whether payload data should be requested from remote sources or just |
180 | * from the local cache. |
181 | * |
182 | * @see setCacheOnly() |
183 | */ |
184 | bool cacheOnly() const; |
185 | |
186 | /** |
187 | * Sets whether payload data should be requested from remote sources or just |
188 | * from the local cache. |
189 | * |
190 | * @param cacheOnly @c true if no remote data should be requested, |
191 | * @c false otherwise (the default). |
192 | */ |
193 | void setCacheOnly(bool cacheOnly); |
194 | |
195 | /** |
196 | * Sets whether payload will be fetched or there will be only a test performed if the |
197 | * requested payload is in the cache. Calling it calls @see setCacheOnly with true automatically. |
198 | * Default is fetching the data. |
199 | * |
200 | * @since 4.11 |
201 | */ |
202 | void setCheckForCachedPayloadPartsOnly(bool check = true); |
203 | |
204 | /** |
205 | * Returns whether payload data should be fetched or only checked for presence in the cache. |
206 | * |
207 | * @see setCheckForCachedPayloadPartsOnly() |
208 | * |
209 | * @since 4.11 |
210 | */ |
211 | bool checkForCachedPayloadPartsOnly() const; |
212 | |
213 | /** |
214 | * Sets how many levels of ancestor collections should be included in the retrieval. |
215 | * The default is AncestorRetrieval::None. |
216 | * |
217 | * @param ancestorDepth The desired ancestor retrieval depth. |
218 | * @since 4.4 |
219 | */ |
220 | void setAncestorRetrieval(AncestorRetrieval ancestorDepth); |
221 | |
222 | /** |
223 | * Returns the ancestor retrieval depth. |
224 | * |
225 | * @see setAncestorRetrieval() |
226 | * @since 4.4 |
227 | */ |
228 | AncestorRetrieval ancestorRetrieval() const; |
229 | |
230 | /** |
231 | * Enables retrieval of the item modification time. |
232 | * This is enabled by default for backward compatibility reasons. |
233 | * |
234 | * @param retrieveMtime @c true to retrieve the modification time, @c false otherwise |
235 | * @since 4.6 |
236 | */ |
237 | void setFetchModificationTime(bool retrieveMtime); |
238 | |
239 | /** |
240 | * Returns whether item modification time should be retrieved. |
241 | * |
242 | * @see setFetchModificationTime() |
243 | * @since 4.6 |
244 | */ |
245 | bool fetchModificationTime() const; |
246 | |
247 | /** |
248 | * Enables retrieval of the item GID. |
249 | * This is disabled by default. |
250 | * |
251 | * @param retrieveGID @c true to retrieve the GID, @c false otherwise |
252 | * @since 4.12 |
253 | */ |
254 | void setFetchGid(bool retrieveGID); |
255 | |
256 | /** |
257 | * Returns whether item GID should be retrieved. |
258 | * |
259 | * @see setFetchGid() |
260 | * @since 4.12 |
261 | */ |
262 | bool fetchGid() const; |
263 | |
264 | /** |
265 | * Ignore retrieval errors while fetching items, and always deliver what is available. |
266 | * If items have missing parts and the part can't be retrieved from the resource (i.e. because the system is offline), |
267 | * the fetch job would normally just fail. By setting this flag, the errors are ignored, |
268 | * and all items which could be fetched completely are returned. |
269 | * Note that all items that are returned are completely fetched, and incomplete items are simply ignored. |
270 | * This flag is useful for displaying everything that is available, where it is not crucial to have all items. |
271 | * Never use this for things like data migration or alike. |
272 | * |
273 | * @since 4.10 |
274 | */ |
275 | void setIgnoreRetrievalErrors(bool enabled); |
276 | |
277 | /** |
278 | * Returns whether retrieval errors should be ignored. |
279 | * |
280 | * @see setIgnoreRetrievalErrors() |
281 | * @since 4.10 |
282 | */ |
283 | bool ignoreRetrievalErrors() const; |
284 | |
285 | /** |
286 | * Returns @c true if there is nothing to fetch. |
287 | */ |
288 | bool isEmpty() const; |
289 | |
290 | /** |
291 | * Only fetch items that were added or modified after given timestamp |
292 | * |
293 | * When this property is set, all results are filtered, i.e. even when you |
294 | * request an item with a specific ID, it will not be fetched unless it was |
295 | * modified after @p changedSince timestamp. |
296 | * |
297 | * @param changedSince The timestamp of oldest modified item to fetch |
298 | * @since 4.11 |
299 | */ |
300 | void setFetchChangedSince(const KDateTime &changedSince); |
301 | |
302 | /** |
303 | * Returns timestamp of the oldest item to fetch. |
304 | */ |
305 | KDateTime fetchChangedSince() const; |
306 | |
307 | /** |
308 | * Fetch remote identification for items. |
309 | * |
310 | * These include Akonadi::Item::remoteId() and Akonadi::Item::remoteRevision(). This should |
311 | * be off for normal clients usually, to save memory (not to mention normal clients should |
312 | * not be concerned with these information anyway). It is however crucial for resource agents. |
313 | * For backward compatibility the default is @c true. |
314 | * |
315 | * @param retrieveRid whether or not to load remote identification. |
316 | * @since 4.12 |
317 | */ |
318 | void setFetchRemoteIdentification(bool retrieveRid); |
319 | |
320 | /** |
321 | * Returns whether item remote identification should be retrieved. |
322 | * |
323 | * @see setFetchRemoteIdentification() |
324 | * @since 4.12 |
325 | */ |
326 | bool fetchRemoteIdentification() const; |
327 | |
328 | /** |
329 | * Fetch tags for items. |
330 | * |
331 | * The fetched tags have only the Tag::id() set and need to be fetched first to access further attributes. |
332 | * |
333 | * The default is @c false. |
334 | * |
335 | * @param fetchTags whether or not to load tags. |
336 | * @since 4.13 |
337 | */ |
338 | void setFetchTags(bool fetchTags); |
339 | |
340 | /** |
341 | * Returns whether tags should be retrieved. |
342 | * |
343 | * @see setFetchTags() |
344 | * @since 4.13 |
345 | */ |
346 | bool fetchTags() const; |
347 | |
348 | /** |
349 | * Returns whether to fetch list of virtual collections the item is linked to |
350 | * |
351 | * @param fetchVRefs whether or not to fetch virtualc references |
352 | * @since 4.14 |
353 | */ |
354 | void setFetchVirtualReferences(bool fetchVRefs); |
355 | |
356 | /** |
357 | * Returns whether virtual references should be retrieved. |
358 | * |
359 | * @see setFetchVirtualReferences() |
360 | * @since 4.14 |
361 | */ |
362 | bool fetchVirtualReferences() const; |
363 | |
364 | private: |
365 | //@cond PRIVATE |
366 | QSharedDataPointer<ItemFetchScopePrivate> d; |
367 | //@endcond |
368 | }; |
369 | |
370 | } |
371 | |
372 | Q_DECLARE_METATYPE(Akonadi::ItemFetchScope) |
373 | |
374 | #endif |
375 | |