Contents

• Public Types
• Public Functions
• Related Non-Members
• Detailed Description

Detailed Description

TheQDBusArgument 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 theQtDBus type system page for more information on the type system.

QDBusArgument is the central class in theQtDBus 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 theQtDBus type system:

struct MyStructure{int count;QString name;};Q_DECLARE_METATYPE(MyStructure)// Marshall the MyStructure data into a D-Bus argumentQDBusArgument&operator<<(QDBusArgument&argument,const MyStructure&mystruct){    argument.beginStructure();    argument<< mystruct.count<< mystruct.name;    argument.endStructure();return argument;}// Retrieve the MyStructure data from the D-Bus argumentconstQDBusArgument&operator>>(constQDBusArgument&argument, MyStructure&mystruct){    argument.beginStructure();    argument>> mystruct.count>> mystruct.name;    argument.endStructure();return argument;}

The type has to be registered withqDBusRegisterMetaType() before it can be used withQDBusArgument. Therefore, somewhere in your program, you should add the following code:

qDBusRegisterMetaType<MyStructure>();

Once registered, a type can be used in outgoing method calls (placed withQDBusAbstractInterface::call()), signal emissions from registered objects or in incoming calls from remote applications.

It is important to note that theoperator<< andoperator>> 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:

// Wrongly marshall the MyTime data into a D-Bus argumentQDBusArgument &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;}

In this example, both theoperator<< and theoperator>> functions may produce a different number of reads/writes. This can confuse theQtDBus type system and should be avoided.

Member Type Documentation

enum QDBusArgument::ElementType

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

This enum was introduced or modified in Qt 4.5.

See alsocurrentType().

Member Function Documentation

QDBusArgument::QDBusArgument()

Constructs an emptyQDBusArgument argument.

An emptyQDBusArgument object does not allow either reading or writing to be performed.

QDBusArgument::QDBusArgument(constQDBusArgument & other)

Constructs a copy of theotherQDBusArgument 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()

Disposes of the resources associated with thisQDBusArgument object.

QVariant QDBusArgument::asVariant() const

Returns the current argument in the form of aQVariant. Basic types will be decoded and returned in theQVariant, but for complex types, this function will return aQDBusArgument object in theQVariant. It is the caller's responsibility to decode the argument (for example, by calling asVariant() in it).

For example, if the current argument is an INT32, this function will return aQVariant with an argument of typeQVariant::Int. For an array of INT32, it will return aQVariant containing aQDBusArgument.

If an error occurs or if there are no more arguments to decode (i.e., we are at the end of the argument list), this function will return an invalidQVariant.

This function was introduced in Qt 4.5.

See alsoatEnd().

bool QDBusArgument::atEnd() const

Returns true if there are no more elements to be extracted from thisQDBusArgument. This function is usually used inQDBusArgument objects returned frombeginMap() andbeginArray().

void QDBusArgument::beginArray(int id)

Opens a new D-Bus array suitable for appending elements of meta-typeid.

This function is used usually inoperator<< streaming operators, as in the following example:

// append an array of MyElement typesQDBusArgument&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;}

If the type you want to marshall is aQList,QVector or any of the Qt'sContainer Classes that take one template parameter, you need not declare anoperator<< function for it, sinceQtDBus provides generic templates to do the job of marshalling the data. The same applies for STL's sequence containers, such asstd::list,std::vector, etc.

See alsoendArray(),beginStructure(), andbeginMap().

void QDBusArgument::beginArray() const

Recurses into the D-Bus array to allow extraction of the array elements.

This function is used usually inoperator>> streaming operators, as in the following example:

// extract a MyArray array of MyElement elementsconstQDBusArgument&operator>>(constQDBusArgument&argument, MyArray&myarray){    argument.beginArray();    myarray.clear();while (!argument.atEnd() ) {        MyElement element;        argument>> element;        myarray.append( element );    }    argument.endArray();return argument;}

If the type you want to demarshall is aQList,QVector or any of the Qt'sContainer Classes that take one template parameter, you need not declare anoperator>> function for it, sinceQtDBus provides generic templates to do the job of demarshalling the data. The same applies for STL's sequence containers, such asstd::list,std::vector, etc.

