1/*
2 Copyright (c) 2007 Volker Krause <vkrause@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_SEARCHCREATEJOB_H
21#define AKONADI_SEARCHCREATEJOB_H
22
23#include <akonadi/job.h>
24#include "collection.h"
25
26namespace Akonadi {
27
28class Collection;
29class SearchQuery;
30class SearchCreateJobPrivate;
31
32/**
33 * @short Job that creates a virtual/search collection in the Akonadi storage.
34 *
35 * This job creates so called virtual or search collections, which don't contain
36 * real data, but references to items that match a given search query.
37 *
38 * @code
39 *
40 * const QString name = "My search folder";
41 * const QString query = "...";
42 *
43 * Akonadi::SearchCreateJob *job = new Akonadi::SearchCreateJob( name, query );
44 * connect( job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*)) );
45 *
46 * MyClass::jobFinished( KJob *job )
47 * {
48 * if ( job->error() ) {
49 * qDebug() << "Error occurred";
50 * return;
51 * }
52 *
53 * qDebug() << "Created search folder successfully";
54 * const Collection searchCollection = job->createdCollection();
55 * ...
56 * }
57 *
58 * @endcode
59 *
60 * @author Volker Krause <vkrause@kde.org>
61 */
62class AKONADI_EXPORT SearchCreateJob : public Job
63{
64 Q_OBJECT
65
66public:
67 /**
68 * Creates a search create job.
69 *
70 * @param name The name of the search collection.
71 * @param query The search query (format not defined yet).
72 * @param parent The parent object.
73 * @deprecated Deprecated as of 4.13, use Akonadi::SearchQuery instead
74 */
75 AKONADI_DEPRECATED SearchCreateJob(const QString &name, const QString &query, QObject *parent = 0);
76
77 /**
78 * Creates a search create job
79 *
80 * @param name The name of the search collection.
81 * @param query The search query.
82 * @param parent The parent object.
83 * @since 4.13
84 */
85 SearchCreateJob(const QString &name, const SearchQuery &searchQuery, QObject *parent = 0);
86
87 /**
88 * Sets the query language.
89 * @param queryLanguage The query language used.
90 * @since 4.6
91 * @deprecated This method is deprecated as of 4.13 and has no effect.
92 *
93 */
94 AKONADI_DEPRECATED void setQueryLanguage(const QString &queryLanguage);
95
96 /**
97 * Sets list of mime types of items that search results can contain
98 *
99 * @param mimeTypes Mime types of items to include in search
100 * @since 4.13
101 */
102 void setSearchMimeTypes(const QStringList &mimeTypes);
103
104 /**
105 * Returns list of mime types that search results can contain
106 *
107 * @since 4.13
108 */
109 QStringList searchMimeTypes() const;
110
111 /**
112 * Sets list of collections to search in.
113 *
114 * When an empty list is set (default value), the search will contain
115 * results from all collections that contain given mime types.
116 *
117 * @param collections Collections to search in, or an empty list to search all
118 * @since 4.13
119 */
120 void setSearchCollections(const Collection::List &collections);
121
122 /**
123 * Returns list of collections to search in
124 *
125 * @since 4.13
126 */
127 Collection::List searchCollections() const;
128
129 /**
130 * Sets whether resources should be queried too.
131 *
132 * When set to true, Akonadi will search local indexed items and will also
133 * query resources that support server-side search, to forward the query
134 * to remote storage (for example using SEARCH feature on IMAP servers) and
135 * merge their results with results from local index.
136 *
137 * This is useful especially when searching resources, that don't fetch full
138 * payload by default, for example the IMAP resource, which only fetches headers
139 * by default and the body is fetched on demand, which means that emails that
140 * were not yet fully fetched cannot be indexed in local index, and thus cannot
141 * be searched. With remote search, even those emails can be included in search
142 * results.
143 *
144 * This feature is disabled by default.
145 *
146 * @param enabled Whether remote search is enabled
147 * @since 4.13
148 */
149 void setRemoteSearchEnabled(bool enabled);
150
151 /**
152 * Returns whether remote search is enabled.
153 *
154 * @since 4.13
155 */
156 bool isRemoteSearchEnabled() const;
157
158 /**
159 * Sets whether the search should recurse into collections
160 *
161 * When set to true, all child collections of the specific collections will
162 * be search recursively.
163 *
164 * @param recursive Whether to search recursively
165 * @since 4.13
166 */
167 void setRecursive(bool recursive);
168
169 /**
170 * Returns whether the search is recursive
171 *
172 * @since 4.13
173 */
174 bool isRecursive() const;
175
176 /**
177 * Destroys the search create job.
178 */
179 ~SearchCreateJob();
180
181 /**
182 * Returns the newly created search collection once the job finished successfully. Returns an invalid
183 * collection if the job has not yet finished or failed.
184 *
185 * @since 4.4
186 */
187 Collection createdCollection() const;
188
189protected:
190 /**
191 * Reimplemented from Akonadi::Job
192 */
193 void doStart();
194
195 /**
196 * Reimplemented from Akonadi::Job
197 */
198 void doHandleResponse(const QByteArray &tag, const QByteArray &data);
199
200private:
201 Q_DECLARE_PRIVATE(SearchCreateJob)
202};
203
204}
205
206#endif
207