KIMAP::GetMetaDataJob Class

Fetches mailbox metadata. More...

Header: #include <KIMAP/GetMetaDataJob>
CMake: find_package(KPim6IMAP REQUIRED)
target_link_libraries(mytarget PRIVATE KPim6::IMAP)
Inherits: KIMAP::MetaDataJobBase

Public Types

enum Depth { NoDepth, OneLevel, AllLevels }
flags Depths

Public Functions

GetMetaDataJob(KIMAP::Session *session)
void addRequestedEntry(const QByteArray &entry)
QMap<QByteArray, QByteArray> allMetaData() const
QMap<QByteArray, QMap<QByteArray, QByteArray>> allMetaData(const QString &mailBox) const
QMap<QByteArray, QByteArray> allMetaDataForMailbox(const QString &mailbox) const
QHash<QString, QMap<QByteArray, QByteArray>> allMetaDataForMailboxes() const
QByteArray metaData(const QByteArray &entry) const
void setDepth(KIMAP::GetMetaDataJob::Depth depth)
void setMaximumSize(qint64 size)

Detailed Description

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

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

Member Type Documentation

enum GetMetaDataJob::Depth
flags GetMetaDataJob::Depths

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

ConstantValueDescription
KIMAP::GetMetaDataJob::NoDepth0Only the requested entries
KIMAP::GetMetaDataJob::OneLevel1The requested entries and all their direct children
KIMAP::GetMetaDataJob::AllLevels2The requested entries and all their descendants

The Depths type is a typedef for QFlags<Depth>. It stores an OR combination of Depth values.

Member Function Documentation

[explicit] GetMetaDataJob::GetMetaDataJob(KIMAP::Session *session)

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.

entry the metadata entry name

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

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

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" );

mailBox a mailbox name or an empty string for server metadata

Returns a map from metadata entry names to attributes or values

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

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

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

QByteArray GetMetaDataJob::metaData(const QByteArray &entry) 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().

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.

entry the entry to get

Returns the metadata entry value

void GetMetaDataJob::setDepth(KIMAP::GetMetaDataJob::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.

depth the depth of the metadata tree to return

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.

size the entry size limit, in octets, or -1 for no limit