KIMAP

setmetadatajob.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 SetMetaDataJobPrivate;
18
19/**
20 * Sets 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 * Note that in Annotatemore mode, this job can only operate on
31 * one metadata entry at once.
32 *
33 * This job can only be run when the session is in the
34 * authenticated (or selected) state.
35 *
36 * If the server supports ACLs, the user will need the
37 * Acl::Lookup right on the mailbox, as well as one of
38 * - Acl::Read
39 * - Acl::KeepSeen
40 * - Acl::Write
41 * - Acl::Insert
42 * - Acl::Post
43 * Otherwise, the user must be able to list the mailbox
44 * and either read or write the message content.
45 *
46 * Note that even if the user has these permissions, the
47 * server may refuse to allow the user to write metadata
48 * based on some other criteria.
49 *
50 * Note also that on servers that implement the Annotatemore
51 * version of the extension, only Acl::Lookup rights are
52 * required (ie: the user must be able to list the mailbox).
53 */
54class KIMAP_EXPORT SetMetaDataJob : public MetaDataJobBase
55{
56 Q_OBJECT
57 Q_DECLARE_PRIVATE(SetMetaDataJob)
58
59 friend class SessionPrivate;
60
61public:
62 explicit SetMetaDataJob(Session *session);
63 ~SetMetaDataJob() override;
64
65 /**
66 * Adds a metadata entry or attribute to the list of modifications to make
67 *
68 * When in Metadata mode, this method adds a metadata
69 * entry to the list of metadata additions and updates that
70 * will be performed when the job is run.
71 *
72 * @p name must be a valid ASCII string and may not contain two
73 * consecutive forward slashes ('/'), must not end with '/' and
74 * must not contain '*', '%', non-ASCII characters or characters
75 * in the ASCII range 0x00 to 0x19 (in practice, all control
76 * characters should be avoided). The name is case-insensitive.
77 *
78 * The first part of the entry name should be "/private" or
79 * "/shared", indicating the scope of the entry. Note that
80 * private metadata may not be supported by all servers.
81 *
82 * Server metadata entry names include:
83 * - /shared/comment
84 * - /shared/admin - a URI for contacting the server administrator
85 * (eg: a mailto: or tel: URI)
86 * - /shared/vendor/<vendor-token>/something
87 * - /private/vendor/<vendor-token>/something
88 *
89 * Mailbox metadata entry names include:
90 * - /shared/comment
91 * - /private/comment
92 * - /shared/vendor/<vendor-token>/something
93 * - /private/vendor/<vendor-token>/something
94 *
95 * @p value can be any data, although if it is a multi-line string
96 * value, CRLF line-endings must be used.
97 *
98 * In Annotatemore mode it is possible to prefix the entry name with a /shared or /private prefix, that is automatically translated
99 * to an appropriate value.shared|priv attribute.
100 *
101 * Annotatemore legacy mode:
102 * When in Annotatemore mode, this method adds an attribute
103 * entry to the list of additions and updates that will be
104 * performed on the metadata entry when the job is run.
105 *
106 * @p name must be a valid UTF-8 string, and may not contain the
107 * '%' or '*' characters, or NUL. Use of non-visible UTF-8 characters
108 * is strongly discouraged.
109 *
110 * Possible attribute name prefixes are:
111 * - value - the data value of the attribute
112 * - content-type - a MIME content type and subtype
113 * - content-language - a RFC 3282 language code
114 * - vendor.<vendor-token> - a vendor-specific attribute
115 *
116 * Attribute names an attribute name prefix followed by ".priv" for
117 * private attributes or ".shared" for shared attributes. Note that
118 * the attributes "size.priv" and "size.shared" are read-only
119 * attributes set by the server, and so cannot be used with
120 * SetMetaDataJob.
121 *
122 * @param name the metadata entry name (Metadata or Annotatemore mode) in ASCII or
123 * attribute name (Annotatemore mode, if used without /shared or /private prefix) in UTF-8
124 * @param value the value of the entry or attribute
125 */
126 // KDE5: drop ANNOTATEMORE support
127 void addMetaData(const QByteArray &name, const QByteArray &value);
128
129 /**
130 * Sets the metadata entry name to operate on (in Annotatemore mode)
131 *
132 * In Annotatemore mode, this specifies the metadata entry name to
133 * operate on. For server metadata, this is one of:
134 * - /comment
135 * - /motd
136 * - /admin
137 * - /vendor/<vendor-token>/something
138 *
139 * For mailbox metadata, this is one of:
140 * - /comment
141 * - /sort
142 * - /thread
143 * - /check
144 * - /checkperiod
145 * - /vendor/<vendor-token>/something
146 *
147 * Entry names must be valid UTF-8 strings that do not contain the
148 * '%' or '*' characters, or NUL. Use of non-visible UTF-8
149 * characters is strongly discouraged.
150 *
151 * In Metadata mode, this has no effect. Metadata entry names
152 * should instead be specified as the first argument to addMetaData().
153 *
154 * @see setServerCapability()
155 *
156 * @param entry the metadata entry name in UTF-8
157 *
158 * @deprecated Use a /shared or /private prefix with addMetaData instead.
159 */
160 // KDE5: remove
161 KIMAP_DEPRECATED void setEntry(const QByteArray &entry);
162
163 /**
164 * Possible error codes that may be returned by the server.
165 */
167 NoError = 0, /**< Used to indicate that no errors have been received */
168 TooMany = 1, /**< Cannot add a new metadata item, because the limit has already been reached */
169 TooBig = 2, /**< A metadata value was too big (see maxAcceptedSize()) */
170 NoPrivate = 4 /**< The server does not support private metadata entries */
171 };
172
173 // Q_DECLARE_WHATEVER_THAT_WAS missing
174 Q_DECLARE_FLAGS(MetaDataErrors, MetaDataError)
175
176 /**
177 * The metadata errors received from the server.
178 *
179 * @return a set of error codes
180 */
181 [[nodiscard]] MetaDataErrors metaDataErrors() const;
182 /**
183 * The maximum accepted metadata size.
184 *
185 * If the server replied that one of the metadata values was too
186 * large (see metaDataErrors), this should indicate what the
187 * maximum size accepted by the server is.
188 *
189 * @return the maximum value size in octets, or -1 if the limit is unknown
190 */
191 [[nodiscard]] qint64 maxAcceptedSize();
192
193protected:
194 void doStart() override;
195 void handleResponse(const Response &response) override;
196};
197
198}
199
200Q_DECLARE_OPERATORS_FOR_FLAGS(KIMAP::SetMetaDataJob::MetaDataErrors)
Base class for jobs that operate on mailbox metadata.
Sets mailbox metadata.
qint64 maxAcceptedSize()
The maximum accepted metadata size.
MetaDataError
Possible error codes that may be returned by the server.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Tue Mar 26 2024 11:14:37 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.