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
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.
| Constant | Value | Description |
|---|---|---|
KIMAP::GetMetaDataJob::NoDepth | 0 | Only the requested entries |
KIMAP::GetMetaDataJob::OneLevel | 1 | The requested entries and all their direct children |
KIMAP::GetMetaDataJob::AllLevels | 2 | The 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