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
27namespace 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 */
39class AKONADI_EXPORT SearchTerm
40{
41public:
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
118private:
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 */
128class AKONADI_EXPORT SearchQuery
129{
130public:
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
181private:
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 */
194class AKONADI_EXPORT EmailSearchTerm : public SearchTerm
195{
196public:
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 Headers, //All headers
207 HeaderFrom,
208 HeaderTo,
209 HeaderCC,
210 HeaderBCC,
211 HeaderReplyTo,
212 HeaderOrganization,
213 HeaderListId,
214 HeaderResentFrom,
215 HeaderXLoop,
216 HeaderXMailingList,
217 HeaderXSpamFlag,
218 HeaderDate, //Expects QDateTime
219 HeaderOnlyDate, //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 */
249class AKONADI_EXPORT ContactSearchTerm : public SearchTerm
250{
251public:
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