Qt:Документация 4.3.2/qdbusargument

Материал из Wiki.crossplatform.ru

Перейти к: навигация, поиск
40px Внимание: Актуальная версия перевода документации находится здесь

__NOTOC__

Image:qt-logo.png

Главная · Все классы · Основные классы · Классы по группам · Модули · Функции

Image:trolltech-logo.png

Содержание

[править] QDBusArgument Class Reference
[ QtDBus module]

The QDBusArgument class is used to marshall and demarshall D-BUS arguments. Далее... 

 #include <QDBusArgument>

Класс был добавлен в Qt 4.2.

[править] Открытые функции

[править] Связанные не-члены

[править] Подробное описание

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 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 QtDBus type system: 

 struct MyStructure
 {
     int count;
     QString name;
 };
 QT_DECLARE_METATYPE(MyStructure)
 
 // Marshall the MyStructure data into a D-BUS argument
 QDBusArgument &amp;operator<<(QDBusArgument &amp;argument, const MyStructure &amp;mystruct)
 {
     argument.beginStructure();
     argument << mystruct.count << mystruct.name;
     argument.endStructure();
     return argument;
 }
 
 // Retrieve the MyStructure data from the D-BUS argument
 const QDBusArgument &amp;operator>>(const QDBusArgument &amp;argument, MyStructure &amp;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: 

 // Wrongly marshall the MyTime data into a D-BUS argument
 QDBusArgument &amp;operator<<(QDBusArgument &amp;argument, const MyTime &amp;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<< and the operator>> functions may produce a different number of reads/writes. This can confuse the QtDBus type system and should be avoided.

See also QDBusAbstractInterface, The QtDBus type system, Using Adaptors, and qdbus_cast().

[править] Описание функций-членов

[править]
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 )

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

Disposes of the resources associated with this QDBusArgument object.

[править]
bool QDBusArgument::atEnd () const

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

[править]
void QDBusArgument::beginArray ( int id )

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 &amp;operator<<(QDBusArgument &amp;argument, const MyArray &amp;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 Generic Containers that take one template parameter, you need not declare an 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 std::list, std::vector, etc.

See also endArray(), beginStructure(), and beginMap().

[править]
void QDBusArgument::beginArray () const

Эта перегруженная функция предоставлена для удобства.

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 &amp;operator>>(const QDBusArgument &amp;argument, MyArray &amp;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 Generic Containers that take one template parameter, you need not declare an operator>> function for it, since QtDBus 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, etc.

See also atEnd(), beginStructure(), and beginMap().

[править]
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's QMap or QHash. The ids of the map's key and value meta types must be passed in kid and vid respectively.

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

 // append a dictionary that associates ints to MyValue types
 QDBusArgument &amp;operator<<(QDBusArgument &amp;argument, const MyDictionary &amp;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 QtDBus provides generic templates to do the job of marshalling the data.

See also endMap(), beginStructure(), beginArray(), and beginMapEntry().

[править]
void QDBusArgument::beginMap () const

Эта перегруженная функция предоставлена для удобства.

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 &amp;operator>>(const QDBusArgument &amp;argument, MyDictionary &amp;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 QtDBus provides generic templates to do the job of demarshalling the data.

See also endMap(), beginStructure(), beginArray(), and beginMapEntry().

[править]
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 with beginMap().

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

See also endMapEntry() and beginMap().

[править]
void QDBusArgument::beginMapEntry () const

Эта перегруженная функция предоставлена для удобства.

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

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

See also endMapEntry() and beginMap().

[править]
void QDBusArgument::beginStructure ()

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 &amp;operator<<(QDBusArgument &amp;argument, const MyStructure &amp;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 &amp;operator<<(QDBusArgument &amp;argument, const MyStructure &amp;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 also endStructure(), beginArray(), and beginMap().

[править]
void QDBusArgument::beginStructure () const

Эта перегруженная функция предоставлена для удобства.

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 &amp;operator>>(const QDBusArgument &amp;argument, MyStructure &amp;mystruct)
 {
     argument.beginStructure()
     argument >> mystruct.member1 >> mystruct.member2 >> mystruct.member3 >> ...;
     argument.endStructure();
     return argument;
 }

See also endStructure(), beginArray(), and beginMap().

[править]
void QDBusArgument::endArray ()

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

See also beginArray(), endStructure(), and endMap().

[править]
void QDBusArgument::endArray () const

Эта перегруженная функция предоставлена для удобства.

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

See also beginArray().

[править]
void QDBusArgument::endMap ()

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

See also beginMap(), endStructure(), and endArray().

[править]
void QDBusArgument::endMap () const

Эта перегруженная функция предоставлена для удобства.

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

See also beginMap().

[править]
void QDBusArgument::endMapEntry ()

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

See also beginMapEntry().

[править]
void QDBusArgument::endMapEntry () const

Эта перегруженная функция предоставлена для удобства.

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

See also beginMapEntry().

[править]
void QDBusArgument::endStructure ()

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

See also beginStructure(), endArray(), and endMap().

[править]
void QDBusArgument::endStructure () const

Эта перегруженная функция предоставлена для удобства.

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

See also beginStructure().

[править]
QDBusArgument & QDBusArgument::operator<< ( uchar arg )

Appends the primitive value arg of type BYTE to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( bool arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type BOOLEAN to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( short arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type INT16 to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( ushort arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type UINT16 to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( int arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type INT32 to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( uint arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type UINT32 to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( qlonglong arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type INT64 to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( qulonglong arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type UINT64 to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( double arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type DOUBLE (double-precision floating-point) to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( const QString & arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type STRING (Unicode character string) to the D-BUS stream.

[править]
QDBusArgument & QDBusArgument::operator<< ( const QDBusVariant & arg )

Эта перегруженная функция предоставлена для удобства.

Appends the primitive value arg of type 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 QStringList & arg )

Эта перегруженная функция предоставлена для удобства.

Appends the 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 QtDBus.

[править]
QDBusArgument & QDBusArgument::operator<< ( const QByteArray & arg )

Эта перегруженная функция предоставлена для удобства.

Appends the 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 QtDBus.

[править]
QDBusArgument & QDBusArgument::operator= ( const QDBusArgument & other )

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

[править]
const QDBusArgument & QDBusArgument::operator>> ( uchar & arg ) const

Extracts one D-BUS primitive argument of type BYTE from the D-BUS stream and puts it into arg.

[править]
const QDBusArgument & QDBusArgument::operator>> ( bool & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type BOOLEAN from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( ushort & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type UINT16 from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( short & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type INT16 from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( int & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type INT32 from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( uint & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type UINT32 from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( qlonglong & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type INT64 from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( qulonglong & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type UINT64 from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( double & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type DOUBLE (double-precision floating pount) from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( QString & arg ) const

Эта перегруженная функция предоставлена для удобства.

Extracts one D-BUS primitive argument of type STRING (Unicode character string) from the D-BUS stream.

[править]
const QDBusArgument & QDBusArgument::operator>> ( QDBusVariant & arg ) const

Эта перегруженная функция предоставлена для удобства.

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 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>> ( QStringList & arg ) const

Эта перегруженная функция предоставлена для удобства.

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>> ( QByteArray & arg ) const

Эта перегруженная функция предоставлена для удобства.

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.

[править] Связанные не-члены

[править]
int qDBusRegisterMetaType ()

Registers T with the QtDBus 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: 

 qDBusRegisterMetaType<MyClass>();

If T isn't a type derived from one of Qt's container classes, the operator<< and operator>> streaming operators between T and QDBusArgument must be already declared. See the QtDBus 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()).

Примечание: эта функция потокобезопасна.

Эта функция была введена в Qt 4.2.

See also QtDBus type system, qRegisterMetaType(), and QMetaType.

[править]
T qdbus_cast ( const QDBusArgument & argument )

Attempts to demarshall the contents of argument 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.


Copyright © 2007 Trolltech Trademarks
Qt 4.3.2
Источник — «http://wiki.crossplatform.ru/index.php?title=Qt:%D0%94%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%86%D0%B8%D1%8F_4.3.2/qdbusargument»