/****************************************************************************

**

** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

** All rights reserved.

** Contact: Nokia Corporation (qt-info@nokia.com)

**

** This file is part of the QtDBus module of the Qt Toolkit.

**

** $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 "qdbusargument.h"

#include <qatomic.h>

#include <qbytearray.h>

#include <qlist.h>

#include <qmap.h>

#include <qstring.h>

#include <qstringlist.h>

#include <qvariant.h>

#include <qdatetime.h>

#include <qrect.h>

#include <qline.h>

#include "qdbusargument_p.h"

#include "qdbusmetatype_p.h"

#include "qdbusutil_p.h"

QT_BEGIN_NAMESPACE

QDBusArgumentPrivate::~QDBusArgumentPrivate()

{

    if (message)

        q_dbus_message_unref(message);

}

QByteArray QDBusArgumentPrivate::createSignature(int id)

{

    if (!qdbus_loadLibDBus())

        return "";

    QByteArray signature;

    QDBusMarshaller *marshaller = new QDBusMarshaller;

    marshaller->ba = &signature;

    // run it

    void *null = 0;

    QVariant v(id, null);

    QDBusArgument arg(marshaller);

    QDBusMetaType::marshall(arg, v.userType(), v.constData());

    arg.d = 0;

    // delete it

    bool ok = marshaller->ok;

    delete marshaller;

    if (signature.isEmpty() || !ok || !QDBusUtil::isValidSingleSignature(QString::fromLatin1(signature))) {

        qWarning("QDBusMarshaller: type `%s' produces invalid D-BUS signature `%s' "

                 "(Did you forget to call beginStructure() ?)",

                 QVariant::typeToName( QVariant::Type(id) ),

                 signature.isEmpty() ? "<empty>" : signature.constData());

        return "";

    } else if ((signature.at(0) != DBUS_TYPE_ARRAY && signature.at(0) != DBUS_STRUCT_BEGIN_CHAR) ||

               (signature.at(0) == DBUS_TYPE_ARRAY && (signature.at(1) == DBUS_TYPE_BYTE ||

                                                       signature.at(1) == DBUS_TYPE_STRING))) {

        qWarning("QDBusMarshaller: type `%s' attempts to redefine basic D-BUS type '%s' (%s) "

                 "(Did you forget to call beginStructure() ?)",

                 QVariant::typeToName( QVariant::Type(id) ),

                 signature.constData(),

                 QVariant::typeToName( QVariant::Type(QDBusMetaType::signatureToType(signature))) );

        return "";

    }

    return signature;

}

bool QDBusArgumentPrivate::checkWrite(QDBusArgumentPrivate *&d)

{

    if (!d)

        return false;

    if (d->direction == Marshalling) {

        if (!d->marshaller()->ok)

            return false;

        if (d->message && d->ref != 1) {

            QDBusMarshaller *dd = new QDBusMarshaller;

            dd->message = q_dbus_message_copy(d->message);

            q_dbus_message_iter_init_append(dd->message, &dd->iterator);

            if (!d->ref.deref())

                delete d;

            d = dd;

        }

        return true;

    }

#ifdef QT_DEBUG

    qFatal("QDBusArgument: write from a read-only object");

#else

    qWarning("QDBusArgument: write from a read-only object");

#endif

    return false;

}

bool QDBusArgumentPrivate::checkRead(QDBusArgumentPrivate *d)

{

    if (!d)

        return false;

    if (d->direction == Demarshalling)

        return true;

#ifdef QT_DEBUG

    qFatal("QDBusArgument: read from a write-only object");

#else

    qWarning("QDBusArgument: read from a write-only object");

#endif

    return false;

}

bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)

{

    if (!checkRead(d))

        return false;           //  don't bother

    if (d->ref == 1)

        return true;            // no need to detach

    QDBusDemarshaller *dd = new QDBusDemarshaller;

    dd->message = q_dbus_message_ref(d->message);

    dd->iterator = static_cast<QDBusDemarshaller*>(d)->iterator;

    if (!d->ref.deref())

        delete d;

    d = dd;

    return true;

}

/*!

    \class QDBusArgument

    \inmodule QtDBus

    \since 4.2

    \brief The QDBusArgument class is used to marshall and demarshall D-Bus arguments.

    The class is used to send arguments over D-Bus to remote

    applications and to receive them back. D-Bus offers an extensible

    type system, based on a few primitive types and associations of

    them. See the \l {qdbustypesystem.html}{QtDBus type system} page

    for more information on the type system.

    QDBusArgument is the central class in the QtDBus type system,

    providing functions to marshall and demarshall the primitive

    types. The compound types are then created by association of one

    or more of the primitive types in arrays, dictionaries or

    structures.

    The following example illustrates how a structure containing an

    integer and a string can be constructed using the \l

    {qdbustypesystem.html}{QtDBus type system}:

    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 0

    The type has to be registered with qDBusRegisterMetaType() before

    it can be used with QDBusArgument. Therefore, somewhere in your

    program, you should add the following code:

    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 1

    Once registered, a type can be used in outgoing method calls

    (placed with QDBusAbstractInterface::call()), signal emissions

    from registered objects or in incoming calls from remote

    applications.

    It is important to note that the \c{operator<<} and \c{operator>>}

    streaming functions must always produce the same number of entries

    in case of structures, both in reading and in writing (marshalling

    and demarshalling), otherwise calls and signals may start to

    silently fail.

    The following example illustrates this wrong usage

    in context of a class that may contain invalid data:

    \badcode

        // Wrongly marshall the MyTime data into a D-Bus argument

        QDBusArgument &operator<<(QDBusArgument &argument, const MyTime &mytime)

        {

            argument.beginStructure();

            if (mytime.isValid)

                argument << true << mytime.hour

                         << mytime.minute << mytime.second;

            else

                argument << false;

            argument.endStructure();

            return argument;

        }

    \endcode

    In this example, both the \c{operator<<} and the \c{operator>>}

    functions may produce a different number of reads/writes. This can

    confuse the QtDBus type system and should be avoided.

    \sa QDBusAbstractInterface, {qdbustypesystem.html}{The QtDBus type

    system}, {usingadaptors.html}{Using Adaptors}, qdbus_cast()

*/

