qdbusargument.cpp

QT 开发环境里面一个很重要的文件

    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 (d && d->checkWrite())
        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.
*/
QDBusArgument &QDBusArgument::operator<<(const QByteArray &arg)
{
    if (d && d->checkWrite())
        d->marshaller()->append(arg);
    return *this;
}

/*!
    \internal
    Returns the type signature of the D-BUS type this QDBusArgument
    object is currently pointing to.
*/
QString QDBusArgument::currentSignature() const
{
    if (d && d->checkRead())
        return d->demarshaller()->currentSignature();

    return QString();
}

/*!
    Extracts one D-BUS primitive argument of type \c{BYTE} from the
    D-BUS stream and puts it into \a arg.
*/
const QDBusArgument &QDBusArgument::operator>>(uchar &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toByte();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{BOOLEAN} from the
    D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(bool &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toBool();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{UINT16} from the
    D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(ushort &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toUShort();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{INT16} from the
    D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(short &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toShort();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{INT32} from the
    D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(int &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toInt();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{UINT32} from the
    D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(uint &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toUInt();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{INT64} from the
    D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(qlonglong &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toLongLong();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{UINT64} from the
    D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(qulonglong &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toULongLong();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{DOUBLE}
    (double-precision floating pount) from the D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(double &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toDouble();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{STRING} (Unicode
    character string) from the D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(QString &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toString();
    return *this;
}

/*!
    \overload
    \internal
    Extracts one D-BUS primitive argument of type \c{OBJECT_PATH}
    (D-BUS path to an object) from the D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(QDBusObjectPath &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toObjectPath();
    return *this;
}

/*!
    \overload
    \internal
    Extracts one D-BUS primitive argument of type \c{SIGNATURE} (D-BUS
    type signature) from the D-BUS stream.
*/
const QDBusArgument &QDBusArgument::operator>>(QDBusSignature &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toSignature();
    return *this;
}

/*!
    \overload
    Extracts one D-BUS primitive argument of type \c{VARIANT} from the
    D-BUS stream.

    A D-BUS variant type can contain any type, including other
    variants. It is similar to the Qt QVariant type.

    In case the variant contains a type not directly supported by
    QDBusArgument, the value of the returned QDBusVariant will contain
    another QDBusArgument. It is your responsibility to further
    demarshall it into another type.
*/
const QDBusArgument &QDBusArgument::operator>>(QDBusVariant &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toVariant();
    return *this;
}

/*!
    \overload
    Extracts an array of strings from the D-BUS stream and return it
    as a QStringList.

    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.
*/
const QDBusArgument &QDBusArgument::operator>>(QStringList &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toStringList();
    return *this;
}

/*!
    \overload
    Extracts an array of bytes from the D-BUS stream and return it
    as a QByteArray.

    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.
*/
const QDBusArgument &QDBusArgument::operator>>(QByteArray &arg) const
{
    if (d && d->checkRead())
        arg = d->demarshaller()->toByteArray();
    return *this;
}

/*!
    Opens a new D-BUS structure suitable for appending new arguments.

    This function is used usually in \c{operator<<} streaming
    operators, as in the following example:

    \code
        QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct)
        {
            argument.beginStructure();
            argument << mystruct.member1 << mystruct.member2 << ... ;
            argument.endStructure();
            return argument;
        }
    \endcode

    Structures can contain other structures, so the following code is
    also valid:

    \code
        QDBusArgument &operator<<(QDBusArgument &argument, const MyStructure &mystruct)
        {
            argument.beginStructure();
            argument << mystruct.member1 << mystruct.member2;

            argument.beginStructure();
            argument << mystruct.member3.subMember1 << mystruct.member3.subMember2;
            argument.endStructure();

            argument << mystruct.member4;
            argument.endStructure();
            return argument;
        }
    \endcode

    \sa endStructure(), beginArray(), beginMap()
*/
void QDBusArgument::beginStructure()
{
    if (d && d->checkWrite())
        d = d->marshaller()->beginStructure();
}

/*!
    Closes a D-BUS structure opened with beginStructure(). This function must be called
    same number of times that beginStructure() is called.

    \sa beginStructure(), endArray(), endMap()
*/
void QDBusArgument::endStructure()
{
    if (d && d->checkWrite())
        d = d->marshaller()->endStructure();
}

/*!
    Opens a new D-BUS array suitable for appending elements of meta-type \a id.

    This function is used usually in \c{operator<<} streaming
    operators, as in the following example:

    \code
        // append an array of MyElement types
        QDBusArgument &operator<<(QDBusArgument &argument, const MyArray &myarray)
        {
            argument.beginArray( qMetaTypeId<MyElement>() );
            for ( int i = 0; i < myarray.length; ++i )
                argument << myarray.elements[i];
            argument.endArray();
            return argument;
        }
    \endcode

    If the type you want to marshall is a QList, QVector or any of the
    Qt's \l {containers.html}{containers} that take one template
    parameter, you need not declare an \c{operator<<} function for
    it, since QtDBus provides generic templates to do the job of
    marshalling the data. The same applies for STL's sequence
    containers, such as \c {std::list}, \c {std::vector}, etc.

    \sa endArray(), beginStructure(), beginMap()
*/
void QDBusArgument::beginArray(int id)
{
    if (d && d->checkWrite())
        d = d->marshaller()->beginArray(id);
}

/*!
    Closes a D-BUS array opened with beginArray(). This function must be called
    same number of times that beginArray() is called.

    \sa beginArray(), endStructure(), endMap()
*/
void QDBusArgument::endArray()
{
    if (d && d->checkWrite())
        d = d->marshaller()->endArray();
}

/*!
    Opens a new D-BUS map suitable for
    appending elements. Maps are containers that associate one entry
    (the key) to another (the value), such as Qt's QMap or QHash. The
    ids of the map's key and value meta types must be passed in \a kid
    and \a vid respectively.

    This function is used usually in \c{operator<<} streaming
    operators, as in the following example:

    \code
        // append a dictionary that associates ints to MyValue types
        QDBusArgument &operator<<(QDBusArgument &argument, const MyDictionary &mydict)
        {
            argument.beginMap( QVariant::Int, qMetaTypeId<MyValue>() );
            for ( int i = 0; i < mydict.length; ++i ) {
                argument.beginMapEntry();
                argument << mydict.data[i].key << mydict.data[i].value;
                argument.endMapEntry();
            }
            argument.endMap();
            return argument;
        }
    \endcode

    If the type you want to marshall is a QMap or QHash, you need not
    declare an \c{operator<<} function for it, since QtDBus provides
    generic templates to do the job of marshalling the data.

    \sa endMap(), beginStructure(), beginArray(), beginMapEntry()
*/
void QDBusArgument::beginMap(int kid, int vid)
{
    if (d && d->checkWrite())
        d = d->marshaller()->beginMap(kid, vid);
}

/*!
    Closes a D-BUS map opened with beginMap(). This function must be called
    same number of times that beginMap() is called.

    \sa beginMap(), endStructure(), endArray()
*/
void QDBusArgument::endMap()
{
    if (d && d->checkWrite())
        d = d->marshaller()->endMap();
}

/*!
    Opens a D-BUS map entry suitable for
    appending the key and value entries. This function is only valid
    when a map has been opened with beginMap().

    See beginMap() for an example of usage of this function.

    \sa endMapEntry(), beginMap()
*/
void QDBusArgument::beginMapEntry()
{
    if (d && d->checkWrite())
        d = d->marshaller()->beginMapEntry();
}

/*!
    Closes a D-BUS map entry opened with beginMapEntry(). This function must be called
    same number of times that beginMapEntry() is called.

    \sa beginMapEntry()
*/
void QDBusArgument::endMapEntry()
{
    if (d && d->checkWrite())
        d = d->marshaller()->endMapEntry();
}