See alsoatEnd(),beginStructure(), andbeginMap().

void QDBusArgument::beginMap(int kid,int vid)

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'sQMap orQHash. The ids of the map's key and value meta types must be passed inkid andvid respectively.

This function is used usually inoperator<< streaming operators, as in the following example:

// append a dictionary that associates ints to MyValue typesQDBusArgument&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;}

If the type you want to marshall is aQMap orQHash, you need not declare anoperator<< function for it, sinceQtDBus provides generic templates to do the job of marshalling the data.

See alsoendMap(),beginStructure(),beginArray(), andbeginMapEntry().

void QDBusArgument::beginMap() const

Recurses into the D-Bus map to allow extraction of the map's elements.

This function is used usually inoperator>> streaming operators, as in the following example:

// extract a MyDictionary map that associates ints to MyValue elementsconstQDBusArgument&operator>>(constQDBusArgument&argument, MyDictionary&mydict){    argument.beginMap();    mydict.clear();while (!argMap.atEnd() ) {int key;        MyValue value;        argument.beginMapEntry();        argument>> key>> value;        argument.endMapEntry();        mydict.append( key, value );    }    argument.endMap();return argument;}

If the type you want to demarshall is aQMap orQHash, you need not declare anoperator>> function for it, sinceQtDBus provides generic templates to do the job of demarshalling the data.

See alsoendMap(),beginStructure(),beginArray(), andbeginMapEntry().

void QDBusArgument::beginMapEntry()

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 withbeginMap().

SeebeginMap() for an example of usage of this function.

See alsoendMapEntry() andbeginMap().

void QDBusArgument::beginMapEntry() const

Recurses into the D-Bus map entry to allow extraction of the key and value pair.

SeebeginMap() for an example of how this function is usually used.

See alsoendMapEntry() andbeginMap().

void QDBusArgument::beginStructure()

Opens a new D-Bus structure suitable for appending new arguments.

This function is used usually inoperator<< streaming operators, as in the following example:

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

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

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;}

See alsoendStructure(),beginArray(), andbeginMap().

void QDBusArgument::beginStructure() const

Opens a D-Bus structure suitable for extracting elements.

This function is used usually inoperator>> streaming operators, as in the following example:

constQDBusArgument&operator>>(constQDBusArgument&argument, MyStructure&mystruct){    argument.beginStructure()    argument>> mystruct.member1>> mystruct.member2>> mystruct.member3>>...;    argument.endStructure();return argument;}

See alsoendStructure(),beginArray(), andbeginMap().

ElementType QDBusArgument::currentType() const

Returns the classification of the current element type. If an error decoding the type occurs or if we're at the end of the argument, this function returnsQDBusArgument::UnknownType.

This function only makes sense when demarshalling arguments. If it is used while marshalling, it will always returnUnknownType.

This function was introduced in Qt 4.5.

void QDBusArgument::endArray()

Closes a D-Bus array opened withbeginArray(). This function must be called same number of times thatbeginArray() is called.

See alsobeginArray(),endStructure(), andendMap().

void QDBusArgument::endArray() const

Closes the D-Bus array and allow extracting of the next element after the array.

See alsobeginArray().

void QDBusArgument::endMap()

Closes a D-Bus map opened withbeginMap(). This function must be called same number of times thatbeginMap() is called.

See alsobeginMap(),endStructure(), andendArray().

void QDBusArgument::endMap() const

Closes the D-Bus map and allow extracting of the next element after the map.

See alsobeginMap().

void QDBusArgument::endMapEntry()

Closes a D-Bus map entry opened withbeginMapEntry(). This function must be called same number of times thatbeginMapEntry() is called.

See alsobeginMapEntry().

void QDBusArgument::endMapEntry() const

Closes the D-Bus map entry and allow extracting of the next element on the map.

See alsobeginMapEntry().

void QDBusArgument::endStructure()

Closes a D-Bus structure opened withbeginStructure(). This function must be called same number of times thatbeginStructure() is called.

See alsobeginStructure(),endArray(), andendMap().

