Akonadi

recursiveitemfetchjob.h
1/*
2 SPDX-FileCopyrightText: 2009 Tobias Koenig <tokoe@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
12#include <KJob>
13
14#include <memory>
15
16namespace Akonadi
17{
18class Collection;
19class ItemFetchScope;
20class 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 <tokoe@kde.org>
71 * @since 4.6
72 */
73class AKONADICORE_EXPORT RecursiveItemFetchJob : public KJob
74{
75 Q_OBJECT
76
77public:
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 */
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 [[nodiscard]] Akonadi::Item::List items() const;
123
124 /**
125 * Starts the recursive item fetch job.
126 */
127 void start() override;
128
129private:
130 /// @cond PRIVATE
131 friend class RecursiveItemFetchJobPrivate;
132 std::unique_ptr<RecursiveItemFetchJobPrivate> const d;
133 /// @endcond
134};
135
136}
Represents a collection of PIM items.
Definition collection.h:62
Specifies which parts of an item should be fetched from the Akonadi storage.
Job that fetches all items of a collection recursive.
~RecursiveItemFetchJob() override
Destroys the recursive item fetch job.
Q_SCRIPTABLE Q_NOREPLY void start()
Helper integration between Akonadi and Qt.
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.