Akonadi

recursiveitemfetchjob.h
1 /*
2  SPDX-FileCopyrightText: 2009 Tobias Koenig <[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 
12 #include <KJob>
13 
14 #include <memory>
15 
16 namespace Akonadi
17 {
18 class Collection;
19 class ItemFetchScope;
20 class RecursiveItemFetchJobPrivate;
21 
22 /**
23  * @short Job that fetches all items of a collection recursive.
24  *
25  * This job takes a collection as argument and returns a list of
26  * all items that are part of the passed collection and its child
27  * collections. The items to fetch can be filtered by mime types and
28  * the parts of the items that shall be fetched can
29  * be specified via an ItemFetchScope.
30  *
31  * Example:
32  *
33  * @code
34  *
35  * // Assume the following Akonadi storage tree structure:
36  * //
37  * // Root Collection
38  * // |
39  * // +- Contacts
40  * // | |
41  * // | +- Private
42  * // | |
43  * // | `- Business
44  * // |
45  * // `- Events
46  * //
47  * // Collection 'Contacts' has the ID 15, then the following code
48  * // returns all contact items from 'Contacts', 'Private' and 'Business'.
49  *
50  * const Akonadi::Collection contactsCollection( 15 );
51  * const QStringList mimeTypes = QStringList() << KContacts::Addressee::mimeType();
52  *
53  * Akonadi::RecursiveItemFetchJob *job = new Akonadi::RecursiveItemFetchJob( contactsCollection, mimeTypes );
54  * job->fetchScope().fetchFullPayload();
55  * connect( job, SIGNAL(result(KJob*)), this, SLOT(fetchResult(KJob*)) );
56  *
57  * job->start();
58  *
59  * ...
60  *
61  * MyClass::fetchResult( KJob *job )
62  * {
63  * Akonadi::RecursiveItemFetchJob *fetchJob = qobject_cast<Akonadi::RecursiveItemFetchJob*>( job );
64  * const Akonadi::Item::List items = fetchJob->items();
65  * // do something with the items
66  * }
67  *
68  * @endcode
69  *
70  * @author Tobias Koenig <[email protected]>
71  * @since 4.6
72  */
73 class AKONADICORE_EXPORT RecursiveItemFetchJob : public KJob
74 {
75  Q_OBJECT
76 
77 public:
78  /**
79  * Creates a new recursive item fetch job.
80  *
81  * @param collection The collection that shall be fetched recursive.
82  * @param mimeTypes The list of mime types that will be used for filtering.
83  * @param parent The parent object.
84  */
85  explicit RecursiveItemFetchJob(const Akonadi::Collection &collection, const QStringList &mimeTypes, QObject *parent = nullptr);
86 
87  /**
88  * Destroys the recursive item fetch job.
89  */
90  ~RecursiveItemFetchJob() override;
91 
92  /**
93  * Sets the item fetch scope.
94  *
95  * The ItemFetchScope controls how much of an item's data is fetched
96  * from the server, e.g. whether to fetch the full item payload or
97  * only meta data.
98  *
99  * @param fetchScope The new scope for item fetch operations.
100  *
101  * @see fetchScope()
102  */
103  void setFetchScope(const Akonadi::ItemFetchScope &fetchScope);
104 
105  /**
106  * Returns the item fetch scope.
107  *
108  * Since this returns a reference it can be used to conveniently modify the
109  * current scope in-place, i.e. by calling a method on the returned reference
110  * without storing it in a local variable. See the ItemFetchScope documentation
111  * for an example.
112  *
113  * @return a reference to the current item fetch scope
114  *
115  * @see setFetchScope() for replacing the current item fetch scope
116  */
117  Akonadi::ItemFetchScope &fetchScope();
118 
119  /**
120  * Returns the list of fetched items.
121  */
122  Q_REQUIRED_RESULT Akonadi::Item::List items() const;
123 
124  /**
125  * Starts the recursive item fetch job.
126  */
127  void start() override;
128 
129 private:
130  /// @cond PRIVATE
131  friend class RecursiveItemFetchJobPrivate;
132  std::unique_ptr<RecursiveItemFetchJobPrivate> const d;
133  /// @endcond
134 };
135 
136 }
137 
Q_SCRIPTABLE Q_NOREPLY void start()
Represents a collection of PIM items.
Definition: collection.h:61
Job that fetches all items of a collection recursive.
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-2022 The KDE developers.
Generated on Mon Jun 27 2022 04:01:07 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.