Akonadi

persistentsearchattribute.h
1 /*
2  SPDX-FileCopyrightText: 2010 Volker Krause <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #pragma once
8 
9 #include "akonadicore_export.h"
10 #include "attribute.h"
11 
12 #include <memory>
13 
14 namespace Akonadi
15 {
16 class Collection;
17 class PersistentSearchAttributePrivate;
18 
19 /**
20  * @short An attribute to store query properties of persistent search collections.
21  *
22  * This attribute is attached to persistent search collections automatically when
23  * creating a new persistent search with SearchCreateJob.
24  * Later on the search query can be changed by modifying this attribute of the
25  * persistent search collection with an CollectionModifyJob.
26  *
27  * Example:
28  *
29  * @code
30  *
31  * const QString name = "My search folder";
32  * const QString query = "...";
33  *
34  * Akonadi::SearchCreateJob *job = new Akonadi::SearchCreateJob( name, query );
35  * connect( job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*)) );
36  *
37  * MyClass::jobFinished( KJob *job )
38  * {
39  * if ( job->error() ) {
40  * qDebug() << "Error occurred";
41  * return;
42  * }
43  *
44  * const Collection searchCollection = job->createdCollection();
45  * ...
46  *
47  * // now let's change the query
48  * if ( searchCollection.hasAttribute<Akonadi::PersistentSearchAttribute>() ) {
49  * Akonadi::PersistentSearchAttribute *attribute = searchCollection.attribute<Akonadi::PersistentSearchAttribute>();
50  * attribute->setQueryString( "... another query string ..." );
51  *
52  * Akonadi::CollectionModifyJob *modifyJob = new Akonadi::CollectionModifyJob( searchCollection );
53  * connect( modifyJob, SIGNAL(result(KJob*)), SLOT(modifyFinished(KJob*)) );
54  * }
55  * ...
56  * }
57  *
58  * @endcode
59  *
60  * @author Volker Krause <[email protected]>
61  * @since 4.5
62  */
63 class AKONADICORE_EXPORT PersistentSearchAttribute : public Akonadi::Attribute
64 {
65 public:
66  /**
67  * Creates a new persistent search attribute.
68  */
69  explicit PersistentSearchAttribute();
70 
71  /**
72  * Destroys the persistent search attribute.
73  */
74  ~PersistentSearchAttribute() override;
75 
76  /**
77  * Returns the query string used for this search.
78  */
79  QString queryString() const;
80 
81  /**
82  * Sets the query string to be used for this search.
83  * @param query The query string.
84  */
85  void setQueryString(const QString &query);
86 
87  /**
88  * Returns IDs of collections that will be queried
89  * @since 4.13
90  */
91  QVector<qint64> queryCollections() const;
92 
93  /**
94  * Sets collections to be queried.
95  * @param collections List of collections to be queries
96  * @since 4.13
97  */
98  void setQueryCollections(const QVector<Collection> &collections);
99 
100  /**
101  * Sets IDs of collections to be queries
102  * @param collectionsIds IDs of collections to query
103  * @since 4.13
104  */
105  void setQueryCollections(const QVector<qint64> &collectionsIds);
106 
107  /**
108  * Sets whether resources should be queried too.
109  *
110  * When set to true, Akonadi will search local indexed items and will also
111  * query resources that support server-side search, to forward the query
112  * to remote storage (for example using SEARCH feature on IMAP servers) and
113  * merge their results with results from local index.
114  *
115  * This is useful especially when searching resources, that don't fetch full
116  * payload by default, for example the IMAP resource, which only fetches headers
117  * by default and the body is fetched on demand, which means that emails that
118  * were not yet fully fetched cannot be indexed in local index, and thus cannot
119  * be searched. With remote search, even those emails can be included in search
120  * results.
121  *
122  * @param enabled Whether remote search is enabled
123  * @since 4.13
124  */
125  void setRemoteSearchEnabled(bool enabled);
126 
127  /**
128  * Returns whether remote search is enabled.
129  *
130  * @since 4.13
131  */
132  bool isRemoteSearchEnabled() const;
133 
134  /**
135  * Sets whether the search should recurse into collections
136  *
137  * When set to true, all child collections of the specific collections will
138  * be search recursively.
139  *
140  * @param recursive Whether to search recursively
141  * @since 4.13
142  */
143  void setRecursive(bool recursive);
144 
145  /**
146  * Returns whether the search is recursive
147  *
148  * @since 4.13
149  */
150  bool isRecursive() const;
151 
152  /// @cond PRIVATE
153  QByteArray type() const override;
154  Attribute *clone() const override;
155  QByteArray serialized() const override;
156  void deserialize(const QByteArray &data) override;
157  /// @endcond
158 
159 private:
160  /// @cond PRIVATE
161  const std::unique_ptr<PersistentSearchAttributePrivate> d;
162  /// @endcond
163 };
164 
165 } // namespace Akonadi
166 
Provides interface for custom attributes for Entity.
Definition: attribute.h:124
An attribute to store query properties of persistent search collections.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:00:32 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.