Akonadi

itemfetchjob.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 "item.h"
11#include "job.h"
12
13namespace Akonadi
14{
15class Collection;
16class ItemFetchJobPrivate;
17class ItemFetchScope;
18
19/**
20 * @short Job that fetches items from the Akonadi storage.
21 *
22 * This class is used to fetch items from the Akonadi storage.
23 * Which parts of the items (e.g. headers only, attachments or all)
24 * can be specified by the ItemFetchScope.
25 *
26 * Note that ItemFetchJob does not refresh the Akonadi storage from the
27 * backend; this is unnecessary due to the fact that backend updates
28 * automatically trigger an update to the Akonadi database whenever they occur
29 * (unless the resource is offline).
30 *
31 * Note that items can not be created in the root collection (Collection::root())
32 * and therefore can not be fetched from there either. That is - an item fetch in
33 * the root collection will yield an empty list.
34 *
35 *
36 * Example:
37 *
38 * @code
39 *
40 * // Fetch all items with full payload from a collection
41 *
42 * const Collection collection = getCollection();
43 *
44 * Akonadi::ItemFetchJob *job = new Akonadi::ItemFetchJob(collection);
45 * connect(job, SIGNAL(result(KJob*)), SLOT(jobFinished(KJob*)));
46 * job->fetchScope().fetchFullPayload();
47 *
48 * ...
49 *
50 * MyClass::jobFinished(KJob *job)
51 * {
52 * if (job->error()) {
53 * qDebug() << "Error occurred";
54 * return;
55 * }
56 *
57 * Akonadi::ItemFetchJob *fetchJob = qobject_cast<Akonadi::ItemFetchJob*>(job);
58 *
59 * const Akonadi::Item::List items = fetchJob->items();
60 * for (const Akonadi::Item &item : items) {
61 * qDebug() << "Item ID:" << item.id();
62 * }
63 * }
64 *
65 * @endcode
66 *
67 * @author Volker Krause <vkrause@kde.org>
68 */
69class AKONADICORE_EXPORT ItemFetchJob : public Job
70{
71 Q_OBJECT
72 Q_FLAGS(DeliveryOptions)
73public:
74 /**
75 * Creates a new item fetch job that retrieves all items inside the given collection.
76 *
77 * @param collection The parent collection to fetch all items from.
78 * @param parent The parent object.
79 */
80 explicit ItemFetchJob(const Collection &collection, QObject *parent = nullptr);
81
82 /**
83 * Creates a new item fetch job that retrieves the specified item.
84 * If the item has a uid set, this is used to identify the item on the Akonadi
85 * server. If only a remote identifier is available, that is used.
86 * However, as remote identifiers are not necessarily globally unique, you
87 * need to specify the collection to search in in that case, using
88 * setCollection().
89 *
90 * @internal
91 * For internal use only when using remote identifiers, the resource search
92 * context can be set globally by ResourceSelectJob.
93 * @endinternal
94 *
95 * @param item The item to fetch.
96 * @param parent The parent object.
97 */
98 explicit ItemFetchJob(const Item &item, QObject *parent = nullptr);
99
100 /**
101 * Creates a new item fetch job that retrieves the specified items.
102 * If the items have a uid set, this is used to identify the item on the Akonadi
103 * server. If only a remote identifier is available, that is used.
104 * However, as remote identifiers are not necessarily globally unique, you
105 * need to specify the collection to search in in that case, using
106 * setCollection().
107 *
108 * @internal
109 * For internal use only when using remote identifiers, the resource search
110 * context can be set globally by ResourceSelectJob.
111 * @endinternal
112 *
113 * @param items The items to fetch.
114 * @param parent The parent object.
115 * @since 4.4
116 */
117 explicit ItemFetchJob(const Item::List &items, QObject *parent = nullptr);
118
119 /**
120 * Convenience ctor equivalent to ItemFetchJob(const Item::List &items, QObject *parent = nullptr)
121 * @since 4.8
122 */
123 explicit ItemFetchJob(const QList<Item::Id> &items, QObject *parent = nullptr);
124 /**
125 * Creates a new item fetch job that retrieves all items tagged with specified @p tag.
126 *
127 * @param tag The tag to fetch all items from.
128 * @param parent The parent object.
129 *
130 * @since 4.14
131 */
132 explicit ItemFetchJob(const Tag &tag, QObject *parent = nullptr);
133
134 /**
135 * Destroys the item fetch job.
136 */
137 ~ItemFetchJob() override;
138
139 /**
140 * Returns the fetched items.
141 *
142 * This returns an empty list when not using the ItemGetter DeliveryOption.
143 *
144 * @note The items are invalid before the result(KJob*)
145 * signal has been emitted or if an error occurred.
146 */
147 [[nodiscard]] Item::List items() const;
148
149 /**
150 * Save memory by clearing the fetched items.
151 * @since 4.12
152 */
153 void clearItems();
154
155 /**
156 * Sets the item fetch scope.
157 *
158 * The ItemFetchScope controls how much of an item's data is fetched
159 * from the server, e.g. whether to fetch the full item payload or
160 * only meta data.
161 *
162 * @param fetchScope The new scope for item fetch operations.
163 *
164 * @see fetchScope()
165 * @since 4.4
166 */
167 void setFetchScope(const ItemFetchScope &fetchScope);
168
169 /**
170 * Returns the item fetch scope.
171 *
172 * Since this returns a reference it can be used to conveniently modify the
173 * current scope in-place, i.e. by calling a method on the returned reference
174 * without storing it in a local variable. See the ItemFetchScope documentation
175 * for an example.
176 *
177 * @return a reference to the current item fetch scope
178 *
179 * @see setFetchScope() for replacing the current item fetch scope
180 */
181 ItemFetchScope &fetchScope();
182
183 /**
184 * Specifies the collection the item is in.
185 * This is only required when retrieving an item based on its remote id
186 * which might not be unique globally.
187 *
188 * @internal
189 * @see ResourceSelectJob (for internal use only)
190 * @endinternal
191 */
192 void setCollection(const Collection &collection);
193
195 ItemGetter = 0x1, ///< items available through items()
196 EmitItemsIndividually = 0x2, ///< emitted via signal upon reception
197 EmitItemsInBatches = 0x4, ///< emitted via signal in bulk (collected and emitted delayed via timer)
198 Default = ItemGetter | EmitItemsInBatches
199 };
200 Q_DECLARE_FLAGS(DeliveryOptions, DeliveryOption)
201
202 /**
203 * Sets the mechanisms by which the items should be fetched
204 * @since 4.13
205 */
206 void setDeliveryOption(DeliveryOptions options);
207
208 /**
209 * Returns the delivery options
210 * @since 4.13
211 */
212 DeliveryOptions deliveryOptions() const;
213
214 /**
215 * Returns the total number of retrieved items.
216 * This works also without the ItemGetter DeliveryOption.
217 * @since 4.14
218 */
219 int count() const;
220
221 /**
222 * Sets the limit of fetched items.
223 *
224 * @param limit the maximum number of items to retrieve.
225 * The default value for @p limit is -1, indicating no limit.
226 * @param start specifies the offset of the first item to retrieve.
227 * @param order specifies whether items will be fetched
228 * starting with the highest or lowest ID of the item.
229 */
230
231 void setLimit(int limit, int start, Qt::SortOrder order = Qt::DescendingOrder);
232
233Q_SIGNALS:
234 /**
235 * This signal is emitted whenever new items have been fetched completely.
236 *
237 * @note This is an optimization; instead of waiting for the end of the job
238 * and calling items(), you can connect to this signal and get the items
239 * incrementally.
240 *
241 * @param items The fetched items.
242 */
244
245protected:
246 void doStart() override;
247 bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
248
249private:
250 Q_DECLARE_PRIVATE(ItemFetchJob)
251};
252
253}
254
255Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::ItemFetchJob::DeliveryOptions)
Represents a collection of PIM items.
Definition collection.h:62
Job that fetches items from the Akonadi storage.
void itemsReceived(const Akonadi::Item::List &items)
This signal is emitted whenever new items have been fetched completely.
~ItemFetchJob() override
Destroys the item fetch job.
Specifies which parts of an item should be fetched from the Akonadi storage.
Represents a PIM item stored in Akonadi storage.
Definition item.h:100
Base class for all actions in the Akonadi storage.
Definition job.h:81
An Akonadi Tag.
Definition tag.h:26
Q_SCRIPTABLE Q_NOREPLY void start()
Helper integration between Akonadi and Qt.
SortOrder
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:42 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.