path: root/src/serviceframework/qservicefilter.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 Mobility Components.
**
** $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 <QRegExp>
#include <QStringList>
#include <QDebug>
#ifndef QT_NO_DATASTREAM
#include <qdatastream.h>
#endif

#include "qservicefilter.h"

QTM_BEGIN_NAMESPACE

class QServiceFilterPrivate
{
public:
    QString interface;
    QString service;
    int majorVersion;
    int minorVersion;
    QServiceFilter::VersionMatchRule matchingRule;
    QHash<QString,QString> customAttributes;
    QStringList capabilities;
    QServiceFilter::CapabilityMatchRule capMatchingRule;
};


/*!
    \class QServiceFilter
    
    \ingroup servicefw
    \inmodule QtServiceFramework
    \brief The QServiceFilter class defines criteria for defining a sub-set of 
    all available services.

    A QServiceFilter can be used to constrain the number of services when searching
    for services. Only those services that match all filter criteria are returned
    by \l QServiceManager::findInterfaces().
    

    \sa QServiceInterfaceDescriptor, QServiceManager
*/

/*!
    \enum QServiceFilter::VersionMatchRule

    This enum describes how interface version matching is performed.

    \value ExactVersionMatch    The filter matches any interface implementation that implements
                                the exact version provided. 
    \value MinimumVersionMatch  The filter matches any interface implementation that implements
                                either the given major/minor version or any subsequent version.
*/

/*!
    \enum QServiceFilter::CapabilityMatchRule

    This enum describes the capability/permission matching rules. Some platforms restrict what services clients 
    can access using "capabilities" or permissions. Services with more capabilities require 
    more privileged clients. Platforms without capabilities may ignore this type of matching
    rule as the default behavior is to ignore any capability restrictions.

    This is a brief example. Assuming that the system knows the services S1 - S6 which require capabilities as stated below:
    \table
        \header     \o Service  \o Required capabilities
        \row        \o S1       \o \{\}
        \row        \o S2       \o \{A\}
        \row        \o S3       \o \{A,B\}
        \row        \o S4       \o \{A,B,C,D\}
        \row        \o S5       \o \{A,D\}
        \row        \o S6       \o \{F\}
    \endtable

    The matching rules would apply as follows:

    \table
        \header     \o Matching rule    \o Filter's capabilities    \o Matching services
        \row        \o MatchLoadable    \o \{\}                       \o S1
        \row        \o MatchLoadable    \o \{A\}                      \o S1, S2
        \row        \o MatchLoadable    \o \{A,B,C\}                  \o S1, S2, S3
        \row        \o MatchMinimum     \o \{\}                       \o S1, S2, S3, S4, S5, S6
        \row        \o MatchMinimum     \o \{A\}                      \o S2, S3, S4, S5
        \row        \o MatchMinimum     \o \{A,B,C\}                  \o S4
    \endtable
    
    \value MatchMinimum     The filter matches any service that requires at least the given 
                            filter capabilities. This may mean that the returned services
                            may require more capabilities than the specified ones.
                            Such a search is equivalent to a wildcard match if the passed filter's capability list is empty. In mathematical set notation 
                            this rule is equivalent to Cap\sub{(Filter)} \\ Cap\sub{(Service)} = {}. This is the default matching rule.
    \value MatchLoadable    The filter matches any service that could be loaded by the client.
                            Using this matching rule guarantees that the returned services do not
                            require more capabilites than specified by this rule. It includes services
                            with no capability requirements. If this rule
                            is provided alongside an empty capability search list the returned 
                            services do not require any capabilities and thus can be accessed
                            by any client. The equivalent set notation is Cap\sub{(Service)} \\ Cap\sub{(Filter)} = {}.
*/

/*!
    Creates a new filter object that matches all service implementations.
*/
QServiceFilter::QServiceFilter()
{
    d = new QServiceFilterPrivate();
    d->majorVersion = -1;
    d->minorVersion = -1;
    d->matchingRule = QServiceFilter::MinimumVersionMatch;
    d->capMatchingRule = QServiceFilter::MatchMinimum;
}

/*!
    Creates a copy of QServiceFilter object contained in \a other.
*/
QServiceFilter::QServiceFilter(const QServiceFilter& other)
{
    d = new QServiceFilterPrivate();
    (*this) = other;
}

/*!
    \fn  QServiceFilter::QServiceFilter(const QString& interfaceName, const QString& version, QServiceFilter::VersionMatchRule rule)
    
    Creates a new filter object that matches all service
    implementations implementing \a interfaceName that match the specified
    \a version using the given \a rule.
*/
QServiceFilter::QServiceFilter(const QString& interfaceName, const QString& version, QServiceFilter::VersionMatchRule rule)
{
    d = new QServiceFilterPrivate();
    d->majorVersion = -1;
    d->minorVersion = -1;
    d->matchingRule = QServiceFilter::MinimumVersionMatch;
    d->capMatchingRule = QServiceFilter::MatchMinimum;
    setInterface(interfaceName, version, rule);
}

