Akonadi

itemfetchjob.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 "item.h"
11 #include "job.h"
12 
13 namespace Akonadi
14 {
15 class Collection;
16 class ItemFetchJobPrivate;
17 class 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 <[email protected]>
68  */
69 class AKONADICORE_EXPORT ItemFetchJob : public Job
70 {
71  Q_OBJECT
72  Q_FLAGS(DeliveryOptions)
73 public:
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 
233 Q_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  */
243  void itemsReceived(const Akonadi::Item::List &items);
244 
245 protected:
246  void doStart() override;
247  bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
248 
249 private:
250  Q_DECLARE_PRIVATE(ItemFetchJob)
251 };
252 
253 }
254 
255 Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::ItemFetchJob::DeliveryOptions)
An Akonadi Tag.
Definition: tag.h:25
Q_SCRIPTABLE Q_NOREPLY void start()
SortOrder
Represents a collection of PIM items.
Definition: collection.h:61
Base class for all actions in the Akonadi storage.
Definition: job.h:80
Job that fetches items from the Akonadi storage.
Definition: itemfetchjob.h:69
Represents a PIM item stored in Akonadi storage.
Definition: item.h:100
Specifies which parts of an item should be fetched from the Akonadi storage.
Helper integration between Akonadi and Qt.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Nov 28 2023 03:52:31 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.