KIMAP2

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

KDE's Doxygen guidelines are available online.