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

KDE's Doxygen guidelines are available online.