KIMAP::SetMetaDataJob Class

Sets mailbox metadata. More...

Header: #include <KIMAP/SetMetaDataJob>
CMake: find_package(KPim6IMAP REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::IMAP)
Inherits: KIMAP::MetaDataJobBase

Public Types

enum MetaDataError { NoError, TooMany, TooBig, NoPrivate }
flags MetaDataErrors

Public Functions

SetMetaDataJob(KIMAP::Session *session)
virtual ~SetMetaDataJob() override
void addMetaData(const QByteArray &name, const QByteArray &value)
qint64 maxAcceptedSize()
KIMAP::SetMetaDataJob::MetaDataErrors metaDataErrors() const

Detailed Description

Provides support for the IMAP METADATA extension; both the final RFC version (RFC 5464) and the older, incompatible draft version (known as ANNOTATEMORE) (draft-daboo-imap-annotatemore-07). 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

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).

Member Type Documentation

enum SetMetaDataJob::MetaDataError
flags SetMetaDataJob::MetaDataErrors

Possible error codes that may be returned by the server.

ConstantValueDescription
KIMAP::SetMetaDataJob::NoError0Used to indicate that no errors have been received
KIMAP::SetMetaDataJob::TooMany1Cannot add a new metadata item, because the limit has already been reached
KIMAP::SetMetaDataJob::TooBig2A metadata value was too big (see maxAcceptedSize())
KIMAP::SetMetaDataJob::NoPrivate4The server does not support private metadata entries

The MetaDataErrors type is a typedef for QFlags<MetaDataError>. It stores an OR combination of MetaDataError values.

Member Function Documentation

[explicit] SetMetaDataJob::SetMetaDataJob(KIMAP::Session *session)

[override virtual noexcept] SetMetaDataJob::~SetMetaDataJob()

void SetMetaDataJob::addMetaData(const QByteArray &name, const QByteArray &value)

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.

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

value can be any data, although if it is a multi-line string value, CRLF line-endings must be used.

In Annotatemore mode it is possible to prefix the entry name with a /shared or /private prefix, that is automatically translated to an appropriate value.shared|priv attribute.

Annotatemore legacy mode: 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.

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.

name the metadata entry name (Metadata or Annotatemore mode) in ASCII or attribute name (Annotatemore mode, if used without /shared or /private prefix) in UTF-8 value the value of the entry or attribute

qint64 SetMetaDataJob::maxAcceptedSize()

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.

Returns the maximum value size in octets, or -1 if the limit is unknown

KIMAP::SetMetaDataJob::MetaDataErrors SetMetaDataJob::metaDataErrors() const

The metadata errors received from the server.

Returns a set of error codes