1 | /* |
2 | Copyright (c) 2009 Tobias Koenig <tokoe@kde.org> |
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 AKONADI_ITEMSEARCHJOB_H |
21 | #define AKONADI_ITEMSEARCHJOB_H |
22 | |
23 | #include <akonadi/item.h> |
24 | #include <akonadi/job.h> |
25 | #include <akonadi/collection.h> |
26 | |
27 | #include <QtCore/QUrl> |
28 | |
29 | namespace Akonadi { |
30 | |
31 | class ItemFetchScope; |
32 | class ItemSearchJobPrivate; |
33 | class SearchQuery; |
34 | |
35 | /** |
36 | * @short Job that searches for items in the Akonadi storage. |
37 | * |
38 | * This job searches for items that match a given search query and returns |
39 | * the list of matching item. |
40 | * |
41 | * @code |
42 | * |
43 | * SearchQuery query; |
44 | * query.addTerm( SearchTerm( "From", "user1@domain.example", SearchTerm::CondEqual ) ); |
45 | * query.addTerm( SearchTerm( "Date", QDateTime( QDate( 2014, 01, 27 ), QTime( 00, 00, 00 ) ), SearchTerm::CondGreaterThan ); |
46 | * |
47 | * Akonadi::ItemSearchJob *job = new Akonadi::ItemSearchJob( query ); |
48 | * job->fetchScope().fetchFullPayload(); |
49 | * connect( job, SIGNAL(result(KJob*)), this, SLOT(searchResult(KJob*)) ); |
50 | * |
51 | * ... |
52 | * |
53 | * MyClass::searchResult( KJob *job ) |
54 | * { |
55 | * Akonadi::ItemSearchJob *searchJob = qobject_cast<Akonadi::ItemSearchJob*>( job ); |
56 | * const Akonadi::Item::List items = searchJob->items(); |
57 | * foreach ( const Akonadi::Item &item, items ) { |
58 | * // extract the payload and do further stuff |
59 | * } |
60 | * } |
61 | * |
62 | * @endcode |
63 | * |
64 | * @author Tobias Koenig <tokoe@kde.org> |
65 | * @since 4.4 |
66 | */ |
67 | class AKONADI_EXPORT ItemSearchJob : public Job |
68 | { |
69 | Q_OBJECT |
70 | |
71 | public: |
72 | /** |
73 | * Creates an item search job. |
74 | * |
75 | * @param query The search query in raw Akonadi search metalanguage format (JSON) |
76 | * @param parent The parent object. |
77 | * @deprecated Deprecated as of 4.13. Use SearchQuery instead. |
78 | */ |
79 | explicit AKONADI_DEPRECATED ItemSearchJob(const QString &query, QObject *parent = 0); |
80 | |
81 | /** |
82 | * Creates an item search job. |
83 | * |
84 | * @param query The search query. |
85 | * @param parent The parent object. |
86 | * @since 4.13 |
87 | */ |
88 | explicit ItemSearchJob(const SearchQuery &query, QObject *parent = 0); |
89 | |
90 | /** |
91 | * Destroys the item search job. |
92 | */ |
93 | ~ItemSearchJob(); |
94 | |
95 | /** |
96 | * Sets the search @p query in Akonadi search metalanguage format (JSON) |
97 | * |
98 | * @deprecated Deprecated as of 4.13. Use SearchQuery instead. |
99 | */ |
100 | void AKONADI_DEPRECATED setQuery(const QString &query); |
101 | |
102 | /** |
103 | * Sets the search @p query. |
104 | * |
105 | * @since 4.13 |
106 | */ |
107 | void setQuery(const SearchQuery &query); |
108 | |
109 | /** |
110 | * Sets the item fetch scope. |
111 | * |
112 | * The ItemFetchScope controls how much of an matching item's data is fetched |
113 | * from the server, e.g. whether to fetch the full item payload or |
114 | * only meta data. |
115 | * |
116 | * @param fetchScope The new scope for item fetch operations. |
117 | * |
118 | * @see fetchScope() |
119 | */ |
120 | void setFetchScope(const ItemFetchScope &fetchScope); |
121 | |
122 | /** |
123 | * Returns the item fetch scope. |
124 | * |
125 | * Since this returns a reference it can be used to conveniently modify the |
126 | * current scope in-place, i.e. by calling a method on the returned reference |
127 | * without storing it in a local variable. See the ItemFetchScope documentation |
128 | * for an example. |
129 | * |
130 | * @return a reference to the current item fetch scope |
131 | * |
132 | * @see setFetchScope() for replacing the current item fetch scope |
133 | */ |
134 | ItemFetchScope &fetchScope(); |
135 | |
136 | /** |
137 | * Returns the items that matched the search query. |
138 | */ |
139 | Item::List items() const; |
140 | |
141 | /** |
142 | * Returns an URI that represents a predicate that is always added to the Nepomuk resource |
143 | * by the Akonadi Nepomuk feeders. |
144 | * |
145 | * The statement containing this predicate has the Akonadi Item ID of the resource as string |
146 | * as the object, and the Nepomuk resource, e.g. a PersonContact, as the subject. |
147 | * |
148 | * Always limit your searches to statements that contain this URI as predicate. |
149 | * |
150 | * @since 4.4.3 |
151 | * @deprecated Deprecated as of 4.13, where SPARQL queries were replaced by Baloo |
152 | */ |
153 | static AKONADI_DEPRECATED QUrl akonadiItemIdUri(); |
154 | |
155 | /** |
156 | * Search only for items of given mime types. |
157 | * |
158 | * @since 4.13 |
159 | */ |
160 | void setMimeTypes(const QStringList &mimeTypes); |
161 | |
162 | /** |
163 | * Returns list of mime types to search in |
164 | * |
165 | * @since 4.13 |
166 | */ |
167 | QStringList mimeTypes() const; |
168 | |
169 | /** |
170 | * Search only in given collections. |
171 | * |
172 | * When recursive search is enabled, all child collections of each specified |
173 | * collection will be searched too |
174 | * |
175 | * By default all collections are be searched. |
176 | * |
177 | * @param collections Collections to search |
178 | * @since 4.13 |
179 | */ |
180 | void setSearchCollections(const Collection::List &collections); |
181 | |
182 | /** |
183 | * Returns list of collections to search. |
184 | * |
185 | * This list does not include child collections that will be searched when |
186 | * recursive search is enabled |
187 | * |
188 | * @since 4.13 |
189 | */ |
190 | Collection::List searchCollections() const; |
191 | |
192 | /** |
193 | * Sets whether the search should recurse into collections |
194 | * |
195 | * When set to true, all child collections of the specific collections will |
196 | * be search recursively. |
197 | * |
198 | * @param recursive Whether to search recursively |
199 | * @since 4.13 |
200 | */ |
201 | void setRecursive(bool recursive); |
202 | |
203 | /** |
204 | * Returns whether the search is recursive |
205 | * |
206 | * @since 4.13 |
207 | */ |
208 | bool isRecursive() const; |
209 | |
210 | /** |
211 | * Sets whether resources should be queried too. |
212 | * |
213 | * When set to true, Akonadi will search local indexed items and will also |
214 | * query resources that support server-side search, to forward the query |
215 | * to remote storage (for example using SEARCH feature on IMAP servers) and |
216 | * merge their results with results from local index. |
217 | * |
218 | * This is useful especially when searching resources, that don't fetch full |
219 | * payload by default, for example the IMAP resource, which only fetches headers |
220 | * by default and the body is fetched on demand, which means that emails that |
221 | * were not yet fully fetched cannot be indexed in local index, and thus cannot |
222 | * be searched. With remote search, even those emails can be included in search |
223 | * results. |
224 | * |
225 | * This feature is disabled by default. |
226 | * |
227 | * Results are streamed back to client as they are received from queried sources, |
228 | * so this job can take some time to finish, but will deliver initial results |
229 | * from local index fairly quickly. |
230 | * |
231 | * @param enabled Whether remote search is enabled |
232 | * @since 4.13 |
233 | */ |
234 | void setRemoteSearchEnabled(bool enabled); |
235 | |
236 | /** |
237 | * Returns whether remote search is enabled. |
238 | * |
239 | * @since 4.13 |
240 | */ |
241 | bool isRemoteSearchEnabled() const; |
242 | |
243 | Q_SIGNALS: |
244 | /** |
245 | * This signal is emitted whenever new matching items have been fetched completely. |
246 | * |
247 | * @note This is an optimization, instead of waiting for the end of the job |
248 | * and calling items(), you can connect to this signal and get the items |
249 | * incrementally. |
250 | * |
251 | * @param items The matching items. |
252 | */ |
253 | void itemsReceived(const Akonadi::Item::List &items); |
254 | |
255 | protected: |
256 | void doStart(); |
257 | virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data); |
258 | |
259 | private: |
260 | //@cond PRIVATE |
261 | Q_DECLARE_PRIVATE(ItemSearchJob) |
262 | |
263 | Q_PRIVATE_SLOT(d_func(), void timeout()) |
264 | //@endcond |
265 | }; |
266 | |
267 | } |
268 | |
269 | #endif |
270 | |