/*!
    Destroys this instance of QServiceFilter.
*/
QServiceFilter::~QServiceFilter()
{
    delete d;
}

/*!
    \fn  QServiceFilter& QServiceFilter::operator=(const QServiceFilter& other)
    
    Copies the content of the QServiceFilter object contained in 
    \a other into this one.
*/
QServiceFilter& QServiceFilter::operator=(const QServiceFilter& other)
{
    d->interface = other.d->interface;
    d->service = other.d->service;
    d->majorVersion = other.d->majorVersion;
    d->minorVersion = other.d->minorVersion;
    d->matchingRule = other.d->matchingRule;
    d->customAttributes = other.d->customAttributes;
    d->capabilities = other.d->capabilities;
    d->capMatchingRule = other.d->capMatchingRule;

    return *this;
}

/*!
    \fn  void QServiceFilter::setServiceName(const QString& serviceName)
    
    The filter only matches implementations which are provided by the service
    specified by \a serviceName.

    If the \a serviceName is empty the filter matches any service.
*/
void QServiceFilter::setServiceName(const QString& serviceName)
{
    d->service = serviceName;
}

/*!
    \fn  void QServiceFilter::setInterface(const QString &interfaceName, const QString& version, QServiceFilter::VersionMatchRule rule)
    
    Sets the filter to match any interface implementation that implements
    \a interfaceName with version \a version. The version is matched
    according to the given \a rule. If \a version is not set, the filter matches any version of the
    interface implementation.

    This method does nothing if \a version is not a valid version string or
    if \a interfaceName is empty.

    A valid version string has the format x.y whereby x and y are positive integer
    numbers.
*/
void QServiceFilter::setInterface(const QString &interfaceName, const QString& version, QServiceFilter::VersionMatchRule rule)
{
    //unset interface name
    if (interfaceName.isEmpty() && version.isEmpty()) 
    {
        d->interface = interfaceName;
        d->majorVersion = d->minorVersion = -1;
        d->matchingRule = rule;
        return;
    }

    if (interfaceName.isEmpty()) {
        qWarning() << "Empty interface name. Ignoring filter details";
        return;
    }

    if (version.isEmpty()) {
        d->majorVersion = d->minorVersion = -1;
        d->matchingRule = rule;
        d->interface = interfaceName;
        return;
    }

    // Match x.y as version format.
    // This differs from regex in servicemetadata in that 0.x versions are
    // accepted for the search filter.
    QRegExp rx("^(0+|[1-9][0-9]*)\\.(0+|[1-9][0-9]*)$");
    int pos = rx.indexIn(version);
    QStringList list = rx.capturedTexts();
    bool success = false;
    int temp_major = -1;
    int temp_minor = -1;
    if (pos == 0 && list.count() == 3 
            && rx.matchedLength() == version.length() ) 
    {
        temp_major = list[1].toInt(&success);
        if ( success ) {
            temp_minor = list[2].toInt(&success);
       }
    }

    if (success) {
        d->majorVersion = temp_major;
        d->minorVersion = temp_minor;
        d->interface = interfaceName;
        d->matchingRule = rule;
    } else {
        qWarning() << "Invalid version tag" << version << ". Ignoring filter details.";
    }
}

/*!
    \fn  QString QServiceFilter::serviceName() const
    
    Returns the service name for this filter.

    \sa setServiceName()
*/
QString QServiceFilter::serviceName() const
{
    return d->service;
}

/*!
    \fn  QString QServiceFilter::interfaceName() const
    
    Returns the interface name for this filter.

    \sa setInterface()
*/
QString QServiceFilter::interfaceName() const
{
    return d->interface;
}

/*!
    \fn  int QServiceFilter::majorVersion() const
    
    Returns the major interface version for this filter.

    \sa setInterface()
*/
int QServiceFilter::majorVersion() const
{
    return d->majorVersion;
}

/*!
    \fn  int QServiceFilter::minorVersion() const
    
    Returns the minor interface version for this filter.

    \sa setInterface()
*/
int QServiceFilter::minorVersion() const
{
    return d->minorVersion;
}

/*!
    \fn  void QServiceFilter::setCustomAttribute(const QString& key, const QString& value)
    
    The filter only matches implementations which have the custom attribute
    \a key with the given \a value. Such constraints are specified via the 
    \i{<customproperty>} tag within the service xml.

    \sa customAttribute(), clearCustomAttribute()
*/
void QServiceFilter::setCustomAttribute(const QString& key, const QString& value)
{
    d->customAttributes.insert(key, value);
}

/*!
    \fn  QString QServiceFilter::customAttribute(const QString& key) const
    
    Returns the value for the custom attribute \a key; otherwise
    returns a null string.

    \sa setCustomAttribute(), clearCustomAttribute()
*/
QString QServiceFilter::customAttribute(const QString& key) const
{
    return d->customAttributes.value(key);
}

