Akonadi

searchquery.h
1 /*
2  SPDX-FileCopyrightText: 2014 Daniel Vrátil <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include <QSharedPointer>
10 
11 #include "akonadicore_export.h"
12 
13 namespace Akonadi
14 {
15 class SearchTermPrivate;
16 
17 /**
18  * Search term represents the actual condition within query.
19  *
20  * SearchTerm can either have multiple subterms, or can be so-called endterm, when
21  * there are no more subterms, but instead the actual condition is specified, that
22  * is have key, value and relation between them.
23  *
24  * @since 4.13
25  */
26 class AKONADICORE_EXPORT SearchTerm
27 {
28 public:
29  enum Relation {
30  RelAnd,
31  RelOr,
32  };
33 
34  enum Condition {
35  CondEqual,
36  CondGreaterThan,
37  CondGreaterOrEqual,
38  CondLessThan,
39  CondLessOrEqual,
40  CondContains,
41  };
42 
43  /**
44  * Constructs a term where all subterms will be in given relation
45  */
46  explicit SearchTerm(SearchTerm::Relation relation = SearchTerm::RelAnd);
47 
48  /**
49  * Constructs an end term
50  */
51  SearchTerm(const QString &key, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual);
52 
53  SearchTerm(const SearchTerm &other);
54  ~SearchTerm();
55 
56  SearchTerm &operator=(const SearchTerm &other);
57  Q_REQUIRED_RESULT bool operator==(const SearchTerm &other) const;
58 
59  Q_REQUIRED_RESULT bool isNull() const;
60 
61  /**
62  * Returns key of this end term.
63  */
64  Q_REQUIRED_RESULT QString key() const;
65 
66  /**
67  * Returns value of this end term.
68  */
69  Q_REQUIRED_RESULT QVariant value() const;
70 
71  /**
72  * Returns relation between key and value.
73  */
74  Q_REQUIRED_RESULT SearchTerm::Condition condition() const;
75 
76  /**
77  * Adds a new subterm to this term.
78  *
79  * Subterms will be in relation as specified in SearchTerm constructor.
80  *
81  * If there are subterms in a term, key, value and condition are ignored.
82  */
83  void addSubTerm(const SearchTerm &term);
84 
85  /**
86  * Returns all subterms, or an empty list if this is an end term.
87  */
88  Q_REQUIRED_RESULT QList<SearchTerm> subTerms() const;
89 
90  /**
91  * Returns relation in which all subterms are.
92  */
93  Q_REQUIRED_RESULT SearchTerm::Relation relation() const;
94 
95  /**
96  * Sets whether the entire term is negated.
97  */
98  void setIsNegated(bool negated);
99 
100  /**
101  * Returns whether the entire term is negated.
102  */
103  Q_REQUIRED_RESULT bool isNegated() const;
104 
105 private:
107 };
108 
109 class SearchQueryPrivate;
110 
111 /**
112  * @brief A query that can be passed to ItemSearchJob or others.
113  *
114  * @since 4.13
115  */
116 class AKONADICORE_EXPORT SearchQuery
117 {
118 public:
119  /**
120  * Constructs query where all added terms will be in given relation
121  */
122  explicit SearchQuery(SearchTerm::Relation rel = SearchTerm::RelAnd);
123 
124  ~SearchQuery();
125  SearchQuery(const SearchQuery &other);
126  SearchQuery &operator=(const SearchQuery &other);
127  bool operator==(const SearchQuery &other) const;
128 
129  bool isNull() const;
130 
131  /**
132  * Adds a new term.
133  */
134  void addTerm(const QString &key, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual);
135 
136  /**
137  * Adds a new term with subterms
138  */
139  void addTerm(const SearchTerm &term);
140 
141  /**
142  * Sets the root term
143  */
144  void setTerm(const SearchTerm &term);
145 
146  /**
147  * Returns the root term.
148  */
149  SearchTerm term() const;
150 
151  /**
152  * Sets the maximum number of results.
153  *
154  * Note that this limit is only evaluated per search backend,
155  * so the total number of results retrieved may be larger.
156  */
157  void setLimit(int limit);
158 
159  /**
160  * Returns the maximum number of results.
161  *
162  * The default value is -1, indicating no limit.
163  */
164  int limit() const;
165 
166  QByteArray toJSON() const;
167  static SearchQuery fromJSON(const QByteArray &json);
168 
169 private:
171 };
172 
173 /**
174  * A search term for an email field.
175  *
176  * This class can be used to create queries that akonadi email search backends understand.
177  *
178  * @since 4.13
179  */
180 class AKONADICORE_EXPORT EmailSearchTerm : public SearchTerm
181 {
182 public:
183  /**
184  * All fields expect a search string unless noted otherwise.
185  */
187  Unknown,
188  Subject,
189  Body,
190  Message, // Complete message including headers, body and attachment
191  Headers, // All headers
192  HeaderFrom,
193  HeaderTo,
194  HeaderCC,
195  HeaderBCC,
196  HeaderReplyTo,
197  HeaderOrganization,
198  HeaderListId,
199  HeaderResentFrom,
200  HeaderXLoop,
201  HeaderXMailingList,
202  HeaderXSpamFlag,
203  HeaderDate, // Expects QDateTime
204  HeaderOnlyDate, // Expects QDate
205  MessageStatus, // Expects message flag from Akonadi::MessageFlags. Boolean filter.
206  ByteSize, // Expects int
207  Attachment, // Textsearch on attachment
208  MessageTag
209  };
210 
211  /**
212  * Constructs an email end term
213  */
214  EmailSearchTerm(EmailSearchField field, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual);
215 
216  /**
217  * Translates field to key
218  */
219  static QString toKey(EmailSearchField);
220 
221  /**
222  * Translates key to field
223  */
224  static EmailSearchField fromKey(const QString &key);
225 };
226 
227 /**
228  * A search term for a contact field.
229  *
230  * This class can be used to create queries that akonadi contact search backends understand.
231  *
232  * @since 4.13
233  */
234 class AKONADICORE_EXPORT ContactSearchTerm : public SearchTerm
235 {
236 public:
237  enum ContactSearchField {
238  Unknown,
239  Name,
240  Email,
241  Nickname,
242  Uid,
243  All // Special field: matches all contacts.
244  };
245 
246  ContactSearchTerm(ContactSearchField field, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual);
247 
248  /**
249  * Translates field to key
250  */
251  static QString toKey(ContactSearchField);
252 
253  /**
254  * Translates key to field
255  */
256  static ContactSearchField fromKey(const QString &key);
257 };
258 
259 /**
260  * A search term for a incidence field.
261  *
262  * This class can be used to create queries that akonadi incidence search backends understand.
263  *
264  * @since 5.0
265  */
266 class AKONADICORE_EXPORT IncidenceSearchTerm : public SearchTerm
267 {
268 public:
269  enum IncidenceSearchField {
270  Unknown,
271  All,
272  PartStatus, // Own PartStatus
273  Organizer,
274  Summary,
275  Location
276  };
277 
278  IncidenceSearchTerm(IncidenceSearchField field, const QVariant &value, SearchTerm::Condition condition = SearchTerm::CondEqual);
279 
280  /**
281  * Translates field to key
282  */
283  static QString toKey(IncidenceSearchField);
284 
285  /**
286  * Translates key to field
287  */
288  static IncidenceSearchField fromKey(const QString &key);
289 };
290 
291 }
Subject
Email
A query that can be passed to ItemSearchJob or others.
Definition: searchquery.h:116
Definition: item.h:29
A search term for a incidence field.
Definition: searchquery.h:266
A search term for an email field.
Definition: searchquery.h:180
A search term for a contact field.
Definition: searchquery.h:234
Search term represents the actual condition within query.
Definition: searchquery.h:26
EmailSearchField
All fields expect a search string unless noted otherwise.
Definition: searchquery.h:186
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Sep 29 2023 03:51:14 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.