1/*
2 Copyright (c) 2009 Andras Mantia <amantia@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 KIMAP_GETMETADATAJOB_H
21#define KIMAP_GETMETADATAJOB_H
22
23#include "kimap_export.h"
24
25#include "metadatajobbase.h"
26
27namespace KIMAP {
28
29class Session;
30struct Message;
31class GetMetaDataJobPrivate;
32
33/**
34 * Fetches mailbox metadata.
35 *
36 * Provides support for the IMAP METADATA extension; both the
37 * final RFC version
38 * (<a href="http://tools.ietf.org/html/rfc5464">RFC 5464</a>)
39 * and the older, incompatible draft version (known as ANNOTATEMORE)
40 * (<a
41 * href="http://tools.ietf.org/html/draft-daboo-imap-annotatemore-07"
42 * >draft-daboo-imap-annotatemore-07</a>). See setServerCompatibility().
43 *
44 * This job can only be run when the session is in the
45 * authenticated (or selected) state.
46 *
47 * If the server supports ACLs, the user will need the
48 * Acl::Lookup right on the mailbox, as well as one of
49 * - Acl::Read
50 * - Acl::KeepSeen
51 * - Acl::Write
52 * - Acl::Insert
53 * - Acl::Post
54 * Otherwise, the user must be able to list the mailbox
55 * and either read or write the message content.
56 *
57 * Note also that on servers that implement the Annotatemore
58 * version of the extension, only Acl::Lookup rights are
59 * required (ie: the user must be able to list the mailbox).
60 */
61class KIMAP_EXPORT GetMetaDataJob : public MetaDataJobBase
62{
63 Q_OBJECT
64 Q_DECLARE_PRIVATE( GetMetaDataJob )
65
66 friend class SessionPrivate;
67
68 public:
69 explicit GetMetaDataJob( Session *session );
70 virtual ~GetMetaDataJob();
71
72 /**
73 * Used to specify the depth of the metadata heirachy to walk.
74 */
75 enum Depth {
76 NoDepth = 0, /**< Only the requested entries */
77 OneLevel, /**< The requested entries and all their direct children */
78 AllLevels /**< The requested entries and all their descendants */
79 };
80
81 Q_DECLARE_FLAGS( Depths, Depth )
82
83 /**
84 * Add an entry to the query list.
85 *
86 * See SetMetaDataJob for a description of metadata entry names.
87 *
88 * When operating in Annotatemore mode, you should provide an attribute
89 * name. Typically this will be "value", "value.priv" or "value.shared",
90 * although you might want to fetch the "content-type" or
91 * "content-language" attributes as well.
92 *
93 * @param entry the metadata entry name
94 * @param attribute the attribute name, in Annotatemore mode
95 *
96 * @deprecated use addRequestedEntry(QByteArray) instead
97 */
98 KIMAP_DEPRECATED void addEntry( const QByteArray &entry, const QByteArray &attribute = QByteArray() );
99
100 /**
101 * Add an entry to the query list.
102 *
103 * See SetMetaDataJob for a description of metadata entry names.
104 *
105 * Note that this expects METADATA style entries (with a /shared or /private prefix typically).
106 * In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute.
107 *
108 * @param entry the metadata entry name
109 */
110 void addRequestedEntry( const QByteArray &entry );
111
112 /**
113 * Limits the size of returned metadata entries.
114 *
115 * In order to save time or bandwidth, it is possible to prevent the
116 * server from returning metadata entries that are larger than a
117 * certain size. These entries will simply not appear in the
118 * list returned by allMetaData(), and will not be accessible using
119 * metaData().
120 *
121 * Note that this is only used when the server capability mode is
122 * Metadata.
123 *
124 * The default is no limit (-1). A value of less than -1 will cause
125 * the job to fail.
126 *
127 * @param size the entry size limit, in octets, or -1 for no limit
128 */
129 void setMaximumSize( qint64 size );
130
131 /**
132 * Sets whether to retrieve children or descendants of the requested entries.
133 *
134 * Metadata entry names are heirachical, much like UNIX path names.
135 * It therefore makes sense to ask for an entry and all its children
136 * (OneLevel) or an entry and all its descendants (AllLevels).
137 *
138 * For example, /shared/foo/bar/baz is a child of /shared/foo/bar and a
139 * descendent of /shared/foo. So if you request the entry "/shared/foo"
140 * with depth NoDepth, you will only get the "/shared/foo" entry. If
141 * you set the depth to OneLevel, you will also get "/shared/foo/bar".
142 * If you set the depth to AllLevels, you will also get
143 * "/shared/foo/bar/baz", and every other metadata entry that starts
144 * with "/shared/foo/".
145 *
146 * Note that this is only used when the server capability mode is
147 * Metadata.
148 *
149 * @param depth the depth of the metadata tree to return
150 */
151 void setDepth( Depth depth );
152
153 /**
154 * Get a single metadata entry.
155 *
156 * The metadata must have been requested using addEntry(), and
157 * the job must have completed successfully, or this method
158 * will not return anything.
159 *
160 * Note that if setMaximumSize() was used to limit the size of
161 * returned metadata, this method may return an empty QByteArray
162 * even if the metadata entry was requested and exists on the
163 * server. This will happen when the metadata entry is larger
164 * than the size limit given to setMaximumSize().
165 *
166 * @param mailBox the mailbox the metadata is attached to, or
167 * an empty string for server metadata
168 * @param entry the entry to get
169 * @param attribute (only in Annotatemore mode) the attribute to get
170 * @return the metadata entry value
171 *
172 * @deprecated use metaData(QByteArray entry) instead
173 */
174 // XXX: what's with the mailBox argument in a class that has setMailBox()?
175 // KJobs are not intended to be run more than once
176 KIMAP_DEPRECATED QByteArray metaData( const QString &mailBox, const QByteArray &entry,
177 const QByteArray &attribute = QByteArray() ) const;
178
179 /**
180 * Get a single metadata entry.
181 *
182 * The metadata must have been requested using addEntry(), and
183 * the job must have completed successfully, or this method
184 * will not return anything.
185 *
186 * Note that if setMaximumSize() was used to limit the size of
187 * returned metadata, this method may return an empty QByteArray
188 * even if the metadata entry was requested and exists on the
189 * server. This will happen when the metadata entry is larger
190 * than the size limit given to setMaximumSize().
191 *
192 * Note that this expects METADATA style entries (with a /shared or /private prefix typically).
193 * In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute.
194 *
195 * @param entry the entry to get
196 * @return the metadata entry value
197 */
198 QByteArray metaData( const QByteArray &entry ) const;
199
200 /**
201 * Get all the metadata for a given mailbox.
202 *
203 * The returned map is from metadata entry names to attributes or values.
204 *
205 * If operating in Metadata mode, the metadata value is stored against the
206 * empty QByteArray:
207 * @code
208 * map = job.allMetaData( "INBOX" );
209 * QByteArray value = map[ "/shared/comment" ].value( QByteArray() );
210 * @endcode
211 *
212 * The equivalent in Annotatemore mode would be:
213 * @code
214 * map = job.allMetaData( "INBOX" );
215 * QByteArray value = map[ "/comment" ].value( "value.shared" );
216 * @endcode
217 *
218 * @param mailBox a mailbox name or an empty string for server metadata
219 * @return a map from metadata entry names to attributes or values
220 */
221 // XXX: what's with the mailBox argument in a class that has setMailBox()?
222 // KJobs are not intended to be run more than once
223 QMap<QByteArray, QMap<QByteArray, QByteArray> > allMetaData( const QString &mailBox ) const;
224
225 /**
226 * Get all the metadata.
227 *
228 * Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically),
229 * also in ANNOTATEMORE mode.
230 *
231 * @return a map from metadata entry names to values
232 */
233 QMap<QByteArray, QByteArray> allMetaData() const;
234
235 protected:
236 virtual void doStart();
237 virtual void handleResponse( const Message &response );
238
239};
240
241}
242
243#endif
244