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
Base class for jobs that operate on mailbox metadata.
MetaDataError
Possible error codes that may be returned by the server.
Sets mailbox metadata.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Feb 7 2023 04:11:30 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.