1/*
2 Copyright (c) 2010 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_PERSISTENTSEARCHATTRIBUTE_H
21#define AKONADI_PERSISTENTSEARCHATTRIBUTE_H
22
23#include <akonadi/attribute.h>
24
25namespace Akonadi {
26
27class Collection;
28
29/**
30 * @short An attribute to store query properties of persistent search collections.
31 *
32 * This attribute is attached to persistent search collections automatically when
33 * creating a new persistent search with SearchCreateJob.
34 * Later on the search query can be changed by modifying this attribute of the
35 * persistent search collection with an CollectionModifyJob.
36 *
37 * Example:
38 *
39 * @code
40 *
41 * const QString name = "My search folder";
42 * const QString query = "...";
43 *
44 * Akonadi::SearchCreateJob *job = new Akonadi::SearchCreateJob( name, query );
45 * connect( job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*)) );
46 *
47 * MyClass::jobFinished( KJob *job )
48 * {
49 * if ( job->error() ) {
50 * qDebug() << "Error occurred";
51 * return;
52 * }
53 *
54 * const Collection searchCollection = job->createdCollection();
55 * ...
56 *
57 * // now let's change the query
58 * if ( searchCollection.hasAttribute<Akonadi::PersistentSearchAttribute>() ) {
59 * Akonadi::PersistentSearchAttribute *attribute = searchCollection.attribute<Akonadi::PersistentSearchAttribute>();
60 * attribute->setQueryString( "... another query string ..." );
61 *
62 * Akonadi::CollectionModifyJob *modifyJob = new Akonadi::CollectionModifyJob( searchCollection );
63 * connect( modifyJob, SIGNAL(result(KJob*)), SLOT(modifyFinished(KJob*)) );
64 * }
65 * ...
66 * }
67 *
68 * @endcode
69 *
70 * @author Volker Krause <vkrause@kde.org>
71 * @since 4.5
72 */
73class AKONADI_EXPORT PersistentSearchAttribute : public Akonadi::Attribute
74{
75public:
76 /**
77 * Creates a new persistent search attribute.
78 */
79 PersistentSearchAttribute();
80
81 /**
82 * Destroys the persistent search attribute.
83 */
84 ~PersistentSearchAttribute();
85
86 /**
87 * Returns the query language used for this search.
88 *
89 * @deprecated Deprecated as of 4.13. This method returns "SPARQL" for
90 * compatibility reasons and should not be used with new code.
91 */
92 AKONADI_DEPRECATED QString queryLanguage() const;
93
94 /**
95 * Sets the query language used for this search.
96 * @param language the query language
97 *
98 * @deprecated Deprecated as of 4.13. This method has no effect.
99 */
100 AKONADI_DEPRECATED void setQueryLanguage(const QString &language);
101
102 /**
103 * Returns the query string used for this search.
104 */
105 QString queryString() const;
106
107 /**
108 * Sets the query string to be used for this search.
109 * @param query The query string.
110 */
111 void setQueryString(const QString &query);
112
113 /**
114 * Returns IDs of collections that will be queried
115 * @since 4.13
116 */
117 QList<qint64> queryCollections() const;
118
119 /**
120 * Sets collections to be queried.
121 * @param collections List of collections to be queries
122 * @since 4.13
123 */
124 void setQueryCollections(const QList<Collection> &collections);
125
126 /**
127 * Sets IDs of collections to be queries
128 * @param collectionsIDs IDs of collections to query
129 * @since 4.13
130 */
131 void setQueryCollections(const QList<qint64> &collectionsIds);
132
133 /**
134 * Sets whether resources should be queried too.
135 *
136 * When set to true, Akonadi will search local indexed items and will also
137 * query resources that support server-side search, to forward the query
138 * to remote storage (for example using SEARCH feature on IMAP servers) and
139 * merge their results with results from local index.
140 *
141 * This is useful especially when searching resources, that don't fetch full
142 * payload by default, for example the IMAP resource, which only fetches headers
143 * by default and the body is fetched on demand, which means that emails that
144 * were not yet fully fetched cannot be indexed in local index, and thus cannot
145 * be searched. With remote search, even those emails can be included in search
146 * results.
147 *
148 * @param enabled Whether remote search is enabled
149 * @since 4.13
150 */
151 void setRemoteSearchEnabled(bool enabled);
152
153 /**
154 * Returns whether remote search is enabled.
155 *
156 * @since 4.13
157 */
158 bool isRemoteSearchEnabled() const;
159
160 /**
161 * Sets whether the search should recurse into collections
162 *
163 * When set to true, all child collections of the specific collections will
164 * be search recursively.
165 *
166 * @param recursive Whether to search recursively
167 * @since 4.13
168 */
169 void setRecursive(bool recursive);
170
171 /**
172 * Returns whether the search is recursive
173 *
174 * @since 4.13
175 */
176 bool isRecursive() const;
177
178 //@cond PRIVATE
179 virtual QByteArray type() const;
180 virtual Attribute *clone() const;
181 virtual QByteArray serialized() const;
182 virtual void deserialize(const QByteArray &data);
183 //@endcond
184
185private:
186 //@cond PRIVATE
187 class Private;
188 Private *const d;
189 //@endcond
190};
191
192}
193
194#endif
195