Akonadi

collectionfetchjob.h
1 /*
2  SPDX-FileCopyrightText: 2006-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 CollectionFetchScope;
16 class 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 <[email protected]>
38  */
39 class AKONADICORE_EXPORT CollectionFetchJob : public Job
40 {
41  Q_OBJECT
42 
43 public:
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  */
121  ~CollectionFetchJob() override;
122 
123  /**
124  * Returns the list of fetched collection.
125  */
126  Q_REQUIRED_RESULT 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  Q_REQUIRED_RESULT CollectionFetchScope &fetchScope();
156 
157 Q_SIGNALS:
158  /**
159  * This signal is emitted whenever the job has received collections.
160  *
161  * @param collections The received collections.
162  */
163  void collectionsReceived(const Akonadi::Collection::List &collections);
164 
165 protected:
166  void doStart() override;
167  bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
168 
169 protected Q_SLOTS:
170  /// @cond PRIVATE
171  void slotResult(KJob *job) override;
172  /// @endcond
173 
174 private:
175  Q_DECLARE_PRIVATE(CollectionFetchJob)
176 };
177 
178 }
179 
Type
Describes the type of fetch depth.
Represents a collection of PIM items.
Definition: collection.h:61
Job that fetches collections from the Akonadi storage.
Specifies which parts of a collection should be fetched from the Akonadi storage.
@ FirstLevel
Only list direct sub-collections of the base collection.
@ Base
Only fetch the base collection.
Base class for all actions in the Akonadi storage.
Definition: job.h:80
@ Recursive
List all sub-collections.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:00:31 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.