summaryrefslogtreecommitdiff
path: root/kimap/setmetadatajob.h
blob: 1391ecc35dadf34ab511c9111f940d6a01d0dc70 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
/*
    Copyright (c) 2009 Andras Mantia <amantia@kde.org>

    This library is free software; you can redistribute it and/or modify it
    under the terms of the GNU Library General Public License as published by
    the Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This library is distributed in the hope that it will be useful, but WITHOUT
    ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
    FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
    License for more details.

    You should have received a copy of the GNU Library General Public License
    along with this library; see the file COPYING.LIB.  If not, write to the
    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
    02110-1301, USA.
*/

#ifndef KIMAP_SETMETADATAJOB_H
#define KIMAP_SETMETADATAJOB_H

#include "kimap_export.h"

#include "metadatajobbase.h"

namespace KIMAP {

class Session;
struct Message;
class SetMetaDataJobPrivate;

/**
 * Sets mailbox metadata.
 *
 * Provides support for the IMAP METADATA extension; both the
 * final RFC version
 * (<a href="http://tools.ietf.org/html/rfc5464">RFC 5464</a>)
 * and the older, incompatible draft version (known as ANNOTATEMORE)
 * (<a
 * href="http://tools.ietf.org/html/draft-daboo-imap-annotatemore-07"
 * >draft-daboo-imap-annotatemore-07</a>).  See setServerCompatibility().
 *
 * Note that in Annotatemore mode, this job can only operate on
 * one metadata entry at once.
 *
 * This job can only be run when the session is in the
 * authenticated (or selected) state.
 *
 * If the server supports ACLs, the user will need the
 * Acl::Lookup right on the mailbox, as well as one of
 * - Acl::Read
 * - Acl::KeepSeen
 * - Acl::Write
 * - Acl::Insert
 * - Acl::Post
 * Otherwise, the user must be able to list the mailbox
 * and either read or write the message content.
 *
 * Note that even if the user has these permissions, the
 * server may refuse to allow the user to write metadata
 * based on some other criteria.
 *
 * Note also that on servers that implement the Annotatemore
 * version of the extension, only Acl::Lookup rights are
 * required (ie: the user must be able to list the mailbox).
 */
class KIMAP_EXPORT SetMetaDataJob : public MetaDataJobBase
{
  Q_OBJECT
  Q_DECLARE_PRIVATE(SetMetaDataJob)

  friend class SessionPrivate;

  public:
    explicit SetMetaDataJob( Session *session );
    virtual ~SetMetaDataJob();

    /**
     * Adds a metadata entry or attribute to the list of modifications to make
     *
     * When in Metadata mode, this method adds a metadata
     * entry to the list of metadata additions and updates that
     * will be performed when the job is run.
     *
     * @p name must be a valid ASCII string and may not contain two
     * consecutive forward slashes ('/'), must not end with '/' and
     * must not contain '*', '%', non-ASCII characters or characters
     * in the ASCII range 0x00 to 0x19 (in practice, all control
     * characters should be avoided).  The name is case-insensitive.
     *
     * The first part of the entry name should be "/private" or
     * "/shared", indicating the scope of the entry.  Note that
     * private metadata may not be supported by all servers.
     *
     * Server metadata entry names include:
     * - /shared/comment
     * - /shared/admin - a URI for contacting the server administrator
     *                   (eg: a mailto: or tel: URI)
     * - /shared/vendor/<vendor-token>/something
     * - /private/vendor/<vendor-token>/something
     *
     * Mailbox metadata entry names include:
     * - /shared/comment
     * - /private/comment
     * - /shared/vendor/<vendor-token>/something
     * - /private/vendor/<vendor-token>/something
     *
     * @p value can be any data, although if it is a multi-line string
     * value, CRLF line-endings must be used.
     *
     * When in Annotatemore mode, this method adds an attribute
     * entry to the list of additions and updates that will be
     * performed on the metadata entry when the job is run.
     *
     * @p name must be a valid UTF-8 string, and may not contain the
     * '%' or '*' characters, or NUL.  Use of non-visible UTF-8 characters
     * is strongly discouraged.
     *
     * Possible attribute name prefixes are:
     * - value - the data value of the attribute
     * - content-type - a MIME content type and subtype
     * - content-language - a RFC 3282 language code
     * - vendor.<vendor-token> - a vendor-specific attribute
     *
     * Attribute names an attribute name prefix followed by ".priv" for
     * private attributes or ".shared" for shared attributes.  Note that
     * the attributes "size.priv" and "size.shared" are read-only
     * attributes set by the server, and so cannot be used with
     * SetMetaDataJob.
     *
     * @param name   the metadata entry name (Metadata mode) in ASCII or
     *               attribute name (Annotatemore mode) in UTF-8
     * @param value  the value of the entry or attribute
     */
    void addMetaData(const QByteArray &name, const QByteArray &value);

    /**
     * Sets the metadata entry name to operate on (in Annotatemore mode)
     *
     * In Annotatemore mode, this specifies the metadata entry name to
     * operate on.  For server metadata, this is one of:
     * - /comment
     * - /motd
     * - /admin
     * - /vendor/<vendor-token>/something
     *
     * For mailbox metadata, this is one of:
     * - /comment
     * - /sort
     * - /thread
     * - /check
     * - /checkperiod
     * - /vendor/<vendor-token>/something
     *
     * Entry names must be valid UTF-8 strings that do not contain the
     * '%' or '*' characters, or NUL.  Use of non-visible UTF-8
     * characters is strongly discouraged.
     *
     * In Metadata mode, this has no effect.  Metadata entry names
     * should instead be specified as the first argument to addMetaData().
     *
     * @see setServerCapability()
     *
     * @param entry  the metadata entry name in UTF-8
     */
    // KDE5: this API is horrible for Annotatemore mode: use an overload of
    //       addMetaData() instead:
    //       void addMetaData(const QString &entry, const QByteArray &value,
    //                        const QByteArray &encoding = QByteArray(),
    //                        const QByteArray &language = QByteArray(),
    //                        const QMap<QString,QByteArray> vendorAttributes =
    //                        QMap<QString,QByteArray>());
    void setEntry(const QByteArray &entry);

    /**
     * Possible error codes that may be returned by the server.
     */
    enum MetaDataError {
      NoError = 0,  /**< Used to indicate that no errors have been received */
      TooMany = 1,  /**< Cannot add a new metadata item, because the limit has already been reached */
      TooBig = 2,   /**< A metadata value was too big (see maxAcceptedSize()) */
      NoPrivate = 4 /**< The server does not support private metadata entries */
    };

    // Q_DECLARE_WHATEVER_THAT_WAS missing
    Q_DECLARE_FLAGS(MetaDataErrors, MetaDataError)

    /**
     * The metadata errors received from the server.
     *
     * @return  a set of error codes
     */
    MetaDataErrors metaDataErrors() const;
    /**
     * The maximum accepted metadata size.
     *
     * If the server replied that one of the metadata values was too
     * large (see metaDataErrors), this should indicate what the
     * maximum size accepted by the server is.
     *
     * @return  the maximum value size in octets, or -1 if the limit is unknown
     */
    qint64 maxAcceptedSize();

  protected:
    virtual void doStart();
    virtual void handleResponse( const Message &response );

};

}

Q_DECLARE_OPERATORS_FOR_FLAGS( KIMAP::SetMetaDataJob::MetaDataErrors )

#endif