Logo Search packages:      
Sourcecode: qmf version File versions  Download package

qmailfolderkey.cpp

/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt Messaging Framework.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain additional
** rights.  These rights are described in the Nokia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qmailfolderkey.h"
#include "qmailfolderkey_p.h"

#include "qmailaccountkey.h"
#include <QStringList>

using namespace QMailKey;

/*!
    \class QMailFolderKey

    \preliminary
    \brief The QMailFolderKey class defines the parameters used for querying a subset of
    all available folders from the mail store.
    \ingroup messaginglibrary

    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":
    \code
    QMailFolderKey inboxKey(QMailFolderKey::path("inbox", QMailDataComparator::Includes));
    QMailFolderKey smsKey(QMailFolderKey::path("sms", QMailDataComparator::Includes));
    QMailFolderIdList results = QMailStore::instance()->queryFolders(inboxKey | smsKey);
    \endcode

    To query all folders with name containing "foo" for a specified account:
    \code
    QMailFolderIdList fooFolders(const QMailAccountId& accountId)
    {
        QMailFolderKey nameKey(QMailFolderKey::displayName("foo", QMailDataComparator::Includes);
        QMailFolderKey accountKey(QMailFolderKey::parentAccountId(accountId));

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

    \sa QMailStore, QMailFolder
*/

/*!
    \enum QMailFolderKey::Property

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

    \value Id The ID of the folder.
    \value Path The path of the folder in native form.
    \value ParentFolderId The ID of the parent folder for a given folder.
    \value ParentAccountId The ID of the parent account for this folder.
    \value DisplayName The name of the folder, designed for display to users.
    \value Status The status value of the folder.
    \value AncestorFolderIds The set of IDs of folders which are direct or indirect parents of this folder.
    \value ServerCount The number of messages reported to be on the server for the folder.
    \value ServerUnreadCount The number of unread messages reported to be on the server for the folder.
    \value ServerUndiscoveredCount The number of undiscovered messages reported to be on the server for the folder.
    \value Custom The custom fields of the folder.
*/

/*!
    \typedef QMailFolderKey::IdType
    \internal
*/

/*!
    \typedef QMailFolderKey::ArgumentType
    
    Defines the type used to represent a single criterion of a folder filter.

    Synonym for QMailKeyArgument<QMailFolderKey::Property>.
*/

Q_IMPLEMENT_USER_METATYPE(QMailFolderKey);

/*!
    Creates a QMailFolderKey without specifying matching parameters.

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

    \sa isEmpty()
*/
00129 QMailFolderKey::QMailFolderKey()
    : d(new QMailFolderKeyPrivate)
{
}

/*!
    Constructs a QMailFolderKey which defines a query parameter where
    QMailFolder::Property \a p is compared using comparison operator
    \a c with a value \a value.
*/
00139 QMailFolderKey::QMailFolderKey(Property p, const QVariant& value, QMailKey::Comparator c)
    : d(new QMailFolderKeyPrivate(p, value, c))
{
}

/*! 
    \fn QMailFolderKey:: QMailFolderKey(const ListType &, Property, QMailKey::Comparator)
    \internal 
*/
template <typename ListType>
QMailFolderKey::QMailFolderKey(const ListType &valueList, QMailFolderKey::Property p, QMailKey::Comparator c)
    : d(new QMailFolderKeyPrivate(valueList, p, c))
{
}

/*!
    Creates a copy of the QMailFolderKey \a other.
*/
00157 QMailFolderKey::QMailFolderKey(const QMailFolderKey& other)
{
    d = other.d;
}

/*!
    Destroys this QMailFolderKey.
*/
00165 QMailFolderKey::~QMailFolderKey()
{
}

/*!
    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.

    \sa isEmpty(), isNonMatching()
*/
00177 QMailFolderKey QMailFolderKey::operator~() const
{
    return QMailFolderKeyPrivate::negate(*this);
}

/*!
    Returns a key that is the logical AND of this key and the value of key \a other.
*/
00185 QMailFolderKey QMailFolderKey::operator&(const QMailFolderKey& other) const
{
    return QMailFolderKeyPrivate::andCombine(*this, other);
}

/*!
    Returns a key that is the logical OR of this key and the value of key \a other.
*/
00193 QMailFolderKey QMailFolderKey::operator|(const QMailFolderKey& other) const
{
    return QMailFolderKeyPrivate::orCombine(*this, other);
}

