• Skip to content
  • Skip to link menu
  • KDE API Reference
  • kdepimlibs-4.8.3 API Reference
  • KDE Home
  • Contact Us
 

KIMAP Library

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

#include <getmetadatajob.h>

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

List of all members.

Public Types

enum  Depth { NoDepth = 0, OneLevel, AllLevels }

Public Member Functions

 GetMetaDataJob (Session *session)
void addEntry (const QByteArray &entry, const QByteArray &attribute=QByteArray())
QMap< QByteArray, QMap
< QByteArray, QByteArray > > 
allMetaData (const QString &mailBox) const
QByteArray metaData (const QString &mailBox, const QByteArray &entry, const QByteArray &attribute=QByteArray()) const
void setDepth (Depth depth)
void setMaximumSize (qint64 size)

Protected Member Functions

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

Detailed Description

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

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 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 61 of file getmetadatajob.h.


Member Enumeration Documentation

enum KIMAP::GetMetaDataJob::Depth

Used to specify the depth of the metadata heirachy to walk.

Enumerator:
NoDepth 

Only the requested entries.

OneLevel 

The requested entries and all their direct children.

AllLevels 

The requested entries and all their descendants.

Definition at line 75 of file getmetadatajob.h.


Member Function Documentation

void GetMetaDataJob::addEntry ( const QByteArray &  entry,
const QByteArray &  attribute = QByteArray() 
)

Add an entry to the query list.

See SetMetaDataJob for a description of metadata entry names.

When operating in Annotatemore mode, you should provide an attribute name. Typically this will be "value", "value.priv" or "value.shared", although you might want to fetch the "content-type" or "content-language" attributes as well.

Parameters:
entrythe metadata entry name
attributethe attribute name, in Annotatemore mode

Definition at line 156 of file getmetadatajob.cpp.

QMap< QByteArray, QMap< QByteArray, QByteArray > > GetMetaDataJob::allMetaData ( const QString &  mailBox) const

Get all the metadata for a given mailbox.

The returned map is from metadata entry names to attributes or values.

If operating in Metadata mode, the metadata value is stored against the empty QByteArray:

 map = job.allMetaData( "INBOX" );
 QByteArray value = map[ "/shared/comment" ].value( QByteArray() );

The equivalent in Annotatemore mode would be:

 map = job.allMetaData( "INBOX" );
 QByteArray value = map[ "/comment" ].value( "value.shared" );
Parameters:
mailBoxa mailbox name or an empty string for server metadata
Returns:
a map from metadata entry names to attributes or values

Definition at line 206 of file getmetadatajob.cpp.

QByteArray GetMetaDataJob::metaData ( const QString &  mailBox,
const QByteArray &  entry,
const QByteArray &  attribute = QByteArray() 
) const

Get a single metadata entry.

The metadata must have been requested using addEntry(), and the job must have completed successfully, or this method will not return anything.

Note that if setMaximumSize() was used to limit the size of returned metadata, this method may return an empty QByteArray even if the metadata entry was requested and exists on the server. This will happen when the metadata entry is larger than the size limit given to setMaximumSize().

Parameters:
mailBoxthe mailbox the metadata is attached to, or an empty string for server metadata
entrythe entry to get
attribute(only in Annotatemore mode) the attribute to get
Returns:
the metadata entry value

Definition at line 188 of file getmetadatajob.cpp.

void GetMetaDataJob::setDepth ( Depth  depth)

Sets whether to retrieve children or descendants of the requested entries.

Metadata entry names are heirachical, much like UNIX path names. It therefore makes sense to ask for an entry and all its children (OneLevel) or an entry and all its descendants (AllLevels).

For example, /shared/foo/bar/baz is a child of /shared/foo/bar and a descendent of /shared/foo. So if you request the entry "/shared/foo" with depth NoDepth, you will only get the "/shared/foo" entry. If you set the depth to OneLevel, you will also get "/shared/foo/bar". If you set the depth to AllLevels, you will also get "/shared/foo/bar/baz", and every other metadata entry that starts with "/shared/foo/".

Note that this is only used when the server capability mode is Metadata.

Parameters:
depththe depth of the metadata tree to return

Definition at line 171 of file getmetadatajob.cpp.

void GetMetaDataJob::setMaximumSize ( qint64  size)

Limits the size of returned metadata entries.

In order to save time or bandwidth, it is possible to prevent the server from returning metadata entries that are larger than a certain size. These entries will simply not appear in the list returned by allMetaData(), and will not be accessible using metaData().

Note that this is only used when the server capability mode is Metadata.

The default is no limit (-1). A value of less than -1 will cause the job to fail.

Parameters:
sizethe entry size limit, in octets, or -1 for no limit

Definition at line 165 of file getmetadatajob.cpp.


The documentation for this class was generated from the following files:
  • getmetadatajob.h
  • getmetadatajob.cpp
This file is part of the KDE documentation.
Documentation copyright © 1996-2012 The KDE developers.
Generated on Mon May 7 2012 23:55:09 by doxygen 1.8.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.

KIMAP Library

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

kdepimlibs-4.8.3 API Reference

Skip menu "kdepimlibs-4.8.3 API Reference"
  • akonadi
  •   contact
  •   kmime
  • kabc
  • kalarmcal
  • 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
Report problems with this website to our bug tracking system.
Contact the specific authors with questions and comments about the page contents.

KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V. | Legal