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
29namespace Akonadi {
30
31class ItemFetchScope;
32class ItemSearchJobPrivate;
33class 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 */
67class AKONADI_EXPORT ItemSearchJob : public Job
68{
69 Q_OBJECT
70
71public:
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
243Q_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
255protected:
256 void doStart();
257 virtual void doHandleResponse(const QByteArray &tag, const QByteArray &data);
258
259private:
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