/*!
    Performs a logical AND with this key and the key \a other and assigns the result
    to this key.
*/
00202 const QMailFolderKey& QMailFolderKey::operator&=(const QMailFolderKey& other)
{
    return QMailFolderKeyPrivate::andAssign(*this, other);
}

/*!
    Performs a logical OR with this key and the key \a other and assigns the result
    to this key.
*/
00211 const QMailFolderKey& QMailFolderKey::operator|=(const QMailFolderKey& other) 
{
    return QMailFolderKeyPrivate::orAssign(*this, other);
}

/*!
    Returns \c true if the value of this key is the same as the key \a other. Returns 
    \c false otherwise.
*/
00220 bool QMailFolderKey::operator==(const QMailFolderKey& other) const
{
    return d->operator==(*other.d);
}

/*!
    Returns \c true if the value of this key is not the same as the key \a other. Returns
    \c false otherwise.
*/
00229 bool QMailFolderKey::operator!=(const QMailFolderKey& other) const
{
    return !d->operator==(*other.d);
}

/*!
    Assign the value of the QMailFolderKey \a other to this.
*/
00237 const QMailFolderKey& QMailFolderKey::operator=(const QMailFolderKey& other)
{
    d = other.d;
    return *this;
}

/*!
    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.

    \sa isNonMatching()
*/
00255 bool QMailFolderKey::isEmpty() const
{
    return d->isEmpty();
}

/*!
    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.

    \sa nonMatchingKey(), isEmpty()
*/
00272 bool QMailFolderKey::isNonMatching() const
{
    return d->isNonMatching();
}

/*! 
    Returns true if the key's criteria should be negated in application.
*/
00280 bool QMailFolderKey::isNegated() const
{
    return d->negated;
}

/*!
    Returns the QVariant representation of this QMailFolderKey. 
*/
00288 QMailFolderKey::operator QVariant() const
{
    return QVariant::fromValue(*this);
}

/*!
    Returns the list of arguments to this QMailFolderKey.
*/
00296 const QList<QMailFolderKey::ArgumentType> &QMailFolderKey::arguments() const
{
    return d->arguments;
}

/*!
    Returns the list of sub keys held by this QMailFolderKey.
*/
00304 const QList<QMailFolderKey> &QMailFolderKey::subKeys() const
{
    return d->subKeys;
}

/*! 
    Returns the combiner used to combine arguments or sub keys of this QMailFolderKey.
*/
00312 QMailKey::Combiner QMailFolderKey::combiner() const
{
    return d->combiner;
}

/*!
    \fn QMailFolderKey::serialize(Stream &stream) const

    Writes the contents of a QMailFolderKey to a \a stream.
*/
00322 template <typename Stream> void QMailFolderKey::serialize(Stream &stream) const
{
    d->serialize(stream);
}

/*!
    \fn QMailFolderKey::deserialize(Stream &stream)

    Reads the contents of a QMailFolderKey from \a stream.
*/
00332 template <typename Stream> void QMailFolderKey::deserialize(Stream &stream)
{
    d->deserialize(stream);
}

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

    \sa isNonMatching(), isEmpty()
*/
00342 QMailFolderKey QMailFolderKey::nonMatchingKey()
{
    return QMailFolderKeyPrivate::nonMatchingKey();
}

/*!
    Returns a key matching folders whose identifier matches \a id, according to \a cmp.

    \sa QMailFolder::id()
*/
00352 QMailFolderKey QMailFolderKey::id(const QMailFolderId &id, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(Id, id, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::id()
*/
00362 QMailFolderKey QMailFolderKey::id(const QMailFolderIdList &ids, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(ids, Id, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::id()
*/
00372 QMailFolderKey QMailFolderKey::id(const QMailFolderKey &key, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(Id, key, QMailKey::comparator(cmp));
}

/*!
    Returns a key matching folders whose path matches \a value, according to \a cmp.

    \sa QMailFolder::path()
*/
00382 QMailFolderKey QMailFolderKey::path(const QString &value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(Path, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::path()
*/
00392 QMailFolderKey QMailFolderKey::path(const QString &value, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(Path, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::path()
*/
00402 QMailFolderKey QMailFolderKey::path(const QStringList &values, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(values, Path, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentFolderId()
*/
00412 QMailFolderKey QMailFolderKey::parentFolderId(const QMailFolderId &id, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(ParentFolderId, id, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentFolderId()
*/
00422 QMailFolderKey QMailFolderKey::parentFolderId(const QMailFolderIdList &ids, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(ids, ParentFolderId, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentFolderId()
*/
00432 QMailFolderKey QMailFolderKey::parentFolderId(const QMailFolderKey &key, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(ParentFolderId, key, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentAccountId()
*/
00442 QMailFolderKey QMailFolderKey::parentAccountId(const QMailAccountId &id, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(ParentAccountId, id, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentAccountId()
*/
00452 QMailFolderKey QMailFolderKey::parentAccountId(const QMailAccountIdList &ids, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(ids, ParentAccountId, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentAccountId()
*/
00462 QMailFolderKey QMailFolderKey::parentAccountId(const QMailAccountKey &key, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(ParentAccountId, key, QMailKey::comparator(cmp));
}

/*!
    Returns a key matching folders whose display name matches \a value, according to \a cmp.

    \sa QMailFolder::displayName()
*/
00472 QMailFolderKey QMailFolderKey::displayName(const QString &value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(DisplayName, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::displayName()
*/
00482 QMailFolderKey QMailFolderKey::displayName(const QString &value, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(DisplayName, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::displayName()
*/
00492 QMailFolderKey QMailFolderKey::displayName(const QStringList &values, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(values, DisplayName, QMailKey::comparator(cmp));
}

/*!
    Returns a key matching folders whose status matches \a value, according to \a cmp.

    \sa QMailFolder::status()
*/
00502 QMailFolderKey QMailFolderKey::status(quint64 value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(Status, value, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::status()
*/
00512 QMailFolderKey QMailFolderKey::status(quint64 mask, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(Status, mask, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentFolderId()
*/
00522 QMailFolderKey QMailFolderKey::ancestorFolderIds(const QMailFolderId &id, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(AncestorFolderIds, id, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentFolderId()
*/
00532 QMailFolderKey QMailFolderKey::ancestorFolderIds(const QMailFolderIdList &ids, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(ids, AncestorFolderIds, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::parentFolderId()
*/
00542 QMailFolderKey QMailFolderKey::ancestorFolderIds(const QMailFolderKey &key, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(AncestorFolderIds, key, QMailKey::comparator(cmp));
}

/*!
    Returns a key matching folders whose serverCount matches \a value, according to \a cmp.

    \sa QMailFolder::serverCount()
*/
00552 QMailFolderKey QMailFolderKey::serverCount(int value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(ServerCount, value, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::serverCount()
*/
00562 QMailFolderKey QMailFolderKey::serverCount(int value, QMailDataComparator::RelationComparator cmp)
{
    return QMailFolderKey(ServerCount, value, QMailKey::comparator(cmp));
}

/*!
    Returns a key matching folders whose serverUnreadCount matches \a value, according to \a cmp.

    \sa QMailFolder::serverUnreadCount()
*/
00572 QMailFolderKey QMailFolderKey::serverUnreadCount(int value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(ServerUnreadCount, value, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::serverUnreadCount()
*/
00582 QMailFolderKey QMailFolderKey::serverUnreadCount(int value, QMailDataComparator::RelationComparator cmp)
{
    return QMailFolderKey(ServerUnreadCount, value, QMailKey::comparator(cmp));
}

/*!
    Returns a key matching folders whose serverUndiscoveredCount matches \a value, according to \a cmp.

    \sa QMailFolder::serverUndiscoveredCount()
*/
00592 QMailFolderKey QMailFolderKey::serverUndiscoveredCount(int value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(ServerUndiscoveredCount, value, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::serverUndiscoveredCount()
*/
00602 QMailFolderKey QMailFolderKey::serverUndiscoveredCount(int value, QMailDataComparator::RelationComparator cmp)
{
    return QMailFolderKey(ServerUndiscoveredCount, value, QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::customField()
*/
00612 QMailFolderKey QMailFolderKey::customField(const QString &name, QMailDataComparator::PresenceComparator cmp)
{
    return QMailFolderKey(Custom, QStringList() << QMailKey::stringValue(name), QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::customField()
*/
00622 QMailFolderKey QMailFolderKey::customField(const QString &name, const QString &value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailFolderKey(Custom, QStringList() << QMailKey::stringValue(name) << QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailFolder::customField()
*/
00632 QMailFolderKey QMailFolderKey::customField(const QString &name, const QString &value, QMailDataComparator::InclusionComparator cmp)
{
    return QMailFolderKey(Custom, QStringList() << QMailKey::stringValue(name) << QMailKey::stringValue(value), QMailKey::comparator(cmp));
}



Generated by  Doxygen 1.6.0   Back to index