Akonadi

collectionfetchjob.h
1/*
2 SPDX-FileCopyrightText: 2006-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
13namespace Akonadi
14{
15class CollectionFetchScope;
16class CollectionFetchJobPrivate;
17
18/**
19 * @short Job that fetches collections from the Akonadi storage.
20 *
21 * This class can be used to retrieve the complete or partial collection tree
22 * from the Akonadi storage. This fetches collection data, not item data.
23 *
24 * @code
25 * using namespace Akonadi;
26 * using namespace Qt::StringLiterals;
27 *
28 * // fetching all collections containing emails recursively, starting at the root collection
29 * auto job = new CollectionFetchJob(Collection::root(), CollectionFetchJob::Recursive, this);
30 * job->fetchScope().setContentMimeTypes({ u"message/rfc822"_s });
31 * connect(job, &CollectionFetchJob::collectionsReceived, this &MyClass::myCollectionsReceived);
32 * connect(job, &KJob::result, this, &MyClass::collectionFetchResult);
33 *
34 * @endcode
35 *
36 * @author Volker Krause <vkrause@kde.org>
37 */
38class AKONADICORE_EXPORT CollectionFetchJob : public Job
39{
40 Q_OBJECT
41
42public:
43 /**
44 * Describes the type of fetch depth.
45 */
46 enum Type {
47 Base, ///< Only fetch the base collection.
48 FirstLevel, ///< Only list direct sub-collections of the base collection.
49 Recursive, ///< List all sub-collections.
50 NonOverlappingRoots ///< List the roots of a list of fetched collections. @since 4.7
51 };
52
53 /**
54 * Creates a new collection fetch job. If the given base collection
55 * has a unique identifier, this is used to identify the collection in the
56 * Akonadi server. If only a remote identifier is available the collection
57 * is identified using that, provided that a resource search context has
58 * been specified by calling setResource().
59 *
60 * @internal
61 * For internal use only, if a remote identifier is set, the resource
62 * search context can be set globally using ResourceSelectJob.
63 * @endinternal
64 *
65 * @param collection The base collection for the listing.
66 * @param type The type of fetch depth.
67 * @param parent The parent object.
68 */
69 explicit CollectionFetchJob(const Collection &collection, Type type = FirstLevel, QObject *parent = nullptr);
70
71 /**
72 * Creates a new collection fetch job to retrieve a list of collections.
73 * If a given collection has a unique identifier, this is used to identify
74 * the collection in the Akonadi server. If only a remote identifier is
75 * available the collection is identified using that, provided that a
76 * resource search context has been specified by calling setResource().
77 *
78 * @internal
79 * For internal use only, if a remote identifier is set, the resource
80 * search context can be set globally using ResourceSelectJob.
81 * @endinternal
82 *
83 * @param collections A list of collections to fetch. Must not be empty.
84 * @param parent The parent object.
85 */
86 explicit CollectionFetchJob(const Collection::List &collections, QObject *parent = nullptr);
87
88 /**
89 * Creates a new collection fetch job to retrieve a list of collections.
90 * If a given collection has a unique identifier, this is used to identify
91 * the collection in the Akonadi server. If only a remote identifier is
92 * available the collection is identified using that, provided that a
93 * resource search context has been specified by calling setResource().
94 *
95 * @internal
96 * For internal use only, if a remote identifier is set, the resource
97 * search context can be set globally using ResourceSelectJob.
98 * @endinternal
99 *
100 * @param collections A list of collections to fetch. Must not be empty.
101 * @param type The type of fetch depth.
102 * @param parent The parent object.
103 * @todo KDE5 merge with ctor above.
104 * @since 4.7
105 */
106 CollectionFetchJob(const Collection::List &collections, Type type, QObject *parent = nullptr);
107
108 /**
109 * Convenience ctor equivalent to CollectionFetchJob(const Collection::List &collections, Type type, QObject *parent = nullptr)
110 * @since 4.8
111 * @param collections list of collection ids
112 * @param type fetch job type
113 * @param parent parent object
114 */
115 explicit CollectionFetchJob(const QList<Collection::Id> &collections, Type type = Base, QObject *parent = nullptr);
116
117 /**
118 * Destroys the collection fetch job.
119 */
121
122 /**
123 * Returns the list of fetched collection.
124 */
125 [[nodiscard]] Collection::List collections() const;
126
127 /**
128 * Sets the collection fetch scope.
129 *
130 * The CollectionFetchScope controls how much of a collection's data is
131 * fetched from the server as well as a filter to select which collections
132 * to fetch.
133 *
134 * @param fetchScope The new scope for collection fetch operations.
135 *
136 * @see fetchScope()
137 * @since 4.4
138 */
139 void setFetchScope(const CollectionFetchScope &fetchScope);
140
141 /**
142 * Returns the collection fetch scope.
143 *
144 * Since this returns a reference it can be used to conveniently modify the
145 * current scope in-place, i.e. by calling a method on the returned reference
146 * without storing it in a local variable. See the CollectionFetchScope documentation
147 * for an example.
148 *
149 * @return a reference to the current collection fetch scope
150 *
151 * @see setFetchScope() for replacing the current collection fetch scope
152 * @since 4.4
153 */
154 [[nodiscard]] CollectionFetchScope &fetchScope();
155
156Q_SIGNALS:
157 /**
158 * This signal is emitted whenever the job has received collections.
159 *
160 * @param collections The received collections.
161 */
163
164protected:
165 void doStart() override;
166 bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
167
168protected Q_SLOTS:
169 /// @cond PRIVATE
170 void slotResult(KJob *job) override;
171 /// @endcond
172
173private:
174 Q_DECLARE_PRIVATE(CollectionFetchJob)
175};
176
177}
Job that fetches collections from the Akonadi storage.
Type
Describes the type of fetch depth.
@ Recursive
List all sub-collections.
@ FirstLevel
Only list direct sub-collections of the base collection.
@ Base
Only fetch the base collection.
void collectionsReceived(const Akonadi::Collection::List &collections)
This signal is emitted whenever the job has received collections.
~CollectionFetchJob() override
Destroys the collection fetch job.
Specifies which parts of a collection should be fetched from the Akonadi storage.
Represents a collection of PIM items.
Definition collection.h:62
Base class for all actions in the Akonadi storage.
Definition job.h:81
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Mon Nov 18 2024 12:08:29 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.