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  /**
126  * Convenience ctor equivalent to ItemFetchJob(const Item::List &items, QObject *parent = nullptr)
127  * @since 5.4
128  */
129  explicit ItemFetchJob(const QVector<Item::Id> &items, QObject *parent = nullptr);
130 
131  /**
132  * Creates a new item fetch job that retrieves all items tagged with specified @p tag.
133  *
134  * @param tag The tag to fetch all items from.
135  * @param parent The parent object.
136  *
137  * @since 4.14
138  */
139  explicit ItemFetchJob(const Tag &tag, QObject *parent = nullptr);
140 
141  /**
142  * Destroys the item fetch job.
143  */
144  ~ItemFetchJob() override;
145 
146  /**
147  * Returns the fetched items.
148  *
149  * This returns an empty list when not using the ItemGetter DeliveryOption.
150  *
151  * @note The items are invalid before the result(KJob*)
152  * signal has been emitted or if an error occurred.
153  */
154  Q_REQUIRED_RESULT Item::List items() const;
155 
156  /**
157  * Save memory by clearing the fetched items.
158  * @since 4.12
159  */
160  void clearItems();
161 
162  /**
163  * Sets the item fetch scope.
164  *
165  * The ItemFetchScope controls how much of an item's data is fetched
166  * from the server, e.g. whether to fetch the full item payload or
167  * only meta data.
168  *
169  * @param fetchScope The new scope for item fetch operations.
170  *
171  * @see fetchScope()
172  * @since 4.4
173  */
174  void setFetchScope(const ItemFetchScope &fetchScope);
175 
176  /**
177  * Returns the item fetch scope.
178  *
179  * Since this returns a reference it can be used to conveniently modify the
180  * current scope in-place, i.e. by calling a method on the returned reference
181  * without storing it in a local variable. See the ItemFetchScope documentation
182  * for an example.
183  *
184  * @return a reference to the current item fetch scope
185  *
186  * @see setFetchScope() for replacing the current item fetch scope
187  */
188  ItemFetchScope &fetchScope();
189 
190  /**
191  * Specifies the collection the item is in.
192  * This is only required when retrieving an item based on its remote id
193  * which might not be unique globally.
194  *
195  * @internal
196  * @see ResourceSelectJob (for internal use only)
197  * @endinternal
198  */
199  void setCollection(const Collection &collection);
200 
202  ItemGetter = 0x1, ///< items available through items()
203  EmitItemsIndividually = 0x2, ///< emitted via signal upon reception
204  EmitItemsInBatches = 0x4, ///< emitted via signal in bulk (collected and emitted delayed via timer)
205  Default = ItemGetter | EmitItemsInBatches
206  };
207  Q_DECLARE_FLAGS(DeliveryOptions, DeliveryOption)
208 
209  /**
210  * Sets the mechanisms by which the items should be fetched
211  * @since 4.13
212  */
213  void setDeliveryOption(DeliveryOptions options);
214 
215  /**
216  * Returns the delivery options
217  * @since 4.13
218  */
219  DeliveryOptions deliveryOptions() const;
220 
221  /**
222  * Returns the total number of retrieved items.
223  * This works also without the ItemGetter DeliveryOption.
224  * @since 4.14
225  */
226  int count() const;
227 
228  /**
229  * Sets the limit of fetched items.
230  *
231  * @param limit the maximum number of items to retrieve.
232  * The default value for @p limit is -1, indicating no limit.
233  * @param start specifies the offset of the first item to retrieve.
234  * @param order specifies whether items will be fetched
235  * starting with the highest or lowest ID of the item.
236  */
237 
238  void setLimit(int limit, int start, Qt::SortOrder order = Qt::DescendingOrder);
239 
240 Q_SIGNALS:
241  /**
242  * This signal is emitted whenever new items have been fetched completely.
243  *
244  * @note This is an optimization; instead of waiting for the end of the job
245  * and calling items(), you can connect to this signal and get the items
246  * incrementally.
247  *
248  * @param items The fetched items.
249  */
250  void itemsReceived(const Akonadi::Item::List &items);
251 
252 protected:
253  void doStart() override;
254  bool doHandleResponse(qint64 tag, const Protocol::CommandPtr &response) override;
255 
256 private:
257  Q_DECLARE_PRIVATE(ItemFetchJob)
258 };
259 
260 }
261 
262 Q_DECLARE_OPERATORS_FOR_FLAGS(Akonadi::ItemFetchJob::DeliveryOptions)
263 
Represents a collection of PIM items.
Definition: collection.h:61
Base class for all actions in the Akonadi storage.
Definition: job.h:80
Specifies which parts of an item should be fetched from the Akonadi storage.
Helper integration between Akonadi and Qt.
Job that fetches items from the Akonadi storage.
Definition: itemfetchjob.h:69
An Akonadi Tag.
Definition: tag.h:25
Represents a PIM item stored in Akonadi storage.
Definition: item.h:100
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sun Nov 28 2021 23:08:20 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.