CopperSpice DBUS  1.7.4
QDBusArgument Class Reference

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

Public Types

enum  ElementType
 

Public Methods

 QDBusArgument ()
 
 QDBusArgument (const QDBusArgument &other)
 
 QDBusArgument (QDBusArgument &&other) noexcept
 
 ~QDBusArgument ()
 
QVariant asVariant () const
 
bool atEnd () const
 
void beginArray () const
 
void beginArray (int metaTypeId)
 

Detailed Description

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. Refer to the DBus Type System for more information.

QDBusArgument is the central class in the &CsDbus 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 &CsDbus type system.

struct MyStructure
{
int count;
QString name;
};
Q_DECLARE_METATYPE(MyStructure)
// Marshall the MyStructure data into a D-Bus argument
QDBusArgument &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 argument
const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &mystruct)
{
argument.beginStructure();
argument >> mystruct.count >> mystruct.name;
argument.endStructure();
return argument;
}
See also
QDBusAbstractInterface, qdbus_cast() (BROOM), DBus Type System, Using DBus Adaptors

Member Enumeration Documentation

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

ConstantValueDescription
QDBusArgument::BasicType 0 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
QDBusArgument::VariantType 1 The variant element (QDBusVariant)
QDBusArgument::ArrayType 2 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.
QDBusArgument::StructureType 3 A custom type represented by a structure, like QDateTime, QPoint, etc.
QDBusArgument::MapType 4 An associative container, like QMap<Key, Value> or QHash<Key, Value>
QDBusArgument::MapEntryType 5 One entry in an associative container: both the key and the value form one map-entry type.
QDBusArgument::UnknownType -1 The type is unknown or we have reached the end of the list.
See also
currentType()

Constructor & Destructor Documentation

QDBusArgument::QDBusArgument ( )

Constructs an empty QDBusArgument argument. An empty QDBusArgument object does not allow either reading or writing to be performed.

QDBusArgument::QDBusArgument ( const QDBusArgument &  other)

Copy constructs a new QDBusArgument from other.

Both objects will contain the same state from this point forward. QDBusArguments are explicitly shared so any modifications to either copy will affect the other one.

QDBusArgument::QDBusArgument ( QDBusArgument &&  other)
inlinenoexcept

Move constructs a new QDBusArgument from other.

QDBusArgument::~QDBusArgument ( )

Disposes of the resources associated with this QDBusArgument object.

Method Documentation

QVariant QDBusArgument::asVariant ( ) const

Returns the current argument in the form of a QVariant. Basic types will be decoded and returned in the QVariant, but for complex types, this function will return a QDBusArgument object in the QVariant. 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 a QVariant with an argument of type QVariant::Int. For an array of INT32, it will return a QVariant containing a QDBusArgument.

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 invalid QVariant.

See also
atEnd()
bool QDBusArgument::atEnd ( ) const

Returns true if there are no more elements to be extracted from this QDBusArgument. This method is usually used in QDBusArgument objects returned from beginMap() and beginArray().

void QDBusArgument::beginArray ( ) const

Recurses into the D-Bus array to allow extraction of the array elements. This method is used in operator>>() streaming operators, shown in the following example.

If the type you want to demarshall is a QList, QVector or another container classes you may not need to declare an operator>>() method since the CsDBus provides generic templates for demarshalling the data.

// extract a MyArray array of MyElement elements
const QDBusArgument &operator>>(const QDBusArgument &argument, MyArray &myarray)
{
argument.beginArray();
myarray.clear();
while (! argument.atEnd()) {
MyElement element;
argument >> element;
myarray.append( element );
}
argument.endArray();
return argument;
}
See also
atEnd(), beginStructure(), beginMap()
void QDBusArgument::beginArray ( int  metaTypeId)

Opens a new D-Bus array suitable for appending elements of meta-type metaTypeId. This method is used in operator<<() streaming operators, as shown in the following example.

If the type you want to marshall is a QList, QVector or another container class you may not need to declare an operator<<() function since CsDBus provides generic templates for marshalling the data.

// append an array of MyElement types
QDBusArgument &operator<<(QDBusArgument &argument, const MyArray &myArray)
{
argument.beginArray( QVariant::typeToTypeId<MyElement>() );
for (int i = 0; i < myArray.length; ++i) {
argument << myArray.elements[i];
}
argument.endArray();
return argument;
}
See also
atEnd(), beginStructure(), beginMap()