Akonadi

persistentsearchattribute.h
1/*
2 SPDX-FileCopyrightText: 2010 Volker Krause <vkrause@kde.org>
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
14namespace Akonadi
15{
16class Collection;
17class 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 <vkrause@kde.org>
61 * @since 4.5
62 */
63class AKONADICORE_EXPORT PersistentSearchAttribute : public Akonadi::Attribute
64{
65public:
66 /**
67 * Creates a new persistent search attribute.
68 */
70
71 /**
72 * Destroys the persistent search attribute.
73 */
75
76 /**
77 * Returns the query string used for this search.
78 */
79 [[nodiscard]] 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 [[nodiscard]] QList<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 QList<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 QList<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 [[nodiscard]] 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 [[nodiscard]] bool isRecursive() const;
151
152 /// @cond PRIVATE
153 [[nodiscard]] QByteArray type() const override;
154 Attribute *clone() const override;
155 [[nodiscard]] QByteArray serialized() const override;
156 void deserialize(const QByteArray &data) override;
157 /// @endcond
158
159private:
160 /// @cond PRIVATE
161 const std::unique_ptr<PersistentSearchAttributePrivate> d;
162 /// @endcond
163};
164
165} // namespace Akonadi
Provides interface for custom attributes for Entity.
Definition attribute.h:132
An attribute to store query properties of persistent search collections.
~PersistentSearchAttribute() override
Destroys the persistent search attribute.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Nov 29 2024 11:49:11 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.