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

qmailaccountkey.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 "qmailaccountkey.h"
#include "qmailaccountkey_p.h"

#include <QStringList>
#include <QDateTime>

using namespace QMailDataComparator;

/*!
    \class QMailAccountKey

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

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

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

    For example:

    To create a query for all accounts handling email messages:
    \code
    QMailAccountKey emailKey(QMailAccountKey::messageType(QMailMessage::Email));
    QMailAccountIdList results = QMailStore::instance()->queryAccounts(emailKey);
    \endcode

    To query all accounts handling SMS or MMS messages:
    \code
    QMailAccountKey mmsAccount(QMailAccountKey::messageType(QMailMessage::Mms));
    QMailAccountKey smsAccount(QMailAccountKey::messageType(QMailMessage::Sms));
    QMailAccountIdList results = QMailStore::instance()->queryAccounts(mmsAccount | smsAccount);
    \endcode

    \sa QMailStore, QMailAccount
*/

/*!
    \enum QMailAccountKey::Property

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

    \value Id The ID of the account.
    \value Name The name of the account.
    \value MessageType The type of messages handled by the account.
    \value FromAddress The address from which the account's outgoing messages should be reported as originating.
    \value Status The status value of the account.
    \value Custom The custom fields of the account.
    \value LastSynchronized The most recent time that a check for new mail in all folders of the account was completed successfully.
*/

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

/*!
    \typedef QMailAccountKey::ArgumentType

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

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

Q_IMPLEMENT_USER_METATYPE(QMailAccountKey);

/*!
    Creates a QMailAccountKey without specifying matching parameters.

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

    \sa isEmpty()
*/
00120 QMailAccountKey::QMailAccountKey()
    : d(new QMailAccountKeyPrivate)
{
}

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

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

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

/*!
    Destroys this QMailAccountKey.
*/
00156 QMailAccountKey::~QMailAccountKey()
{
}

/*!
    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()
*/
00168 QMailAccountKey QMailAccountKey::operator~() const
{
    return QMailAccountKeyPrivate::negate(*this);
}

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

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

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

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

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

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

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

    An empty key matches all accounts.

    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()
*/
00246 bool QMailAccountKey::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 accounts.

    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()
*/
00263 bool QMailAccountKey::isNonMatching() const
{
    return d->isNonMatching();
}

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

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

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

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

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

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

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

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

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

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

    \sa isNonMatching(), isEmpty()
*/
00333 QMailAccountKey QMailAccountKey::nonMatchingKey()
{
    return QMailAccountKeyPrivate::nonMatchingKey();
}

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

    \sa QMailAccount::id()
*/
00343 QMailAccountKey QMailAccountKey::id(const QMailAccountId &id, QMailDataComparator::EqualityComparator cmp)
{
    return QMailAccountKey(Id, id, QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::id()
*/
00353 QMailAccountKey QMailAccountKey::id(const QMailAccountIdList &ids, QMailDataComparator::InclusionComparator cmp)
{
    return QMailAccountKey(ids, Id, QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::id()
*/
00363 QMailAccountKey QMailAccountKey::id(const QMailAccountKey &key, QMailDataComparator::InclusionComparator cmp)
{
    return QMailAccountKey(Id, key, QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::name()
*/
00373 QMailAccountKey QMailAccountKey::name(const QString &value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailAccountKey(Name, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::name()
*/
00383 QMailAccountKey QMailAccountKey::name(const QString &value, QMailDataComparator::InclusionComparator cmp)
{
    return QMailAccountKey(Name, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::name()
*/
00393 QMailAccountKey QMailAccountKey::name(const QStringList &values, QMailDataComparator::InclusionComparator cmp)
{
    return QMailAccountKey(values, Name, QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::messageType()
*/
00403 QMailAccountKey QMailAccountKey::messageType(QMailMessageMetaDataFwd::MessageType value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailAccountKey(MessageType, static_cast<int>(value), QMailKey::comparator(cmp));
}

/*! 
    Returns a key matching accounts whose messageType is a bitwise match to \a value, according to \a cmp.

    \sa QMailAccount::messageType()
*/
00413 QMailAccountKey QMailAccountKey::messageType(int value, QMailDataComparator::InclusionComparator cmp)
{
    return QMailAccountKey(MessageType, value, QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::fromAddress()
*/
00423 QMailAccountKey QMailAccountKey::fromAddress(const QString &value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailAccountKey(FromAddress, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::fromAddress()
*/
00433 QMailAccountKey QMailAccountKey::fromAddress(const QString &value, QMailDataComparator::InclusionComparator cmp)
{
    return QMailAccountKey(FromAddress, QMailKey::stringValue(value), QMailKey::comparator(cmp));
}

/*! 
    Returns a key matching accounts whose last synchronization time matches the time \a value, according to \a cmp.

    \sa QMailAccount::lastSynchronized()
*/
00443 QMailAccountKey QMailAccountKey::lastSynchronized(const QDateTime &value, QMailDataComparator::EqualityComparator cmp)
{
    // An invalid QDateTime does not exist-compare correctly, so use a substitute value
    return QMailAccountKey(LastSynchronized, (value.isNull() ? QDateTime::fromTime_t(0) : value), QMailKey::comparator(cmp));
}

/*!
    Returns a key matching accounts whose last synchronization timestamp has the relation to \a value that is specified by \a cmp.

    \sa QMailAccount::lastSynchronized()
*/
00454 QMailAccountKey QMailAccountKey::lastSynchronized(const QDateTime &value, QMailDataComparator::RelationComparator cmp)
{
    return QMailAccountKey(LastSynchronized, value, QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::status()
*/
00464 QMailAccountKey QMailAccountKey::status(quint64 value, QMailDataComparator::EqualityComparator cmp)
{
    return QMailAccountKey(Status, value, QMailKey::comparator(cmp));
}

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

    \sa QMailAccount::status()
*/
00474 QMailAccountKey QMailAccountKey::status(quint64 mask, QMailDataComparator::InclusionComparator cmp)
{
    return QMailAccountKey(Status, mask, QMailKey::comparator(cmp));
}

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

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

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

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

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

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


Generated by  Doxygen 1.6.0   Back to index