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 | |
25 | namespace Akonadi { |
26 | |
27 | class 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 | */ |
73 | class AKONADI_EXPORT PersistentSearchAttribute : public Akonadi::Attribute |
74 | { |
75 | public: |
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 | |
185 | private: |
186 | //@cond PRIVATE |
187 | class Private; |
188 | Private *const d; |
189 | //@endcond |
190 | }; |
191 | |
192 | } |
193 | |
194 | #endif |
195 | |