KIMAP::SetMetaDataJob Class Reference

#include <setmetadatajob.h>

Inheritance diagram for KIMAP::SetMetaDataJob:

Public Types
enum	MetaDataError { NoError = 0 , TooMany = 1 , TooBig = 2 , NoPrivate = 4 }
typedef QFlags< MetaDataError >	MetaDataErrors
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

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

Definition at line 54 of file setmetadatajob.h.

Member Typedef Documentation

MetaDataErrors

QFlags< MetaDataError > KIMAP::SetMetaDataJob::MetaDataErrors

Definition at line 174 of file setmetadatajob.h.

Member Enumeration Documentation

MetaDataError

enum KIMAP::SetMetaDataJob::MetaDataError

Possible error codes that may be returned by the server.

Enumerator
NoError	Used to indicate that no errors have been received.
TooMany	Cannot add a new metadata item, because the limit has already been reached.
TooBig	A metadata value was too big (see maxAcceptedSize())
NoPrivate	The server does not support private metadata entries.

Definition at line 166 of file setmetadatajob.h.

Constructor & Destructor Documentation

SetMetaDataJob()

SetMetaDataJob::SetMetaDataJob ( Session * session )

explicit

Definition at line 42 of file setmetadatajob.cpp.

~SetMetaDataJob()

SetMetaDataJob::~SetMetaDataJob ( )

override

Definition at line 47 of file setmetadatajob.cpp.

Member Function Documentation

addMetaData()

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.

Parameters

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

Definition at line 152 of file setmetadatajob.cpp.

doStart()

void SetMetaDataJob::doStart ( )

overrideprotected

Definition at line 51 of file setmetadatajob.cpp.

handleResponse()

void SetMetaDataJob::handleResponse ( const Response & response )

overrideprotected

Definition at line 101 of file setmetadatajob.cpp.

maxAcceptedSize()

qint64 KIMAP::SetMetaDataJob::maxAcceptedSize ( )

nodiscard

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

metaDataErrors()

SetMetaDataJob::MetaDataErrors SetMetaDataJob::metaDataErrors ( ) const

nodiscard

The metadata errors received from the server.

Returns

a set of error codes

Definition at line 170 of file setmetadatajob.cpp.

setEntry()

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

setServerCapability()

Parameters

entry

the metadata entry name in UTF-8

Deprecated

Use a /shared or /private prefix with addMetaData instead.

Definition at line 164 of file setmetadatajob.cpp.

---

The documentation for this class was generated from the following files:

• setmetadatajob.h
• setmetadatajob.cpp