/*!
    \fn  void QServiceFilter::clearCustomAttribute(const QString &key)
    
    Clears the custom attribute \a key from the filter's set of constraints.
    If \a key is empty all custom attributes are cleared.

    \sa setCustomAttribute()
*/
void QServiceFilter::clearCustomAttribute(const QString &key)
{
    if (key.isEmpty())
        d->customAttributes.clear();
    else
        d->customAttributes.remove(key);
}

/*!
    \fn  QServiceFilter::VersionMatchRule QServiceFilter::versionMatchRule() const
    
    Returns the version match rule for this filter.

    \sa setInterface()
*/
QServiceFilter::VersionMatchRule QServiceFilter::versionMatchRule() const
{
    return d->matchingRule;
}

/*!
    \fn  QList<QString> QServiceFilter::customAttributes() const
    
    Returns the list of custom keys which have been added to the filter.
*/
QStringList QServiceFilter::customAttributes() const
{
    return d->customAttributes.keys();
}

/*!
    \fn  void QServiceFilter::setCapabilities(QServiceFilter::CapabilityMatchRule rule, const QStringList& capabilities )
    
    Sets the list of \a capabilities which are used to constrain
    searches for services. The capabilities are matched according
    to the given \a rule.
    
    \sa capabilities(), QAbstractSecuritySession
*/
void QServiceFilter::setCapabilities(QServiceFilter::CapabilityMatchRule rule, const QStringList& capabilities )
{
    d->capMatchingRule = rule;
    d->capabilities = capabilities;
}

/*!
    \fn  QStringList QServiceFilter::capabilities() const
    
    Returns the list of capabilities which are used to limit services searches.

    The filter matches any services that requires the given or less
    capabilities and thus enabling clients to query for services
    for which they have the required capabilties.

    \sa setCapabilities(), capabilityMatchRule(), QAbstractSecuritySession
*/
QStringList QServiceFilter::capabilities() const
{
    return d->capabilities;
}

/*!
    Returns the capability matching rule for this filter.

    \sa setCapabilities(), capabilities()
*/
QServiceFilter::CapabilityMatchRule QServiceFilter::capabilityMatchRule() const
{
    return d->capMatchingRule;
}

#ifndef QT_NO_DATASTREAM
/*! 
    \fn QDataStream &operator<<(QDataStream &out, const QServiceFilter &sf)
    \relates QServiceFilter

    Writes service filter \a sf to the stream \a out and returns a reference
    to the stream.
*/

QDataStream &operator<<(QDataStream &out, const QServiceFilter &sf)
{
    const quint32 magicNumber = 0x78AFAFA;
    const qint32 mj = sf.d->majorVersion;
    const qint32 mn = sf.d->minorVersion;
    const qint8 versionrule = (qint32) sf.d->matchingRule;
    const qint8 caprule = (qint8) sf.d->capMatchingRule;
    const quint16 majorVersion = 1;
    const quint16 minorVersion = 0;

    out << magicNumber
        << majorVersion
        << minorVersion
        << sf.d->interface
        << sf.d->service
        << mj
        << mn
        << versionrule
        << sf.d->customAttributes
        << caprule
        << sf.d->capabilities;
    return out;
}

/*!
    \fn QDataStream &operator>>(QDataStream &in, QServiceFilter &sf)
    \relates QServiceFilter

    Reads a service filter into \a sf from the stream \a in and returns a
    reference to the stream.
*/
QDataStream &operator>>(QDataStream &in, QServiceFilter &sf)
{
    const quint32 magicNumber = 0x78AFAFA;
    qint32 mj, mn;
    qint8 versionrule, caprule;

    quint32 storedMagicNumber;
    in >> storedMagicNumber;
    if (storedMagicNumber != magicNumber) {
        qWarning() << "Datastream doesn't provide serialized QServiceFilter";
        return in;
    }

    const quint16 currentMajorVersion = 1;
    quint16 majorVersion = 0;
    quint16 minorVersion = 0;

    in >> majorVersion >> minorVersion;
    if (majorVersion != currentMajorVersion) {
        qWarning() << "Unknown serialization format for QServiceFilter.";
        return in;
    }
    //Allow all minor versions.

    in  >> sf.d->interface
        >> sf.d->service
        >> mj
        >> mn
        >> versionrule
        >> sf.d->customAttributes
        >> caprule
        >> sf.d->capabilities;

    sf.d->majorVersion = mj;
    sf.d->minorVersion = mn;
    sf.d->matchingRule = (QServiceFilter::VersionMatchRule) versionrule;
    sf.d->capMatchingRule = (QServiceFilter::CapabilityMatchRule) caprule;

    return in;
}
#endif //QT_NO_DATASTREAM


QTM_END_NAMESPACE