• Skip to content
  • Skip to link menu
KDE 4.6 API Reference
  • KDE API Reference
  • KDE-PIM Libraries
  • KDE Home
  • Contact Us
 

KIMAP Library

  • KIMAP
  • SetMetaDataJob
Public Types | Public Member Functions | Protected Member Functions
KIMAP::SetMetaDataJob Class Reference

Sets mailbox metadata. More...

#include <setmetadatajob.h>

Inheritance diagram for KIMAP::SetMetaDataJob:
Inheritance graph
[legend]

List of all members.

Public Types

enum  MetaDataError { NoError = 0, TooMany = 1, TooBig = 2, NoPrivate = 4 }

Public Member Functions

 SetMetaDataJob (Session *session)
void addMetaData (const QByteArray &name, const QByteArray &value)
qint64 maxAcceptedSize ()
MetaDataErrors metaDataErrors () const
void setEntry (const QByteArray &entry)

Protected Member Functions

virtual void doStart ()
virtual void handleResponse (const Message &response)

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 68 of file setmetadatajob.h.


Member Enumeration Documentation

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

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:
namethe metadata entry name (Metadata mode) in ASCII or attribute name (Annotatemore mode) in UTF-8
valuethe value of the entry or attribute

Definition at line 136 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.

Returns:
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.

Returns:
a set of error codes

Definition at line 148 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:
setServerCapability()
Parameters:
entrythe metadata entry name in UTF-8

Definition at line 142 of file setmetadatajob.cpp.


The documentation for this class was generated from the following files:
  • setmetadatajob.h
  • setmetadatajob.cpp

KIMAP Library

Skip menu "KIMAP Library"
  • Main Page
  • Namespace List
  • Class Hierarchy
  • Alphabetical List
  • Class List
  • File List
  • Namespace Members
  • Class Members
  • Related Pages

KDE-PIM Libraries

Skip menu "KDE-PIM Libraries"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kblog
  • kcal
  • kcalcore
  • kcalutils
  • kholidays
  • kimap
  • kioslave
  •   imap4
  •   mbox
  •   nntp
  • kldap
  • kmbox
  • kmime
  • kontactinterface
  • kpimidentities
  • kpimtextedit
  •   richtextbuilders
  • kpimutils
  • kresources
  • ktnef
  • kxmlrpcclient
  • mailtransport
  • microblog
  • qgpgme
  • syndication
  •   atom
  •   rdf
  •   rss2
Generated for KDE-PIM Libraries by doxygen 1.7.4
This website is maintained by Adriaan de Groot and Allen Winter.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal