|  | Home |

# QMailFolderKey Class Reference

The QMailFolderKey class defines the parameters used for querying a subset of all available folders from the mail store. More...

        #include <QMailFolderKey>

This class is under development and is subject to change.

- List of all members, including inherited members

## Public Types

typedef | ArgumentType
enum | Property { Id, Path, ParentFolderId, ParentAccountId, ..., Custom }

## Public Functions

| QMailFolderKey ()
| QMailFolderKey ( const QMailFolderKey & other )
virtual | ~QMailFolderKey ()
const QList<ArgumentType> & | arguments () const
QMailKey::Combiner | combiner () const
void | deserialize ( Stream & stream )
bool | isEmpty () const
bool | isNegated () const
bool | isNonMatching () const
void | serialize ( Stream & stream ) const
const QList<QMailFolderKey> & | subKeys () const
| operator QVariant () const
bool | operator!= ( const QMailFolderKey & other ) const
QMailFolderKey | operator& ( const QMailFolderKey & other ) const
const QMailFolderKey & | operator&= ( const QMailFolderKey & other )
const QMailFolderKey & | operator= ( const QMailFolderKey & other )
bool | operator== ( const QMailFolderKey & other ) const
QMailFolderKey | operator| ( const QMailFolderKey & other ) const
const QMailFolderKey & | operator|= ( const QMailFolderKey & other )
QMailFolderKey | operator~ () const

## Static Public Members

QMailFolderKey | ancestorFolderIds ( const QMailFolderId & id, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | ancestorFolderIds ( const QMailFolderIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | ancestorFolderIds ( const QMailFolderKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | customField ( const QString & name, QMailDataComparator::PresenceComparator cmp = QMailDataComparator::Present )
QMailFolderKey | customField ( const QString & name, const QString & value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | customField ( const QString & name, const QString & value, QMailDataComparator::InclusionComparator cmp )
QMailFolderKey | displayName ( const QString & value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | displayName ( const QString & value, QMailDataComparator::InclusionComparator cmp )
QMailFolderKey | displayName ( const QStringList & values, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | id ( const QMailFolderId & id, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | id ( const QMailFolderIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | id ( const QMailFolderKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | nonMatchingKey ()
QMailFolderKey | parentAccountId ( const QMailAccountId & id, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | parentAccountId ( const QMailAccountIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | parentAccountId ( const QMailAccountKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | parentFolderId ( const QMailFolderId & id, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | parentFolderId ( const QMailFolderIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | parentFolderId ( const QMailFolderKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | path ( const QString & value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | path ( const QString & value, QMailDataComparator::InclusionComparator cmp )
QMailFolderKey | path ( const QStringList & values, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | serverCount ( int value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | serverCount ( int value, QMailDataComparator::RelationComparator cmp )
QMailFolderKey | serverUndiscoveredCount ( int value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | serverUndiscoveredCount ( int value, QMailDataComparator::RelationComparator cmp )
QMailFolderKey | serverUnreadCount ( int value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal )
QMailFolderKey | serverUnreadCount ( int value, QMailDataComparator::RelationComparator cmp )
QMailFolderKey | status ( quint64 mask, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes )
QMailFolderKey | status ( quint64 value, QMailDataComparator::EqualityComparator cmp )

## Detailed Description

The QMailFolderKey class defines the parameters used for querying a subset of all available folders from the mail store.

A QMailFolderKey is composed of a folder property, an optional comparison operator and a comparison value. The QMailFolderKey class is used in conjunction with the QMailStore::queryFolders() and QMailStore::countFolders() functions to filter results which meet the criteria defined by the key.

QMailFolderKey's can be combined using the logical operators (&), (|) and (~) to build more sophisticated queries.

For example:

To create a query for folders with paths containing "inbox" or "sms":

        QMailFolderKey inboxKey(QMailFolderKey::path("inbox", QMailDataComparator::Includes));
        QMailFolderKey smsKey(QMailFolderKey::path("sms", QMailDataComparator::Includes));
        QMailFolderIdList results = QMailStore::instance()->queryFolders(inboxKey | smsKey);

To query all folders with name containing "foo" for a specified account:

        QMailFolderIdList fooFolders(const QMailAccountId& accountId)
        {
            QMailFolderKey nameKey(QMailFolderKey::displayName("foo", QMailDataComparator::Includes);
            QMailFolderKey accountKey(QMailFolderKey::parentAccountId(accountId));

            return QMailStore::instance()->queryFolders(nameKey & accountKey);
        }

See also QMailStore and QMailFolder.

## Member Type Documentation

### typedef QMailFolderKey::ArgumentType

Defines the type used to represent a single criterion of a folder filter.

Synonym for QMailKeyArgument<QMailFolderKey::Property>.

### enum QMailFolderKey::Property

This enum type describes the queryable data properties of a QMailFolder.

Constant | Value | Description
--- | --- | ---
`QMailFolderKey::Id` | `( 1<<0 )` | The ID of the folder.
`QMailFolderKey::Path` | `( 1<<1 )` | The path of the folder in native form.
`QMailFolderKey::ParentFolderId` | `( 1<<2 )` | The ID of the parent folder for a given folder.
`QMailFolderKey::ParentAccountId` | `( 1<<3 )` | The ID of the parent account for this folder.
`QMailFolderKey::DisplayName` | `( 1<<4 )` | The name of the folder, designed for display to users.
`QMailFolderKey::Status` | `( 1<<5 )` | The status value of the folder.
`QMailFolderKey::AncestorFolderIds` | `( 1<<6 )` | The set of IDs of folders which are direct or indirect parents of this folder.
`QMailFolderKey::ServerCount` | `( 1<<7 )` | The number of messages reported to be on the server for the folder.
`QMailFolderKey::ServerUnreadCount` | `( 1<<8 )` | The number of unread messages reported to be on the server for the folder.
`QMailFolderKey::ServerUndiscoveredCount` | `( 1<<9 )` | The number of undiscovered messages reported to be on the server for the folder.
`QMailFolderKey::Custom` | `( 1<<10 )` | The custom fields of the folder.

## Member Function Documentation

### QMailFolderKey::QMailFolderKey ()

Creates a QMailFolderKey without specifying matching parameters.

A default-constructed key (one for which isEmpty() returns true) matches all folders.

See also isEmpty().

### QMailFolderKey::QMailFolderKey ( const QMailFolderKey & other )

Creates a copy of the QMailFolderKey other.

### QMailFolderKey::~QMailFolderKey () `[virtual]`

Destroys this QMailFolderKey.

### QMailFolderKey QMailFolderKey::ancestorFolderIds ( const QMailFolderId & id, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose ancestor folders' identifiers contain id, according to cmp.

See also QMailFolder::parentFolderId().

### QMailFolderKey QMailFolderKey::ancestorFolderIds ( const QMailFolderIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose ancestor folders' identifiers contain a member of ids, according to cmp.

See also QMailFolder::parentFolderId().

### QMailFolderKey QMailFolderKey::ancestorFolderIds ( const QMailFolderKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose ancestor folders' identifiers contain a member of the set yielded by key, according to cmp.

See also QMailFolder::parentFolderId().

### const QList<ArgumentType> & QMailFolderKey::arguments () const

Returns the list of arguments to this QMailFolderKey.

### QMailKey::Combiner QMailFolderKey::combiner () const

Returns the combiner used to combine arguments or sub keys of this QMailFolderKey.

### QMailFolderKey QMailFolderKey::customField ( const QString & name, QMailDataComparator::PresenceComparator cmp = QMailDataComparator::Present ) `[static]`

Returns a key matching folders that possess a custom field with the name name, according to cmp.

See also QMailFolder::customField().

### QMailFolderKey QMailFolderKey::customField ( const QString & name, const QString & value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders that possess a custom field with the name name, whose value matches value, according to cmp.

See also QMailFolder::customField().

### QMailFolderKey QMailFolderKey::customField ( const QString & name, const QString & value, QMailDataComparator::InclusionComparator cmp ) `[static]`

Returns a key matching folders that possess a custom field with the name name, whose value matches the substring value, according to cmp.

See also QMailFolder::customField().

### void QMailFolderKey::deserialize ( Stream & stream )

Reads the contents of a QMailFolderKey from stream.

### QMailFolderKey QMailFolderKey::displayName ( const QString & value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose display name matches value, according to cmp.

See also QMailFolder::displayName().

### QMailFolderKey QMailFolderKey::displayName ( const QString & value, QMailDataComparator::InclusionComparator cmp ) `[static]`

Returns a key matching folders whose display name matches the substring value, according to cmp.

See also QMailFolder::displayName().

### QMailFolderKey QMailFolderKey::displayName ( const QStringList & values, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose display name is a member of values, according to cmp.

See also QMailFolder::displayName().

### QMailFolderKey QMailFolderKey::id ( const QMailFolderId & id, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose identifier matches id, according to cmp.

See also QMailFolder::id().

### QMailFolderKey QMailFolderKey::id ( const QMailFolderIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose identifier is a member of ids, according to cmp.

See also QMailFolder::id().

### QMailFolderKey QMailFolderKey::id ( const QMailFolderKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose identifier is a member of the set yielded by key, according to cmp.

See also QMailFolder::id().

### bool QMailFolderKey::isEmpty () const

Returns true if the key remains empty after default construction; otherwise returns false.

An empty key matches all folders.

The result of combining an empty key with a non-empty key is the original non-empty key. This is true regardless of whether the combination is formed by an AND or an OR operation.

The result of combining two empty keys is an empty key.

See also isNonMatching().

### bool QMailFolderKey::isNegated () const

Returns true if the key's criteria should be negated in application.

### bool QMailFolderKey::isNonMatching () const

Returns true if the key is a non-matching key; otherwise returns false.

A non-matching key does not match any folders.

The result of ANDing a non-matching key with a matching key is a non-matching key. The result of ORing a non-matching key with a matching key is the original matching key.

The result of combining two non-matching keys is a non-matching key.

See also nonMatchingKey() and isEmpty().

### QMailFolderKey QMailFolderKey::nonMatchingKey () `[static]`

Returns a key that does not match any folders (unlike an empty key).

See also isNonMatching() and isEmpty().

### QMailFolderKey QMailFolderKey::parentAccountId ( const QMailAccountId & id, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose parent account's identifier matches id, according to cmp.

See also QMailFolder::parentAccountId().

### QMailFolderKey QMailFolderKey::parentAccountId ( const QMailAccountIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose parent account's identifier is a member of ids, according to cmp.

See also QMailFolder::parentAccountId().

### QMailFolderKey QMailFolderKey::parentAccountId ( const QMailAccountKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose parent account's identifier is a member of the set yielded by key, according to cmp.

See also QMailFolder::parentAccountId().

### QMailFolderKey QMailFolderKey::parentFolderId ( const QMailFolderId & id, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose parent folder's identifier matches id, according to cmp.

See also QMailFolder::parentFolderId().

### QMailFolderKey QMailFolderKey::parentFolderId ( const QMailFolderIdList & ids, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose parent folder's identifier is a member of ids, according to cmp.

See also QMailFolder::parentFolderId().

### QMailFolderKey QMailFolderKey::parentFolderId ( const QMailFolderKey & key, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose parent folder's identifier is a member of the set yielded by key, according to cmp.

See also QMailFolder::parentFolderId().

### QMailFolderKey QMailFolderKey::path ( const QString & value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose path matches value, according to cmp.

See also QMailFolder::path().

### QMailFolderKey QMailFolderKey::path ( const QString & value, QMailDataComparator::InclusionComparator cmp ) `[static]`

Returns a key matching folders whose path matches the substring value, according to cmp.

See also QMailFolder::path().

### QMailFolderKey QMailFolderKey::path ( const QStringList & values, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose path is a member of values, according to cmp.

See also QMailFolder::path().

### void QMailFolderKey::serialize ( Stream & stream ) const

Writes the contents of a QMailFolderKey to a stream.

### QMailFolderKey QMailFolderKey::serverCount ( int value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose serverCount matches value, according to cmp.

See also QMailFolder::serverCount().

### QMailFolderKey QMailFolderKey::serverCount ( int value, QMailDataComparator::RelationComparator cmp ) `[static]`

Returns a key matching folders whose serverCount has the relation to value that is specified by cmp.

See also QMailFolder::serverCount().

### QMailFolderKey QMailFolderKey::serverUndiscoveredCount ( int value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose serverUndiscoveredCount matches value, according to cmp.

See also QMailFolder::serverUndiscoveredCount().

### QMailFolderKey QMailFolderKey::serverUndiscoveredCount ( int value, QMailDataComparator::RelationComparator cmp ) `[static]`

Returns a key matching folders whose serverUndiscoveredCount has the relation to value that is specified by cmp.

See also QMailFolder::serverUndiscoveredCount().

### QMailFolderKey QMailFolderKey::serverUnreadCount ( int value, QMailDataComparator::EqualityComparator cmp = QMailDataComparator::Equal ) `[static]`

Returns a key matching folders whose serverUnreadCount matches value, according to cmp.

See also QMailFolder::serverUnreadCount().

### QMailFolderKey QMailFolderKey::serverUnreadCount ( int value, QMailDataComparator::RelationComparator cmp ) `[static]`

Returns a key matching folders whose serverUnreadCount has the relation to value that is specified by cmp.

See also QMailFolder::serverUnreadCount().

### QMailFolderKey QMailFolderKey::status ( quint64 mask, QMailDataComparator::InclusionComparator cmp = QMailDataComparator::Includes ) `[static]`

Returns a key matching folders whose status is a bitwise match to mask, according to cmp.

See also QMailFolder::status().

### QMailFolderKey QMailFolderKey::status ( quint64 value, QMailDataComparator::EqualityComparator cmp ) `[static]`

Returns a key matching folders whose status matches value, according to cmp.

See also QMailFolder::status().

### const QList<QMailFolderKey> & QMailFolderKey::subKeys () const

Returns the list of sub keys held by this QMailFolderKey.

### QMailFolderKey::operator QVariant () const

Returns the QVariant representation of this QMailFolderKey.

### bool QMailFolderKey::operator!= ( const QMailFolderKey & other ) const

Returns `true` if the value of this key is not the same as the key other. Returns `false` otherwise.

### QMailFolderKey QMailFolderKey::operator& ( const QMailFolderKey & other ) const

Returns a key that is the logical AND of this key and the value of key other.

### const QMailFolderKey & QMailFolderKey::operator&= ( const QMailFolderKey & other )

Performs a logical AND with this key and the key other and assigns the result to this key.

### const QMailFolderKey & QMailFolderKey::operator= ( const QMailFolderKey & other )

Assign the value of the QMailFolderKey other to this.

### bool QMailFolderKey::operator== ( const QMailFolderKey & other ) const

Returns `true` if the value of this key is the same as the key other. Returns `false` otherwise.

### QMailFolderKey QMailFolderKey::operator| ( const QMailFolderKey & other ) const

Returns a key that is the logical OR of this key and the value of key other.

### const QMailFolderKey & QMailFolderKey::operator|= ( const QMailFolderKey & other )

Performs a logical OR with this key and the key other and assigns the result to this key.

### QMailFolderKey QMailFolderKey::operator~ () const

Returns a key that is the logical NOT of the value of this key.

If this key is empty, the result will be a non-matching key; if this key is non-matching, the result will be an empty key.

See also isEmpty() and isNonMatching().