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