Akonadi

searchcreatejob.h
1 /*
2  SPDX-FileCopyrightText: 2007 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 "collection.h"
11 #include "job.h"
12 
13 namespace Akonadi
14 {
15 class Collection;
16 class SearchQuery;
17 class SearchCreateJobPrivate;
18 
19 /**
20  * @short Job that creates a virtual/search collection in the Akonadi storage.
21  *
22  * This job creates so called virtual or search collections, which don't contain
23  * real data, but references to items that match a given search query.
24  *
25  * @code
26  *
27  * const QString name = "My search folder";
28  * const QString query = "...";
29  *
30  * Akonadi::SearchCreateJob *job = new Akonadi::SearchCreateJob( name, query );
31  * connect( job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*)) );
32  *
33  * MyClass::jobFinished( KJob *job )
34  * {
35  * if ( job->error() ) {
36  * qDebug() << "Error occurred";
37  * return;
38  * }
39  *
40  * qDebug() << "Created search folder successfully";
41  * const Collection searchCollection = job->createdCollection();
42  * ...
43  * }
44  *
45  * @endcode
46  *
47  * @author Volker Krause <[email protected]>
48  */
49 class AKONADICORE_EXPORT SearchCreateJob : public Job
50 {
51  Q_OBJECT
52 
53 public:
54  /**
55  * Creates a search create job
56  *
57  * @param name The name of the search collection
58  * @param searchQuery The search query
59  * @param parent The parent object
60  * @since 4.13
61  */
62  SearchCreateJob(const QString &name, const SearchQuery &searchQuery, QObject *parent = nullptr);
63 
64  /**
65  * Sets list of mime types of items that search results can contain
66  *
67  * @param mimeTypes Mime types of items to include in search
68  * @since 4.13
69  */
70  void setSearchMimeTypes(const QStringList &mimeTypes);
71 
72  /**
73  * Returns list of mime types that search results can contain
74  *
75  * @since 4.13
76  */
77  Q_REQUIRED_RESULT QStringList searchMimeTypes() const;
78 
79  /**
80  * Sets list of collections to search in.
81  *
82  * When an empty list is set (default value), the search will contain
83  * results from all collections that contain given mime types.
84  *
85  * @param collections Collections to search in, or an empty list to search all
86  * @since 4.13
87  */
88  void setSearchCollections(const QVector<Collection> &collections);
89 
90  /**
91  * Returns list of collections to search in
92  *
93  * @since 4.13
94  */
95  Q_REQUIRED_RESULT QVector<Collection> searchCollections() const;
96 
97  /**
98  * Sets whether resources should be queried too.
99  *
100  * When set to true, Akonadi will search local indexed items and will also
101  * query resources that support server-side search, to forward the query
102  * to remote storage (for example using SEARCH feature on IMAP servers) and
103  * merge their results with results from local index.
104  *
105  * This is useful especially when searching resources, that don't fetch full
106  * payload by default, for example the IMAP resource, which only fetches headers
107  * by default and the body is fetched on demand, which means that emails that
108  * were not yet fully fetched cannot be indexed in local index, and thus cannot
109  * be searched. With remote search, even those emails can be included in search
110  * results.
111  *
112  * This feature is disabled by default.
113  *
114  * @param enabled Whether remote search is enabled
115  * @since 4.13
116  */
117  void setRemoteSearchEnabled(bool enabled);
118 
119  /**
120  * Returns whether remote search is enabled.
121  *
122  * @since 4.13
123  */
124  Q_REQUIRED_RESULT bool isRemoteSearchEnabled() const;
125 
126  /**
127  * Sets whether the search should recurse into collections
128  *
129  * When set to true, all child collections of the specific collections will
130  * be search recursively.
131  *
132  * @param recursive Whether to search recursively
133  * @since 4.13
134  */
135  void setRecursive(bool recursive);
136 
137  /**
138  * Returns whether the search is recursive
139  *
140  * @since 4.13
141  */
142  Q_REQUIRED_RESULT bool isRecursive() const;
143 
144  /**
145  * Destroys the search create job.
146  */
147  ~SearchCreateJob() override;
148 
149  /**
150  * Returns the newly created search collection once the job finished successfully. Returns an invalid
151  * collection if the job has not yet finished or failed.
152  *
153  * @since 4.4
154  */
155  Q_REQUIRED_RESULT Collection createdCollection() const;
156 
157 protected:
158  /**
159  * Reimplemented from Akonadi::Job
160  */
161  void doStart() override;
162 
163  /**
164  * Reimplemented from Akonadi::Job
165  */
166  bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
167 
168 private:
169  Q_DECLARE_PRIVATE(SearchCreateJob)
170 };
171 
172 }
173 
Job that creates a virtual/search collection in the Akonadi storage.
Represents a collection of PIM items.
Definition: collection.h:61
A query that can be passed to ItemSearchJob or others.
Definition: searchquery.h:116
Base class for all actions in the Akonadi storage.
Definition: job.h:80
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Mon Jul 4 2022 03:53:15 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.