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 | |
27 | namespace KIMAP { |
28 | |
29 | class Session; |
30 | struct Message; |
31 | class 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 | */ |
68 | class 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 | |
215 | Q_DECLARE_OPERATORS_FOR_FLAGS( KIMAP::SetMetaDataJob::MetaDataErrors ) |
216 | |
217 | #endif |
218 | |