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 | |
26 | namespace Akonadi { |
27 | |
28 | class Collection; |
29 | class SearchQuery; |
30 | class 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 | */ |
62 | class AKONADI_EXPORT SearchCreateJob : public Job |
63 | { |
64 | Q_OBJECT |
65 | |
66 | public: |
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 | |
189 | protected: |
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 | |
200 | private: |
201 | Q_DECLARE_PRIVATE(SearchCreateJob) |
202 | }; |
203 | |
204 | } |
205 | |
206 | #endif |
207 | |