1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
/*
Copyright (c) 2006 - 2007 Volker Krause <vkrause@kde.org>
This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Library General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301, USA.
*/
#ifndef AKONADI_COLLECTIONFETCHJOB_H
#define AKONADI_COLLECTIONFETCHJOB_H
#include "akonadi_export.h"
#include <akonadi/collection.h>
#include <akonadi/job.h>
namespace Akonadi {
class CollectionFetchScope;
class CollectionFetchJobPrivate;
/**
* @short Job that fetches collections from the Akonadi storage.
*
* This class can be used to retrieve the complete or partial collection tree
* from the Akonadi storage. This fetches collection data, not item data.
*
* @code
*
* using namespace Akonadi;
*
* // fetching all collections containing emails recursively, starting at the root collection
* CollectionFetchJob *job = new CollectionFetchJob( Collection::root(), CollectionFetchJob::Recursive, this );
* job->fetchScope().setContentMimeTypes( QStringList() << "message/rfc822" );
* connect( job, SIGNAL( collectionsReceived( const Akonadi::Collection::List& ) ),
* this, SLOT( myCollectionsReceived( const Akonadi::Collection::List& ) ) );
* connect( job, SIGNAL( result( KJob* ) ), this, SLOT( collectionFetchResult( KJob* ) ) );
*
* @endcode
*
* @author Volker Krause <vkrause@kde.org>
*/
class AKONADI_EXPORT CollectionFetchJob : public Job
{
Q_OBJECT
public:
/**
* Describes the type of fetch depth.
*/
enum Type
{
Base, ///< Only fetch the base collection.
FirstLevel, ///< Only list direct sub-collections of the base collection.
Recursive, ///< List all sub-collections.
NonOverlappingRoots ///< List the roots of a list of fetched collections. @since 4.7
};
/**
* Creates a new collection fetch job. If the given base collection
* has a unique identifier, this is used to identify the collection in the
* Akonadi server. If only a remote identifier is avaiable the collection
* is identified using that, provided that a resource search context has
* been specified. There are two ways of doing that: by calling
* setResource(), or globally using Akonadi::ResourceSelectJob.
*
* @param collection The base collection for the listing.
* @param type The type of fetch depth.
* @param parent The parent object.
*/
explicit CollectionFetchJob( const Collection &collection, Type type = FirstLevel, QObject *parent = 0 );
/**
* Creates a new collection fetch job to retrieve a list of collections.
* The same rules for identifiers apply as noted in the constructor
* description.
*
* @param collections A list of collections to fetch. Must not be empty.
* @param parent The parent object.
*/
explicit CollectionFetchJob( const Collection::List &collections, QObject *parent = 0 );
/**
* Creates a new collection fetch job to retrieve a list of collections.
* The same rules for identifiers apply as noted in the constructor
* description.
*
* @param collections A list of collections to fetch. Must not be empty.
* @param type The type of fetch depth.
* @param parent The parent object.
* @todo KDE5 merge with ctor above.
* @since 4.7
*/
CollectionFetchJob( const Collection::List &collections, Type type, QObject *parent = 0 );
/**
* Convenience ctor equivalent to CollectionFetchJob( const Collection::List &collections, Type type, QObject *parent = 0 )
* @since 4.8
*/
explicit CollectionFetchJob( const QList<Collection::Id> &collections, Type type = Base, QObject *parent = 0 );
/**
* Destroys the collection fetch job.
*/
virtual ~CollectionFetchJob();
/**
* Returns the list of fetched collection.
*/
Collection::List collections() const;
/**
* Sets a resource identifier to limit collection listing to one resource.
*
* @param resource The resource identifier.
* @deprecated Use CollectionFetchScope instead.
*/
KDE_DEPRECATED void setResource( const QString &resource );
/**
* Include also unsubscribed collections.
* @deprecated Use CollectionFetchScope instead.
*/
KDE_DEPRECATED void includeUnsubscribed( bool include = true );
/**
* Include also statistics about the collections.
*
* @since 4.3
* @deprecated Use CollectionFetchScope instead.
*/
KDE_DEPRECATED void includeStatistics( bool include = true );
/**
* Sets the collection fetch scope.
*
* The CollectionFetchScope controls how much of a collection's data is
* fetched from the server as well as a filter to select which collections
* to fetch.
*
* @param fetchScope The new scope for collection fetch operations.
*
* @see fetchScope()
* @since 4.4
*/
void setFetchScope( const CollectionFetchScope &fetchScope );
/**
* Returns the collection fetch scope.
*
* Since this returns a reference it can be used to conveniently modify the
* current scope in-place, i.e. by calling a method on the returned reference
* without storing it in a local variable. See the CollectionFetchScope documentation
* for an example.
*
* @return a reference to the current collection fetch scope
*
* @see setFetchScope() for replacing the current collection fetch scope
* @since 4.4
*/
CollectionFetchScope &fetchScope();
Q_SIGNALS:
/**
* This signal is emitted whenever the job has received collections.
*
* @param collections The received collections.
*/
void collectionsReceived( const Akonadi::Collection::List &collections );
protected:
virtual void doStart();
virtual void doHandleResponse( const QByteArray &tag, const QByteArray &data );
protected Q_SLOTS:
//@cond PRIVATE
void slotResult( KJob* job );
//@endcond
private:
Q_DECLARE_PRIVATE( CollectionFetchJob )
//@cond PRIVATE
Q_PRIVATE_SLOT( d_func(), void timeout() )
Q_PRIVATE_SLOT( d_func(), void subJobCollectionReceived(const Akonadi::Collection::List &) )
//@endcond
};
}
#endif
|