1 /*
2     SPDX-FileCopyrightText: 2007 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 "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 <vkrause@kde.org>
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 
174