1/*
2 Copyright (c) 2008 Kevin Krammer <kevin.krammer@gmx.at>
3 Copyright (c) 2009 Volker Krause <vkrause@kde.org>
4
5 This library is free software; you can redistribute it and/or modify it
6 under the terms of the GNU Library General Public License as published by
7 the Free Software Foundation; either version 2 of the License, or (at your
8 option) any later version.
9
10 This library is distributed in the hope that it will be useful, but WITHOUT
11 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13 License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18 02110-1301, USA.
19*/
20
21#ifndef AKONADI_COLLECTIONFETCHSCOPE_H
22#define AKONADI_COLLECTIONFETCHSCOPE_H
23
24#include "akonadi_export.h"
25
26#include <QtCore/QSharedDataPointer>
27
28class QStringList;
29
30namespace Akonadi {
31
32class CollectionFetchScopePrivate;
33
34/**
35 * @short Specifies which parts of a collection should be fetched from the Akonadi storage.
36 *
37 * When collections are fetched from the server either by using CollectionFetchJob
38 * explicitly or when it is being used internally by other classes, e.g. Akonadi::Monitor,
39 * the scope of the fetch operation can be tailored to the application's current needs.
40 *
41 * Note that CollectionFetchScope always includes fetching collection attributes.
42 *
43 * There are two supported ways of changing the currently active CollectionFetchScope
44 * of classes:
45 * - in-place: modify the CollectionFetchScope object the other class holds as a member
46 * - replace: replace the other class' member with a new scope object
47 *
48 * Example: modifying a CollectionFetchJob's scope @c in-place
49 * @code
50 * Akonadi::CollectionFetchJob *job = new Akonadi::CollectionFetchJob( collection );
51 * job->fetchScope().setIncludeUnsubscribed( true );
52 * @endcode
53 *
54 * Example: @c replacing a CollectionFetchJob's scope
55 * @code
56 * Akonadi::CollectionFetchScope scope;
57 * scope.setIncludeUnsubscribed( true );
58 *
59 * Akonadi::CollectionFetchJob *job = new Akonadi::CollectionFetchJob( collection );
60 * job->setFetchScope( scope );
61 * @endcode
62 *
63 * This class is implicitly shared.
64 *
65 * @author Volker Krause <vkrause@kde.org>
66 * @since 4.4
67 */
68class AKONADI_EXPORT CollectionFetchScope
69{
70public:
71 /**
72 * Describes the ancestor retrieval depth.
73 */
74 enum AncestorRetrieval {
75 None, ///< No ancestor retrieval at all (the default)
76 Parent, ///< Only retrieve the immediate parent collection
77 All ///< Retrieve all ancestors, up to Collection::root()
78 };
79
80 /**
81 * Creates an empty collection fetch scope.
82 *
83 * Using an empty scope will only fetch the very basic meta data of collections,
84 * e.g. local id, remote id and content mimetypes.
85 */
86 CollectionFetchScope();
87
88 /**
89 * Creates a new collection fetch scope from an @p other.
90 */
91 CollectionFetchScope(const CollectionFetchScope &other);
92
93 /**
94 * Destroys the collection fetch scope.
95 */
96 ~CollectionFetchScope();
97
98 /**
99 * Assigns the @p other to this scope and returns a reference to this scope.
100 */
101 CollectionFetchScope &operator=(const CollectionFetchScope &other);
102
103 /**
104 * Returns whether unsubscribed collection should be included.
105 *
106 * @deprecated Use includeUnsubscribed()
107 */
108 AKONADI_DEPRECATED bool includeUnubscribed() const;
109
110 /**
111 * Returns whether unsubscribed collection should be included.
112 *
113 * @see setIncludeUnsubscribed()
114 * @since 4.5
115 * @deprecated use listFilter() instead
116 */
117 AKONADI_DEPRECATED bool includeUnsubscribed() const;
118
119 /**
120 * Sets whether unsubscribed collections should be included in the collection listing.
121 *
122 * @param include @c true to include unsubscribed collections, @c false otherwise (the default).
123 * @deprecated use setListFilter() instead
124 */
125 AKONADI_DEPRECATED void setIncludeUnsubscribed(bool include);
126
127 /**
128 * Describes the list filter
129 *
130 * @since 4.14
131 */
132 enum ListFilter {
133 NoFilter, ///< No filtering, retrieve all collections
134 Display, ///< Only retrieve collections for display, taking the local preference and enabled into account.
135 Sync, ///< Only retrieve collections for synchronization, taking the local preference and enabled into account.
136 Index, ///< Only retrieve collections for indxing, taking the local preference and enabled into account.
137 Enabled ///< Only retrieve enabled collections, ignoring the local preference. This is the same as setIncludeUnsubscribed(false).
138 };
139
140 /**
141 * Sets a filter for the collections to be listed.
142 *
143 * Note that collections that do not match the filter are included if required to complete the tree.
144 *
145 * @since 4.14
146 */
147 void setListFilter(ListFilter);
148
149 /**
150 * Returns the list filter.
151 *
152 * @see setListFilter()
153 * @since 4.14
154 */
155 ListFilter listFilter() const;
156
157 /**
158 * Returns whether collection statistics should be included in the retrieved results.
159 *
160 * @see setIncludeStatistics()
161 */
162 bool includeStatistics() const;
163
164 /**
165 * Sets whether collection statistics should be included in the retrieved results.
166 *
167 * @param include @c true to include collction statistics, @c false otherwise (the default).
168 */
169 void setIncludeStatistics(bool include);
170
171 /**
172 * Returns the resource identifier that is used as filter.
173 *
174 * @see setResource()
175 */
176 QString resource() const;
177
178 /**
179 * Sets a resource filter, that is only collections owned by the specified resource are
180 * retrieved.
181 *
182 * @param resource The resource identifier.
183 */
184 void setResource(const QString &resource);
185
186 /**
187 * Sets a content mimetypes filter, that is only collections that contain at least one of the
188 * given mimetypes (or their parents) are retrieved.
189 *
190 * @param mimeTypes A list of mime types
191 */
192 void setContentMimeTypes(const QStringList &mimeTypes);
193
194 /**
195 * Returns the content mimetypes filter.
196 *
197 * @see setContentMimeTypes()
198 */
199 QStringList contentMimeTypes() const;
200
201 /**
202 * Sets how many levels of ancestor collections should be included in the retrieval.
203 *
204 * Only the ID and the remote ID of the ancestor collections are fetched. If
205 * you want more information about the ancestor collections, like their name,
206 * you will need to do an additional CollectionFetchJob for them.
207 *
208 * @param ancestorDepth The desired ancestor retrieval depth.
209 */
210 void setAncestorRetrieval(AncestorRetrieval ancestorDepth);
211
212 /**
213 * Returns the ancestor retrieval depth.
214 *
215 * @see setAncestorRetrieval()
216 */
217 AncestorRetrieval ancestorRetrieval() const;
218
219 /**
220 * Returns @c true if there is nothing to fetch.
221 */
222 bool isEmpty() const;
223
224private:
225 //@cond PRIVATE
226 QSharedDataPointer<CollectionFetchScopePrivate> d;
227 //@endcond
228};
229
230}
231
232#endif
233