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 | |
28 | class QStringList; |
29 | |
30 | namespace Akonadi { |
31 | |
32 | class 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 | */ |
68 | class AKONADI_EXPORT CollectionFetchScope |
69 | { |
70 | public: |
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 | |
224 | private: |
225 | //@cond PRIVATE |
226 | QSharedDataPointer<CollectionFetchScopePrivate> d; |
227 | //@endcond |
228 | }; |
229 | |
230 | } |
231 | |
232 | #endif |
233 | |