1/*
2 Copyright (c) 2009 Tobias Koenig <tokoe@kde.org>
3
4 This library is free software; you can redistribute it and/or modify it
5 under the terms of the GNU Library General Public License as published by
6 the Free Software Foundation; either version 2 of the License, or (at your
7 option) any later version.
8
9 This library is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
12 License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to the
16 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
17 02110-1301, USA.
18*/
19
20#ifndef AKONADI_RECURSIVEITEMFETCHJOB_H
21#define AKONADI_RECURSIVEITEMFETCHJOB_H
22
23#include "akonadi_export.h"
24
25#include <akonadi/item.h>
26#include <kjob.h>
27
28namespace Akonadi {
29
30class Collection;
31class ItemFetchScope;
32
33/**
34 * @short Job that fetches all items of a collection recursive.
35 *
36 * This job takes a collection as argument and returns a list of
37 * all items that are part of the passed collection and its child
38 * collections. The items to fetch can be filtered by mime types and
39 * the parts of the items that shall be fetched can
40 * be specified via an ItemFetchScope.
41 *
42 * Example:
43 *
44 * @code
45 *
46 * // Assume the following Akonadi storage tree structure:
47 * //
48 * // Root Collection
49 * // |
50 * // +- Contacts
51 * // | |
52 * // | +- Private
53 * // | |
54 * // | `- Business
55 * // |
56 * // `- Events
57 * //
58 * // Collection 'Contacts' has the ID 15, then the following code
59 * // returns all contact items from 'Contacts', 'Private' and 'Business'.
60 *
61 * const Akonadi::Collection contactsCollection( 15 );
62 * const QStringList mimeTypes = QStringList() << KABC::Addressee::mimeType();
63 *
64 * Akonadi::RecursiveItemFetchJob *job = new Akonadi::RecursiveItemFetchJob( contactsCollection, mimeTypes );
65 * job->fetchScope().fetchFullPayload();
66 * connect( job, SIGNAL(result(KJob*)), this, SLOT(fetchResult(KJob*)) );
67 *
68 * job->start();
69 *
70 * ...
71 *
72 * MyClass::fetchResult( KJob *job )
73 * {
74 * Akonadi::RecursiveItemFetchJob *fetchJob = qobject_cast<Akonadi::RecursiveItemFetchJob*>( job );
75 * const Akonadi::Item::List items = fetchJob->items();
76 * // do something with the items
77 * }
78 *
79 * @endcode
80 *
81 * @author Tobias Koenig <tokoe@kde.org>
82 * @since 4.6
83 */
84class AKONADI_EXPORT RecursiveItemFetchJob : public KJob
85{
86 Q_OBJECT
87
88public:
89 /**
90 * Creates a new recursive item fetch job.
91 *
92 * @param collection The collection that shall be fetched recursive.
93 * @param mimeTypes The list of mime types that will be used for filtering.
94 * @param parent The parent object.
95 */
96 explicit RecursiveItemFetchJob(const Akonadi::Collection &collection,
97 const QStringList &mimeTypes,
98 QObject *parent = 0);
99
100 /**
101 * Destroys the recursive item fetch job.
102 */
103 ~RecursiveItemFetchJob();
104
105 /**
106 * Sets the item fetch scope.
107 *
108 * The ItemFetchScope controls how much of an item's data is fetched
109 * from the server, e.g. whether to fetch the full item payload or
110 * only meta data.
111 *
112 * @param fetchScope The new scope for item fetch operations.
113 *
114 * @see fetchScope()
115 */
116 void setFetchScope(const Akonadi::ItemFetchScope &fetchScope);
117
118 /**
119 * Returns the item fetch scope.
120 *
121 * Since this returns a reference it can be used to conveniently modify the
122 * current scope in-place, i.e. by calling a method on the returned reference
123 * without storing it in a local variable. See the ItemFetchScope documentation
124 * for an example.
125 *
126 * @return a reference to the current item fetch scope
127 *
128 * @see setFetchScope() for replacing the current item fetch scope
129 */
130 Akonadi::ItemFetchScope &fetchScope();
131
132 /**
133 * Returns the list of fetched items.
134 */
135 Akonadi::Item::List items() const;
136
137 /**
138 * Starts the recursive item fetch job.
139 */
140 virtual void start();
141
142private:
143 //@cond PRIVATE
144 class Private;
145 Private *const d;
146
147 Q_PRIVATE_SLOT(d, void collectionFetchResult(KJob *))
148 Q_PRIVATE_SLOT(d, void itemFetchResult(KJob *))
149 //@endcond
150};
151
152}
153
154#endif
155