/*!

    \enum QDBusArgument::ElementType

    \since 4.5

    This enum describes the type of element held by the argument.

    \value BasicType A basic element, which is understood by

        QVariant. The following types are considered basic: bool,

        byte, short, ushort, int, uint, qint64, quint64, double,

        QString, QByteArray, QDBusObjectPath, QDBusSignature

    \value VariantType The variant element (QDBusVariant)

    \value ArrayType An array element, usually represented by QList<T>

    or QVector<T>. Note: QByteArray and associative maps are not

    considered arrays, even if the D-Bus protocol transports them as such.

    \value StructureType A custom type represented by a structure,

    like QDateTime, QPoint, etc.

    \value MapType An associative container, like QMap<Key, Value> or

    QHash<Key, Value>

    \value MapEntryType One entry in an associative container: both

    the key and the value form one map-entry type.

    \value UnknownType The type is unknown or we have reached the end

    of the list.

    \sa currentType()

*/

/*!

    \fn qdbus_cast(const QDBusArgument &argument)

    \relates QDBusArgument

    \since 4.2

    Attempts to demarshall the contents of \a argument into the type

    \c{T}. For example:

    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 2

    Note that it is equivalent to the following:

    \snippet doc/src/snippets/code/src_qdbus_qdbusargument.cpp 3

*/

/*!

    Constructs an empty QDBusArgument argument.

    An empty QDBusArgument object does not allow either reading or

    writing to be performed.

*/

QDBusArgument::QDBusArgument()

{

    if (!qdbus_loadLibDBus()) {

        d = 0;

        return;

    }

    QDBusMarshaller *dd = new QDBusMarshaller;

    d = dd;

    // create a new message with any type, we won't sent it anyways

    dd->message = q_dbus_message_new(DBUS_MESSAGE_TYPE_METHOD_CALL);

    q_dbus_message_iter_init_append(dd->message, &dd->iterator);

}

/*!

    Constructs a copy of the \a other QDBusArgument object.

    Both objects will therefore contain the same state from this point

    forward. QDBusArguments are explicitly shared and, therefore, any

    modification to either copy will affect the other one too.

*/

QDBusArgument::QDBusArgument(const QDBusArgument &other)

    : d(other.d)

{

    if (d)

        d->ref.ref();

}

/*!

    \internal

*/

QDBusArgument::QDBusArgument(QDBusArgumentPrivate *dd)

    : d(dd)

{

}

/*!

    Copies the \a other QDBusArgument object into this one.

    Both objects will therefore contain the same state from this point

    forward. QDBusArguments are explicitly shared and, therefore, any

    modification to either copy will affect the other one too.

*/

QDBusArgument &QDBusArgument::operator=(const QDBusArgument &other)

{

    qAtomicAssign(d, other.d);

    return *this;

}

/*!

    Disposes of the resources associated with this QDBusArgument

    object.

*/

QDBusArgument::~QDBusArgument()

{

    if (d && !d->ref.deref())

        delete d;

}

/*!

    Appends the primitive value \a arg of type \c{BYTE} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(uchar arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{BOOLEAN} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(bool arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{INT16} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(short arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{UINT16} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(ushort arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{INT32} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(int arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{UINT32} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(uint arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{INT64} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(qlonglong arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{UINT64} to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(qulonglong arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{DOUBLE} (double-precision

    floating-point) to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(double arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{STRING} (Unicode character

    string) to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(const QString &arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    \internal

    Appends the primitive value \a arg of type \c{OBJECT_PATH} (path to a D-Bus

    object) to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(const QDBusObjectPath &arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    \internal

    Appends the primitive value \a arg of type \c{SIGNATURE} (D-Bus type

    signature) to the D-Bus stream.

*/

QDBusArgument &QDBusArgument::operator<<(const QDBusSignature &arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the primitive value \a arg of type \c{VARIANT} to the D-Bus stream.

    A D-Bus variant type can contain any type, including other

    variants. It is similar to the Qt QVariant type.

*/

QDBusArgument &QDBusArgument::operator<<(const QDBusVariant &arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the QStringList given by \a arg as \c{ARRAY of STRING}

    to the D-Bus stream.

    QStringList and QByteArray are the only two non-primitive types

    that are supported directly by QDBusArgument because of their

    widespread usage in Qt applications.

    Other arrays are supported through compound types in QtDBus.

*/

QDBusArgument &QDBusArgument::operator<<(const QStringList &arg)

{

    if (QDBusArgumentPrivate::checkWrite(d))

        d->marshaller()->append(arg);

    return *this;

}

/*!

    \overload

    Appends the QByteArray given by \a arg as \c{ARRAY of BYTE}

    to the D-Bus stream.

    QStringList and QByteArray are the only two non-primitive types

    that are supported directly by QDBusArgument because of their

    widespread usage in Qt applications.

    Other arrays are supported through compound types in QtDBus.

*/