The QDBusArgument class is used to marshall and demarshall D-Bus arguments. 更多...
| 头： | #include <QDBusArgument> |
| qmake: | QT += dbus |
| Since: | Qt 4.2 |
| enum | ElementType { BasicType, VariantType, ArrayType, StructureType, ..., UnknownType } |
| QDBusArgument () | |
| QDBusArgument (const QDBusArgument & other ) | |
| QDBusArgument (QDBusArgument && other ) | |
| ~QDBusArgument () | |
| QVariant | asVariant () const |
| bool | atEnd () const |
| void | beginArray (int id ) |
| void | beginArray () const |
| void | beginMap (int kid , int vid ) |
| void | beginMap () const |
| void | beginMapEntry () |
| void | beginMapEntry () const |
| void | beginStructure () |
| void | beginStructure () const |
| QDBusArgument::ElementType | currentType () const |
| void | endArray () |
| void | endArray () const |
| void | endMap () |
| void | endMap () const |
| void | endMapEntry () |
| void | endMapEntry () const |
| void | endStructure () |
| void | endStructure () const |
| void | swap (QDBusArgument & other ) |
| QDBusArgument & | operator<< (uchar arg ) |
| QDBusArgument & | operator<< (bool arg ) |
| QDBusArgument & | operator<< (short arg ) |
| QDBusArgument & | operator<< (ushort arg ) |
| QDBusArgument & | operator<< (int arg ) |
| QDBusArgument & | operator<< (uint arg ) |
| QDBusArgument & | operator<< (qlonglong arg ) |
| QDBusArgument & | operator<< (qulonglong arg ) |
| QDBusArgument & | operator<< (double arg ) |
| QDBusArgument & | operator<< (const QString & arg ) |
| QDBusArgument & | operator<< (const QDBusVariant & arg ) |
| QDBusArgument & | operator<< (const QStringList & arg ) |
| QDBusArgument & | operator<< (const QByteArray & arg ) |
| QDBusArgument & | operator= (QDBusArgument && other ) |
| QDBusArgument & | operator= (const QDBusArgument & other ) |
| const QDBusArgument & | operator>> (uchar & arg ) const |
| const QDBusArgument & | operator>> (bool & arg ) const |
| const QDBusArgument & | operator>> (short & arg ) const |
| const QDBusArgument & | operator>> (ushort & arg ) const |
| const QDBusArgument & | operator>> (int & arg ) const |
| const QDBusArgument & | operator>> (uint & arg ) const |
| const QDBusArgument & | operator>> (qlonglong & arg ) const |
| const QDBusArgument & | operator>> (qulonglong & arg ) const |
| const QDBusArgument & | operator>> (double & arg ) const |
| const QDBusArgument & | operator>> (QString & arg ) const |
| const QDBusArgument & | operator>> (QDBusVariant & arg ) const |
| const QDBusArgument & | operator>> (QStringList & arg ) const |
| const QDBusArgument & | operator>> (QByteArray & arg ) const |
| QDBusArgumentPrivate * | d |
| int | qDBusRegisterMetaType () |
| T | qdbus_cast (const QDBusArgument & arg ) |
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 Qt D-Bus Type System page for more information on the type system.
QDBusArgument is the central class in the Qt D-Bus 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 Qt D-Bus 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; }
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:
qDBusRegisterMetaType<MyStructure>();
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
operator<<
and
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:
//bad code // 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; }
In this example, both the
operator<<
和
operator>>
functions may produce a different number of reads/writes. This can confuse the Qt D-Bus type system and should be avoided.
另请参阅 QDBusAbstractInterface , The Qt D-Bus type system , Using Adaptors ，和 qdbus_cast ().
This enum describes the type of element held by the argument.
| 常量 | 值 | 描述 |
|---|---|---|
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 ，等。 |
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. |
该枚举在 Qt 4.5 引入或被修改。
另请参阅 currentType ().
构造空的 QDBusArgument 自变量。
空 QDBusArgument object does not allow either reading or writing to be performed.
构造副本为 other QDBusArgument 对象。
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.
移动拷贝构造函数。
Disposes of the resources associated with this QDBusArgument 对象。
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 包含 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 .
该函数在 Qt 4.5 引入。
另请参阅 atEnd ().
返回
true
if there are no more elements to be extracted from this
QDBusArgument
. This function is usually used in
QDBusArgument
objects returned from
beginMap
() 和
beginArray
().
Opens a new D-Bus array suitable for appending elements of meta-type id .
This function is used usually in
operator<<
streaming operators, as in the following example:
// 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; }
If the type you want to marshall is a
QList
,
QVector
or any of the Qt's
容器类
that take one template parameter, you need not declare an
operator<<
function for it, since Qt D-Bus provides generic templates to do the job of marshalling the data. The same applies for STL's sequence containers, such as
std::list
,
std::vector
，等。
另请参阅 endArray (), beginStructure ()，和 beginMap ().
Recurses into the D-Bus array to allow extraction of the array elements.
This function is used usually in
operator>>
streaming operators, as in the following example:
// 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; }
If the type you want to demarshall is a
QList
,
QVector
or any of the Qt's
容器类
that take one template parameter, you need not declare an
operator>>
function for it, since Qt D-Bus provides generic templates to do the job of demarshalling the data. The same applies for STL's sequence containers, such as
std::list
,
std::vector
，等。
另请参阅 atEnd (), beginStructure ()，和 beginMap ().
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 kid and vid 分别。
This function is used usually in
operator<<
streaming operators, as in the following example:
// 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; }
If the type you want to marshall is a
QMap
or
QHash
, you need not declare an
operator<<
function for it, since Qt D-Bus provides generic templates to do the job of marshalling the data.
另请参阅 endMap (), beginStructure (), beginArray ()，和 beginMapEntry ().
Recurses into the D-Bus map to allow extraction of the map's elements.
This function is used usually in
operator>>
streaming operators, as in the following example:
// extract a MyDictionary map that associates ints to MyValue elements const QDBusArgument &operator>>(const QDBusArgument &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 a
QMap
or
QHash
, you need not declare an
operator>>
function for it, since Qt D-Bus provides generic templates to do the job of demarshalling the data.
另请参阅 endMap (), beginStructure (), beginArray ()，和 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 with beginMap ().
见 beginMap () for an example of usage of this function.
另请参阅 endMapEntry () 和 beginMap ().
Recurses into the D-Bus map entry to allow extraction of the key and value pair.
见 beginMap () for an example of how this function is usually used.
另请参阅 endMapEntry () 和 beginMap ().
Opens a new D-Bus structure suitable for appending new arguments.
This function is used usually in
operator<<
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; }
另请参阅 endStructure (), beginArray ()，和 beginMap ().
Opens a D-Bus structure suitable for extracting elements.
This function is used usually in
operator>>
streaming operators, as in the following example:
const QDBusArgument &operator>>(const QDBusArgument &argument, MyStructure &mystruct) { argument.beginStructure() argument >> mystruct.member1 >> mystruct.member2 >> mystruct.member3 >> ...; argument.endStructure(); return argument; }
另请参阅 endStructure (), beginArray ()，和 beginMap ().
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 returns QDBusArgument::UnknownType .
This function only makes sense when demarshalling arguments. If it is used while marshalling, it will always return UnknownType .
该函数在 Qt 4.5 引入。
Closes a D-Bus array opened with beginArray (). This function must be called same number of times that beginArray () 被调用。
另请参阅 beginArray (), endStructure ()，和 endMap ().
Closes the D-Bus array and allow extracting of the next element after the array.
另请参阅 beginArray ().
Closes a D-Bus map opened with beginMap (). This function must be called same number of times that beginMap () 被调用。
另请参阅 beginMap (), endStructure ()，和 endArray ().
Closes the D-Bus map and allow extracting of the next element after the map.
另请参阅 beginMap ().
Closes a D-Bus map entry opened with beginMapEntry (). This function must be called same number of times that beginMapEntry () 被调用。
另请参阅 beginMapEntry ().
Closes the D-Bus map entry and allow extracting of the next element on the map.
另请参阅 beginMapEntry ().
Closes a D-Bus structure opened with beginStructure (). This function must be called same number of times that beginStructure () 被调用。
另请参阅 beginStructure (), endArray ()，和 endMap ().
Closes the D-Bus structure and allow extracting of the next element after the structure.
另请参阅 beginStructure ().
交换此 QDBusArgument 实例与 other .
Appends the primitive value
arg
类型
BYTE
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
BOOLEAN
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
INT16
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
UINT16
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
INT32
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
UINT32
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
INT64
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
UINT64
to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
DOUBLE
(double-precision floating-point) to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
STRING
(Unicode character string) to the D-Bus stream.
这是重载函数。
Appends the primitive value
arg
类型
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 类型。
这是重载函数。
追加
QStringList
given by
arg
as
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 Qt D-Bus.
这是重载函数。
追加
QByteArray
given by
arg
as
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 Qt D-Bus.
移动赋值运算符。
拷贝 other QDBusArgument 对象到此对象。
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.
Extracts one D-BUS primitive argument of type
BYTE
from the D-BUS stream and puts it into
arg
.
这是重载函数。
Extracts one D-Bus primitive argument of type
BOOLEAN
from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
INT16
from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
UINT16
from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
INT32
from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
UINT32
from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
INT64
from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
UINT64
from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
DOUBLE
(double-precision floating pount) from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
STRING
(Unicode character string) from the D-Bus stream.
这是重载函数。
Extracts one D-Bus primitive argument of type
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 类型。
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.
这是重载函数。
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 Qt D-Bus.
这是重载函数。
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 Qt D-Bus.
注册
T
采用
Qt D-Bus Type System
and the Qt
meta-type system
, if it's not already registered.
To register a type, it must be declared as a meta-type with the Q_DECLARE_METATYPE () macro, and then registered as in the following example:
#include <QDBusMetaType> qDBusRegisterMetaType<MyClass>();
若
T
isn't one of Qt's
容器类
，
operator<<
and
operator>>
streaming operators between
T
and
QDBusArgument
must be already declared. See the
Qt D-Bus 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 from qRegisterMetaType ()).
注意：
The feature that a
T
inheriting a streamable type (including the containers
QList
,
QHash
or
QMap
) can be streamed without providing custom
operator<<
and
operator>>
is deprecated as of Qt 5.7, because it ignores everything in
T
except the base class. There is no diagnostic. You should always provide these operators for all types you wish to stream and not rely on Qt-provided stream operators for base classes.
注意： 此函数是 thread-safe .
该函数在 Qt 4.2 引入。
另请参阅 Qt D-Bus Type System , qRegisterMetaType ()，和 QMetaType .
Attempts to demarshall the contents of
arg
into the type
T
。例如：
MyType item = qdbus_cast<Type>(argument);
Note that it is equivalent to the following:
MyType item; argument >> item;
该函数在 Qt 4.2 引入。
