KIMAP::GetMetaDataJob

Search for usage in LXR

#include <getmetadatajob.h>

Inheritance diagram for KIMAP::GetMetaDataJob:

Public Types

enum  Depth { NoDepth = 0 , OneLevel , AllLevels }
 
typedef QFlags< DepthDepths
 
- Public Types inherited from KIMAP::MetaDataJobBase
enum  ServerCapability { Metadata = 0 , Annotatemore }
 

Public Member Functions

 GetMetaDataJob (Session *session)
 
KIMAP_DEPRECATED void addEntry (const QByteArray &entry, const QByteArray &attribute=QByteArray())
 
void addRequestedEntry (const QByteArray &entry)
 
QMap< QByteArray, QByteArrayallMetaData () const
 
QMap< QByteArray, QMap< QByteArray, QByteArray > > allMetaData (const QString &mailBox) const
 
QMap< QByteArray, QByteArrayallMetaDataForMailbox (const QString &mailbox) const
 
QHash< QString, QMap< QByteArray, QByteArray > > allMetaDataForMailboxes () const
 
QByteArray metaData (const QByteArray &entry) const
 
KIMAP_DEPRECATED QByteArray metaData (const QString &mailBox, const QByteArray &entry, const QByteArray &attribute=QByteArray()) const
 
void setDepth (Depth depth)
 
void setMaximumSize (qint64 size)
 
- 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

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

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

Member Typedef Documentation

◆ Depths

Member Enumeration Documentation

◆ Depth

Used to specify the depth of the metadata hierarchy 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 61 of file getmetadatajob.h.

Constructor & Destructor Documentation

◆ GetMetaDataJob()

GetMetaDataJob::GetMetaDataJob ( Session * session)
explicit

Definition at line 42 of file getmetadatajob.cpp.

◆ ~GetMetaDataJob()

GetMetaDataJob::~GetMetaDataJob ( )
override

Definition at line 47 of file getmetadatajob.cpp.

Member Function Documentation

◆ addEntry()

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
Deprecated
use addRequestedEntry(QByteArray) instead

Definition at line 166 of file getmetadatajob.cpp.

◆ addRequestedEntry()

void GetMetaDataJob::addRequestedEntry ( const QByteArray & entry)

Add an entry to the query list.

See SetMetaDataJob for a description of metadata entry names.

Note that this expects METADATA style entries (with a /shared or /private prefix typically). In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute.

Parameters
entrythe metadata entry name

Definition at line 176 of file getmetadatajob.cpp.

◆ allMetaData() [1/2]

QMap< QByteArray, QByteArray > GetMetaDataJob::allMetaData ( ) const
nodiscard

Get all the metadata for the mailbox set with setMailBox().

Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically), also in ANNOTATEMORE mode.

Returns
a map from metadata entry names to values

Definition at line 236 of file getmetadatajob.cpp.

◆ allMetaData() [2/2]

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

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 230 of file getmetadatajob.cpp.

◆ allMetaDataForMailbox()

QMap< QByteArray, QByteArray > GetMetaDataJob::allMetaDataForMailbox ( const QString & mailbox) const

Get all the metadata for the mailbox.

Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically), also in ANNOTATEMORE mode.

Returns
a map from metadata entry names to values

Definition at line 242 of file getmetadatajob.cpp.

◆ allMetaDataForMailboxes()

QHash< QString, QMap< QByteArray, QByteArray > > GetMetaDataJob::allMetaDataForMailboxes ( ) const
nodiscard

Get all the metadata for for all mailboxes.

Note that the returned map uses METADATA style entries (with a /shared or /private prefix typically), also in ANNOTATEMORE mode.

Returns
a map in the form (mailbox, (entry, value))

Definition at line 258 of file getmetadatajob.cpp.

◆ doStart()

void GetMetaDataJob::doStart ( )
overrideprotected

Definition at line 58 of file getmetadatajob.cpp.

◆ handleResponse()

void GetMetaDataJob::handleResponse ( const Response & response)
overrideprotected

Definition at line 125 of file getmetadatajob.cpp.

◆ metaData() [1/2]

QByteArray GetMetaDataJob::metaData ( const QByteArray & entry) const
nodiscard

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

Note that this expects METADATA style entries (with a /shared or /private prefix typically). In ANNOTATEMORE mode, this prefix is automatically replaced with an appropriate attribute.

Parameters
entrythe entry to get
Returns
the metadata entry value

Definition at line 223 of file getmetadatajob.cpp.

◆ metaData() [2/2]

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
Deprecated
use metaData(QByteArray entry) instead

Definition at line 205 of file getmetadatajob.cpp.

◆ setDepth()

void GetMetaDataJob::setDepth ( Depth depth)

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

Metadata entry names are hierarchical, 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 189 of file getmetadatajob.cpp.

◆ setMaximumSize()

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 183 of file getmetadatajob.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sat Dec 21 2024 17:01:17 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.