void QDBusArgument::endStructure() const

Closes the D-Bus structure and allow extracting of the next element after the structure.

See alsobeginStructure().

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

Appends the primitive valuearg of typeBYTE to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeBOOLEAN to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeINT16 to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeUINT16 to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeINT32 to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeUINT32 to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeINT64 to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeUINT64 to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeDOUBLE (double-precision floating-point) to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeSTRING (Unicode character string) to the D-Bus stream.

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

This is an overloaded function.

Appends the primitive valuearg of typeVARIANT to the D-Bus stream.

A D-Bus variant type can contain any type, including other variants. It is similar to the QtQVariant type.

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

This is an overloaded function.

Appends theQStringList given byarg asARRAY of STRING to the D-Bus stream.

QStringList andQByteArray are the only two non-primitive types that are supported directly byQDBusArgument because of their widespread usage in Qt applications.

Other arrays are supported through compound types inQtDBus.

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

This is an overloaded function.

Appends theQByteArray given byarg asARRAY of BYTE to the D-Bus stream.

QStringList andQByteArray are the only two non-primitive types that are supported directly byQDBusArgument because of their widespread usage in Qt applications.

Other arrays are supported through compound types inQtDBus.

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

Copies theotherQDBusArgument 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.

constQDBusArgument & QDBusArgument::operator>>(uchar & arg) const

Extracts one D-BUS primitive argument of typeBYTE from the D-BUS stream and puts it intoarg.

constQDBusArgument & QDBusArgument::operator>>(bool & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeBOOLEAN from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(ushort & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeUINT16 from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(short & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeINT16 from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(int & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeINT32 from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(uint & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeUINT32 from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(qlonglong & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeINT64 from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(qulonglong & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeUINT64 from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(double & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeDOUBLE (double-precision floating pount) from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(QString & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeSTRING (Unicode character string) from the D-Bus stream.

constQDBusArgument & QDBusArgument::operator>>(QDBusVariant & arg) const

This is an overloaded function.

Extracts one D-Bus primitive argument of typeVARIANT from the D-Bus stream.

A D-Bus variant type can contain any type, including other variants. It is similar to the QtQVariant type.

In case the variant contains a type not directly supported byQDBusArgument, the value of the returnedQDBusVariant will contain anotherQDBusArgument. It is your responsibility to further demarshall it into another type.

constQDBusArgument & QDBusArgument::operator>>(QStringList & arg) const

This is an overloaded function.

Extracts an array of strings from the D-Bus stream and return it as aQStringList.

QStringList andQByteArray are the only two non-primitive types that are supported directly byQDBusArgument because of their widespread usage in Qt applications.

Other arrays are supported through compound types inQtDBus.

constQDBusArgument & QDBusArgument::operator>>(QByteArray & arg) const

This is an overloaded function.

Extracts an array of bytes from the D-Bus stream and return it as aQByteArray.

QStringList andQByteArray are the only two non-primitive types that are supported directly byQDBusArgument because of their widespread usage in Qt applications.

Other arrays are supported through compound types inQtDBus.

Related Non-Members

intqDBusRegisterMetaType()

RegistersT with theQtDBus type system and the Qtmeta-type system, if it's not already registered.

To register a type, it must be declared as a meta-type with theQ_DECLARE_METATYPE() macro, and then registered as in the following example:

#include <QDBusMetaType>qDBusRegisterMetaType<MyClass>();

IfT isn't a type derived from one of Qt'scontainer classes, theoperator<< andoperator>> streaming operators betweenT andQDBusArgument must be already declared. See theQtDBus type system page for more information on how to declare such types.

This function returns the Qt meta type id for the type (the same value that is returned fromqRegisterMetaType()).

Note: This function isthread-safe.

This function was introduced in Qt 4.2.

See alsoQtDBus type system,qRegisterMetaType(), andQMetaType.

Tqdbus_cast(constQDBusArgument & argument)

Attempts to demarshall the contents ofargument into the typeT. For example:

MyType item= qdbus_cast<Type>(argument);

Note that it is equivalent to the following:

MyType item;argument>> item;

This function was introduced in Qt 4.2.