#include <setmetadatajob.h>

Inheritance diagram for KIMAP::SetMetaDataJob:

Public Types

enum  MetaDataError { NoError = 0, TooMany = 1, TooBig = 2, NoPrivate = 4 }
typedef QFlags< MetaDataErrorMetaDataErrors
- Public Types inherited from KIMAP::MetaDataJobBase
enum  ServerCapability { Metadata = 0, Annotatemore }

Public Member Functions

 SetMetaDataJob (Session *session)
void addMetaData (const QByteArray &name, const QByteArray &value)
qint64 maxAcceptedSize ()
MetaDataErrors metaDataErrors () const
KIMAP_DEPRECATED void setEntry (const QByteArray &entry)
- Public Member Functions inherited from KIMAP::MetaDataJobBase
 MetaDataJobBase (Session *session)
QString mailBox () const
ServerCapability serverCapability () const
void setMailBox (const QString &mailBox)
void setServerCapability (ServerCapability capability)

Protected Member Functions

void doStart () override
void handleResponse (const Response &response) override
- Protected Member Functions inherited from KIMAP::MetaDataJobBase
 MetaDataJobBase (JobPrivate &dd)

Detailed Description

Sets mailbox metadata.

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

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

Definition at line 56 of file setmetadatajob.h.

Member Enumeration Documentation

Possible error codes that may be returned by the server.


Used to indicate that no errors have been received.


Cannot add a new metadata item, because the limit has already been reached.


A metadata value was too big (see maxAcceptedSize())


The server does not support private metadata entries.

Definition at line 168 of file setmetadatajob.h.

Member Function Documentation

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.

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

Definition at line 149 of file setmetadatajob.cpp.

qint64 KIMAP::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.

the maximum value size in octets, or -1 if the limit is unknown
SetMetaDataJob::MetaDataErrors SetMetaDataJob::metaDataErrors ( ) const

The metadata errors received from the server.

a set of error codes

Definition at line 167 of file setmetadatajob.cpp.

void SetMetaDataJob::setEntry ( const QByteArray entry)

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 also
entrythe metadata entry name in UTF-8
Use a /shared or /private prefix with addMetaData instead.

Definition at line 161 of file setmetadatajob.cpp.

The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Mon Nov 30 2020 23:12:58 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.