KIMAP

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

KDE's Doxygen guidelines are available online.