KIMAP2

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

KDE's Doxygen guidelines are available online.