File indexing completed on 2024-05-12 05:17:17
0001 /* 0002 SPDX-FileCopyrightText: 2009 Andras Mantia <amantia@kde.org> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #pragma once 0008 0009 #include "kimap_export.h" 0010 0011 #include "metadatajobbase.h" 0012 0013 namespace KIMAP 0014 { 0015 class Session; 0016 struct Response; 0017 class SetMetaDataJobPrivate; 0018 0019 /** 0020 * Sets mailbox metadata. 0021 * 0022 * Provides support for the IMAP METADATA extension; both the 0023 * final RFC version 0024 * (<a href="https://tools.ietf.org/html/rfc5464">RFC 5464</a>) 0025 * and the older, incompatible draft version (known as ANNOTATEMORE) 0026 * (<a 0027 * href="https://tools.ietf.org/html/draft-daboo-imap-annotatemore-07" 0028 * >draft-daboo-imap-annotatemore-07</a>). See setServerCompatibility(). 0029 * 0030 * Note that in Annotatemore mode, this job can only operate on 0031 * one metadata entry at once. 0032 * 0033 * This job can only be run when the session is in the 0034 * authenticated (or selected) state. 0035 * 0036 * If the server supports ACLs, the user will need the 0037 * Acl::Lookup right on the mailbox, as well as one of 0038 * - Acl::Read 0039 * - Acl::KeepSeen 0040 * - Acl::Write 0041 * - Acl::Insert 0042 * - Acl::Post 0043 * Otherwise, the user must be able to list the mailbox 0044 * and either read or write the message content. 0045 * 0046 * Note that even if the user has these permissions, the 0047 * server may refuse to allow the user to write metadata 0048 * based on some other criteria. 0049 * 0050 * Note also that on servers that implement the Annotatemore 0051 * version of the extension, only Acl::Lookup rights are 0052 * required (ie: the user must be able to list the mailbox). 0053 */ 0054 class KIMAP_EXPORT SetMetaDataJob : public MetaDataJobBase 0055 { 0056 Q_OBJECT 0057 Q_DECLARE_PRIVATE(SetMetaDataJob) 0058 0059 friend class SessionPrivate; 0060 0061 public: 0062 explicit SetMetaDataJob(Session *session); 0063 ~SetMetaDataJob() override; 0064 0065 /** 0066 * Adds a metadata entry or attribute to the list of modifications to make 0067 * 0068 * When in Metadata mode, this method adds a metadata 0069 * entry to the list of metadata additions and updates that 0070 * will be performed when the job is run. 0071 * 0072 * @p name must be a valid ASCII string and may not contain two 0073 * consecutive forward slashes ('/'), must not end with '/' and 0074 * must not contain '*', '%', non-ASCII characters or characters 0075 * in the ASCII range 0x00 to 0x19 (in practice, all control 0076 * characters should be avoided). The name is case-insensitive. 0077 * 0078 * The first part of the entry name should be "/private" or 0079 * "/shared", indicating the scope of the entry. Note that 0080 * private metadata may not be supported by all servers. 0081 * 0082 * Server metadata entry names include: 0083 * - /shared/comment 0084 * - /shared/admin - a URI for contacting the server administrator 0085 * (eg: a mailto: or tel: URI) 0086 * - /shared/vendor/<vendor-token>/something 0087 * - /private/vendor/<vendor-token>/something 0088 * 0089 * Mailbox metadata entry names include: 0090 * - /shared/comment 0091 * - /private/comment 0092 * - /shared/vendor/<vendor-token>/something 0093 * - /private/vendor/<vendor-token>/something 0094 * 0095 * @p value can be any data, although if it is a multi-line string 0096 * value, CRLF line-endings must be used. 0097 * 0098 * In Annotatemore mode it is possible to prefix the entry name with a /shared or /private prefix, that is automatically translated 0099 * to an appropriate value.shared|priv attribute. 0100 * 0101 * Annotatemore legacy mode: 0102 * When in Annotatemore mode, this method adds an attribute 0103 * entry to the list of additions and updates that will be 0104 * performed on the metadata entry when the job is run. 0105 * 0106 * @p name must be a valid UTF-8 string, and may not contain the 0107 * '%' or '*' characters, or NUL. Use of non-visible UTF-8 characters 0108 * is strongly discouraged. 0109 * 0110 * Possible attribute name prefixes are: 0111 * - value - the data value of the attribute 0112 * - content-type - a MIME content type and subtype 0113 * - content-language - a RFC 3282 language code 0114 * - vendor.<vendor-token> - a vendor-specific attribute 0115 * 0116 * Attribute names an attribute name prefix followed by ".priv" for 0117 * private attributes or ".shared" for shared attributes. Note that 0118 * the attributes "size.priv" and "size.shared" are read-only 0119 * attributes set by the server, and so cannot be used with 0120 * SetMetaDataJob. 0121 * 0122 * @param name the metadata entry name (Metadata or Annotatemore mode) in ASCII or 0123 * attribute name (Annotatemore mode, if used without /shared or /private prefix) in UTF-8 0124 * @param value the value of the entry or attribute 0125 */ 0126 // KDE5: drop ANNOTATEMORE support 0127 void addMetaData(const QByteArray &name, const QByteArray &value); 0128 0129 /** 0130 * Sets the metadata entry name to operate on (in Annotatemore mode) 0131 * 0132 * In Annotatemore mode, this specifies the metadata entry name to 0133 * operate on. For server metadata, this is one of: 0134 * - /comment 0135 * - /motd 0136 * - /admin 0137 * - /vendor/<vendor-token>/something 0138 * 0139 * For mailbox metadata, this is one of: 0140 * - /comment 0141 * - /sort 0142 * - /thread 0143 * - /check 0144 * - /checkperiod 0145 * - /vendor/<vendor-token>/something 0146 * 0147 * Entry names must be valid UTF-8 strings that do not contain the 0148 * '%' or '*' characters, or NUL. Use of non-visible UTF-8 0149 * characters is strongly discouraged. 0150 * 0151 * In Metadata mode, this has no effect. Metadata entry names 0152 * should instead be specified as the first argument to addMetaData(). 0153 * 0154 * @see setServerCapability() 0155 * 0156 * @param entry the metadata entry name in UTF-8 0157 * 0158 * @deprecated Use a /shared or /private prefix with addMetaData instead. 0159 */ 0160 // KDE5: remove 0161 KIMAP_DEPRECATED void setEntry(const QByteArray &entry); 0162 0163 /** 0164 * Possible error codes that may be returned by the server. 0165 */ 0166 enum MetaDataError { 0167 NoError = 0, /**< Used to indicate that no errors have been received */ 0168 TooMany = 1, /**< Cannot add a new metadata item, because the limit has already been reached */ 0169 TooBig = 2, /**< A metadata value was too big (see maxAcceptedSize()) */ 0170 NoPrivate = 4 /**< The server does not support private metadata entries */ 0171 }; 0172 0173 // Q_DECLARE_WHATEVER_THAT_WAS missing 0174 Q_DECLARE_FLAGS(MetaDataErrors, MetaDataError) 0175 0176 /** 0177 * The metadata errors received from the server. 0178 * 0179 * @return a set of error codes 0180 */ 0181 [[nodiscard]] MetaDataErrors metaDataErrors() const; 0182 /** 0183 * The maximum accepted metadata size. 0184 * 0185 * If the server replied that one of the metadata values was too 0186 * large (see metaDataErrors), this should indicate what the 0187 * maximum size accepted by the server is. 0188 * 0189 * @return the maximum value size in octets, or -1 if the limit is unknown 0190 */ 0191 [[nodiscard]] qint64 maxAcceptedSize(); 0192 0193 protected: 0194 void doStart() override; 0195 void handleResponse(const Response &response) override; 0196 }; 0197 0198 } 0199 0200 Q_DECLARE_OPERATORS_FOR_FLAGS(KIMAP::SetMetaDataJob::MetaDataErrors)