1 | /* |
2 | Copyright (c) 2014 Daniel Vrátil <dvratil@redhat.com> |
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_SEARCHQUERY_H |
21 | #define AKONADI_SEARCHQUERY_H |
22 | |
23 | #include <QSharedPointer> |
24 | |
25 | #include "akonadi_export.h" |
26 | |
27 | namespace Akonadi |
28 | { |
29 | |
30 | /** |
31 | * Search term represents the actual condition within query. |
32 | * |
33 | * SearchTerm can either have multiple subterms, or can be so-called endterm, when |
34 | * there are no more subterms, but instead the actual condition is specified, that |
35 | * is have key, value and relation between them. |
36 | * |
37 | * @since 4.13 |
38 | */ |
39 | class AKONADI_EXPORT SearchTerm |
40 | { |
41 | public: |
42 | enum Relation { |
43 | RelAnd, |
44 | RelOr |
45 | }; |
46 | |
47 | enum Condition { |
48 | CondEqual, |
49 | CondGreaterThan, |
50 | CondGreaterOrEqual, |
51 | CondLessThan, |
52 | CondLessOrEqual, |
53 | CondContains |
54 | }; |
55 | |
56 | /** |
57 | * Constructs a term where all subterms will be in given relation |
58 | */ |
59 | SearchTerm(SearchTerm::Relation relation = SearchTerm::RelAnd); |
60 | |
61 | /** |
62 | * Constructs an end term |
63 | */ |
64 | SearchTerm(const QString &key, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual); |
65 | |
66 | SearchTerm(const SearchTerm &other); |
67 | ~SearchTerm(); |
68 | |
69 | SearchTerm &operator=(const SearchTerm &other); |
70 | bool operator==(const SearchTerm &other) const; |
71 | |
72 | bool isNull() const; |
73 | |
74 | /** |
75 | * Returns key of this end term. |
76 | */ |
77 | QString key() const; |
78 | |
79 | /** |
80 | * Returns value of this end term. |
81 | */ |
82 | QVariant value() const; |
83 | |
84 | /** |
85 | * Returns relation between key and value. |
86 | */ |
87 | SearchTerm::Condition condition() const; |
88 | |
89 | /** |
90 | * Adds a new subterm to this term. |
91 | * |
92 | * Subterms will be in relation as specified in SearchTerm constructor. |
93 | * |
94 | * If there are subterms in a term, key, value and condition are ignored. |
95 | */ |
96 | void addSubTerm(const SearchTerm &term); |
97 | |
98 | /** |
99 | * Returns all subterms, or an empty list if this is an end term. |
100 | */ |
101 | QList<SearchTerm> subTerms() const; |
102 | |
103 | /** |
104 | * Returns relation in which all subterms are. |
105 | */ |
106 | SearchTerm::Relation relation() const; |
107 | |
108 | /** |
109 | * Sets whether the entire term is negated. |
110 | */ |
111 | void setIsNegated(bool negated); |
112 | |
113 | /** |
114 | * Returns whether the entire term is negated. |
115 | */ |
116 | bool isNegated() const; |
117 | |
118 | private: |
119 | class Private; |
120 | QSharedDataPointer<Private> d; |
121 | }; |
122 | |
123 | /** |
124 | * @brief A query that can be passed to ItemSearchJob or others. |
125 | * |
126 | * @since 4.13 |
127 | */ |
128 | class AKONADI_EXPORT SearchQuery |
129 | { |
130 | public: |
131 | /** |
132 | * Constructs query where all added terms will be in given relation |
133 | */ |
134 | SearchQuery(SearchTerm::Relation rel = SearchTerm::RelAnd); |
135 | |
136 | ~SearchQuery(); |
137 | SearchQuery(const SearchQuery &other); |
138 | SearchQuery &operator=(const SearchQuery &other); |
139 | bool operator==(const SearchQuery &other) const; |
140 | |
141 | bool isNull() const; |
142 | |
143 | /** |
144 | * Adds a new term. |
145 | */ |
146 | void addTerm(const QString &key, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual); |
147 | |
148 | /** |
149 | * Adds a new term with subterms |
150 | */ |
151 | void addTerm(const SearchTerm &term); |
152 | |
153 | /** |
154 | * Sets the root term |
155 | */ |
156 | void setTerm(const SearchTerm &term); |
157 | |
158 | /** |
159 | * Returns the root term. |
160 | */ |
161 | SearchTerm term() const; |
162 | |
163 | /** |
164 | * Sets the maximum number of results. |
165 | * |
166 | * Note that this limit is only evaluated per search backend, |
167 | * so the total number of results retrieved may be larger. |
168 | */ |
169 | void setLimit(int limit); |
170 | |
171 | /** |
172 | * Returns the maximum number of results. |
173 | * |
174 | * The default value is -1, indicating no limit. |
175 | */ |
176 | int limit() const; |
177 | |
178 | QByteArray toJSON() const; |
179 | static SearchQuery fromJSON(const QByteArray &json); |
180 | |
181 | private: |
182 | class Private; |
183 | QSharedDataPointer<Private> d; |
184 | |
185 | }; |
186 | |
187 | /** |
188 | * A search term for an email field. |
189 | * |
190 | * This class can be used to create queries that akonadi email search backends understand. |
191 | * |
192 | * @since 4.13 |
193 | */ |
194 | class AKONADI_EXPORT EmailSearchTerm : public SearchTerm |
195 | { |
196 | public: |
197 | |
198 | /** |
199 | * All fields expect a search string unless noted otherwise. |
200 | */ |
201 | enum EmailSearchField { |
202 | Unknown, |
203 | Subject, |
204 | Body, |
205 | Message, //Complete message including headers, body and attachment |
206 | , //All headers |
207 | , |
208 | , |
209 | , |
210 | , |
211 | , |
212 | , |
213 | , |
214 | , |
215 | , |
216 | , |
217 | , |
218 | , //Expects QDateTime |
219 | , //Expectes QDate |
220 | MessageStatus, //Expects message flag from Akonadi::MessageFlags. Boolean filter. |
221 | ByteSize, //Expects int |
222 | Attachment, //Textsearch on attachment |
223 | MessageTag |
224 | }; |
225 | |
226 | /** |
227 | * Constructs an email end term |
228 | */ |
229 | EmailSearchTerm(EmailSearchField field, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual); |
230 | |
231 | /** |
232 | * Translates field to key |
233 | */ |
234 | static QString toKey(EmailSearchField); |
235 | |
236 | /** |
237 | * Translates key to field |
238 | */ |
239 | static EmailSearchField fromKey(const QString &key); |
240 | }; |
241 | |
242 | /** |
243 | * A search term for a contact field. |
244 | * |
245 | * This class can be used to create queries that akonadi contact search backends understand. |
246 | * |
247 | * @since 4.13 |
248 | */ |
249 | class AKONADI_EXPORT ContactSearchTerm : public SearchTerm |
250 | { |
251 | public: |
252 | enum ContactSearchField { |
253 | Unknown, |
254 | Name, |
255 | Email, |
256 | Nickname, |
257 | Uid, |
258 | All //Special field: matches all contacts. |
259 | }; |
260 | |
261 | ContactSearchTerm(ContactSearchField field, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual); |
262 | |
263 | /** |
264 | * Translates field to key |
265 | */ |
266 | static QString toKey(ContactSearchField); |
267 | |
268 | /** |
269 | * Translates key to field |
270 | */ |
271 | static ContactSearchField fromKey(const QString &key); |
272 | }; |
273 | |
274 | } |
275 | |
276 | #endif // AKONADI_SEARCHQUERY_H |
277 | |