Класс QDBusArgument

Класс QDBusArgument используется для маршалинга и демаршалинга аргументов D-Bus. Подробнее...

Этот класс был введён в Qt 4.2.

• Список всех членов, включая унаследованные члены

Открытые типы

Открытые функции

Связанные внешние функции

Подробное описание

Класс используется для отправки аргументов по D-Bus в удалённые приложения и для получения их обратно. D-Bus предлагает расширяемую систему типов, основанную на нескольких примитивных типах и их ассоциациях. Для получения дополнительной информации о системе типов см. страницу Система типов Qt D-Bus.

QDBusArgument — центральный класс в системе типов Qt D-Bus, предоставляющий функции для маршаллирования и демаршаллирования примитивных типов. Составные типы затем создаются путём объединения одного или нескольких примитивных типов в массивы, словари или структуры.

Следующий пример иллюстрирует, как можно создать структуру, содержащую целое число и строку, с использованием системы типов Qt D-Bus:

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

Тип необходимо зарегистрировать с помощью qDBusRegisterMetaType() перед его использованием с QDBusArgument. Поэтому где-то в вашей программе вы должны добавить следующий код:

qDBusRegisterMetaType<MyStructure>();

После регистрации тип можно использовать в исходящих вызовах методов (размещая с помощью QDBusAbstractInterface::call()), при отправке сигналов из зарегистрированных объектов или в входящих вызовах из удалённых приложений.

Важно отметить, что функции потоковой обработки operator<< и operator>> всегда должны генерировать одинаковое количество элементов в случае структур, как при чтении, так и при записи (маршаллировании и демаршаллировании), иначе вызовы и сигналы могут начать молчаливо завершаться ошибкой.

Следующий пример иллюстрирует эту неправильную практику в контексте класса, который может содержать некорректные данные:

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

В этом примере и функция operator<<, и функция operator>> могут генерировать разное количество чтений/записей. Это может сбить с толку систему типов Qt D-Bus и следует избегать.

См. также QDBusAbstractInterface, систему типов Qt D-Bus, Использование адаптеров и qdbus_cast().

Документация по типам членов

enum QDBusArgument::ElementType

Это перечисление описывает тип элемента, хранимого аргументом.

Это перечисление было введено или изменено в Qt 4.5.

См. также currentType().

Документация по функциям-членам

QDBusArgument::QDBusArgument(const QDBusArgument &other)

Создаёт копию объекта QDBusArgument other.

Оба объекта, следовательно, будут содержать одинаковое состояние с этого момента. QDBusArgument явно объединены, и поэтому любое изменение в одной копии повлияет на другую.

QDBusArgument::QDBusArgument()

Создаёт пустой аргумент QDBusArgument.

Пустой объект QDBusArgument не позволяет выполнять чтение или запись.

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

Копирует объект QDBusArgument other в текущий.

Оба объекта, следовательно, будут содержать одинаковое состояние с этого момента. QDBusArgument явно объединены, и поэтому любое изменение в одной копии повлияет на другую.

QDBusArgument::~QDBusArgument()

Освобождает ресурсы, связанные с этим объектом QDBusArgument.

QVariant QDBusArgument::asVariant() const

Возвращает текущий аргумент в виде QVariant. Базовые типы будут декодированы и возвращены в QVariant, но для сложных типов эта функция вернёт объект QDBusArgument в QVariant. Ответственность за декодирование аргумента (например, путём вызова asVariant() в нём) лежит на вызывающей стороне.

Например, если текущий аргумент — INT32, эта функция вернёт QVariant с аргументом типа QVariant::Int. Для массива INT32 она вернёт QVariant, содержащий QDBusArgument.

В случае ошибки или если больше нет аргументов для декодирования (т.е., мы достигли конца списка аргументов), эта функция вернёт недействительный QVariant.

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

См. также atEnd().

bool QDBusArgument::atEnd() const

Возвращает true, если больше нет элементов для извлечения из QDBusArgument. Эта функция обычно используется в объектах QDBusArgument, возвращаемых из beginMap() и beginArray().

void QDBusArgument::beginArray(int id)

Открывает новый массив D-Bus, подходящий для добавления элементов метатипа id.

Эта функция обычно используется в операторах потоковой обработки, как в следующем примере:

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

Если тип, который вы хотите маршаллировать, это QList, QVector или любой из контейнеров Qt, принимающих один шаблонный параметр, вам не нужно объявлять функцию, так как Qt D-Bus предоставляет универсальные шаблоны для обработки маршаллирования данных. То же самое относится к контейнерам последовательностей STL, таким как QList, QVector и т. д.

См. также endArray(), beginStructure() и beginMap().

void QDBusArgument::beginArray() const

Возвращается в массив D-Bus, чтобы разрешить извлечение элементов массива.

Эта функция обычно используется в операторах потоковой обработки, как в следующем примере:

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

Если тип, который вы хотите демаршаллировать, это QList, QVector или любой из контейнеров Qt, принимающих один шаблонный параметр, вам не нужно объявлять функцию, так как Qt D-Bus предоставляет универсальные шаблоны для обработки демаршаллирования данных. То же самое относится к контейнерам последовательностей STL, таким как QList, QVector и т. д.

См. также atEnd(), beginStructure() и beginMap().

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

Открывает новую карту D-Bus, подходящую для добавления элементов. Карты — это контейнеры, которые связывают один элемент (ключ) с другим (значение), например, Qt QMap или QHash. Идентификаторы метатипов ключа и значения карты должны быть переданы в kid и vid соответственно.

Эта функция обычно используется в операторах потоковой обработки, как в следующем примере:

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

Если тип, который вы хотите маршаллировать, это QMap или QHash, вам не нужно объявлять функцию для него, так как Qt D-Bus предоставляет универсальные шаблоны для обработки маршаллирования данных.

См. также endMap(), beginStructure(), beginArray() и beginMapEntry().

void QDBusArgument::beginMap() const

Возвращается в карту D-Bus, чтобы разрешить извлечение элементов карты.

Эта функция обычно используется в операторах потоковой обработки, как в следующем примере:

// extract a MyDictionary map that associates ints to MyValue elements
const QDBusArgument &operator>>(const QDBusArgument &argument, MyDictionary &mydict)
{
    argument.beginMap();
    mydict.clear();

    while ( !argument.atEnd() ) {
        int key;
        MyValue value;
        argument.beginMapEntry();
        argument >> key >> value;
        argument.endMapEntry();
        mydict.append( key, value );
    }

    argument.endMap();
    return argument;
}

Если тип, который вы хотите демаршаллировать, это QMap или QHash, вам не нужно объявлять функцию для него, так как Qt D-Bus предоставляет универсальные шаблоны для обработки демаршаллирования данных.

См. также endMap(), beginStructure(), beginArray() и beginMapEntry().

void QDBusArgument::beginMapEntry()

Открывает запись в карте D-Bus, подходящую для добавления ключа и значения. Данная функция допустима только при открытой карте с помощью beginMap().

См. beginMap() для примера использования этой функции.

См. также endMapEntry() и beginMap().

void QDBusArgument::beginMapEntry() const

Рекурсивно входит в запись карты D-Bus, чтобы получить пару ключ-значение.

См. beginMap() для примера типичного использования этой функции.

См. также endMapEntry() и beginMap().

void QDBusArgument::beginStructure()

Открывает новую структуру D-Bus, подходящую для добавления новых аргументов.

Эта функция обычно используется в operator<< операторах потоковой передачи, как в следующем примере:

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

Структуры могут содержать другие структуры, поэтому следующий код также корректен:

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

void QDBusArgument::beginStructure() const

Открывает структуру D-Bus, подходящую для извлечения элементов.

Эта функция обычно используется в operator>> операторах потоковой передачи, как в следующем примере:

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

См. также endStructure(), beginArray() и beginMap().

QDBusArgument::ElementType QDBusArgument::currentType() const

Возвращает классификацию текущего типа элемента. Если произошла ошибка при декодировании типа или мы достигли конца аргумента, эта функция возвращает QDBusArgument::UnknownType.

Эта функция имеет смысл только при разборке аргументов. Если она используется при сборке, она всегда вернёт UnknownType.

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

void QDBusArgument::endArray()

Закрывает массив D-Bus, открытый с помощью beginArray(). Эта функция должна вызываться столько же раз, сколько и beginArray().

См. также beginArray(), endStructure() и endMap().

void QDBusArgument::endArray() const

Закрывает массив D-Bus и позволяет извлечь следующий элемент после массива.

См. также beginArray().

void QDBusArgument::endMap()

Закрывает карту D-Bus, открытую с помощью beginMap(). Эта функция должна вызываться столько же раз, сколько и beginMap().

См. также beginMap(), endStructure() и endArray().

void QDBusArgument::endMap() const

Закрывает карту D-Bus и позволяет извлечь следующий элемент после карты.

См. также beginMap().

void QDBusArgument::endMapEntry()

Закрывает запись в карте D-Bus, открытую с помощью beginMapEntry(). Эта функция должна вызываться столько же раз, сколько и beginMapEntry().

См. также beginMapEntry().

void QDBusArgument::endMapEntry() const

Закрывает запись в карте D-Bus и позволяет извлечь следующий элемент в карте.

См. также beginMapEntry().

void QDBusArgument::endStructure()

Закрывает структуру D-Bus, открытую с помощью beginStructure(). Эта функция должна вызываться столько же раз, сколько и beginStructure().

См. также beginStructure(), endArray() и endMap().

void QDBusArgument::endStructure() const

Закрывает структуру D-Bus и позволяет извлечь следующий элемент после структуры.

См. также beginStructure().

void QDBusArgument::swap(QDBusArgument &other)

Меняет местами этот экземпляр QDBusArgument с other.

QDBusArgument &QDBusArgument::operator<<(const QStringList &arg)

Это перегруженная функция.

Добавляет QStringList, заданную arg, в поток D-Bus в качестве списка строк.

QStringList и QByteArray — единственные два не примитивных типа, которые напрямую поддерживаются QDBusArgument из-за их широкого использования в приложениях Qt.

Другие массивы поддерживаются через составные типы в Qt D-Bus.

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

Добавляет примитивное значение arg типа беззнакового 8-битного целого числа в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа булево в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа 16-битного целого числа в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа беззнакового 16-битного целого числа в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа 32-битного целого числа в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа беззнакового 32-битного целого числа в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа 64-битного целого числа в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа беззнакового 64-битного целого числа в поток D-Bus.

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

Это перегруженная функция.

Добавляет примитивное значение arg типа числа с плавающей точкой двойной точности в поток D-Bus.

QDBusArgument &QDBusArgument::operator<<(const QString &arg)

Это перегруженная функция.

Добавляет примитивное значение arg типа строки Юникода в поток D-Bus.

QDBusArgument &QDBusArgument::operator<<(const QDBusVariant &arg)

Это перегруженная функция.

Добавляет примитивное значение arg типа D-Bus-варианта в поток D-Bus.

Тип D-Bus-варианта может содержать любой тип, включая и другие варианты. Он похож на тип Qt QVariant.

QDBusArgument &QDBusArgument::operator<<(const QByteArray &arg)

Это перегруженный метод.

Добавляет QByteArray, заданный параметром arg, в поток D-Bus.

QStringList и QByteArray — единственные два не-примитивных типа, которые напрямую поддерживаются QDBusArgument из-за их широкого использования в приложениях Qt.

Другие массивы поддерживаются через составные типы в Qt D-Bus.

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

Это перегруженный метод.

Извлекает массив строк из потока D-Bus и возвращает его как QStringList.

QStringList и QByteArray — единственные два не-примитивных типа, которые напрямую поддерживаются QDBusArgument из-за их широкого использования в приложениях Qt.

Другие массивы поддерживаются через составные типы в Qt D-Bus.

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

Извлекает один примитивный аргумент D-BUS типа BYTE из потока D-BUS и помещает его в arg.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа BOOLEAN из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа INT16 из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа UINT16 из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа INT32 из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа UINT32 из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа INT64 из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа UINT64 из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа DOUBLE (вещественный тип двойной точности) из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа STRING (строка Юникод) из потока D-Bus.

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

Это перегруженный метод.

Извлекает один примитивный аргумент D-Bus типа VARIANT из потока D-Bus.

Тип варианта D-Bus может содержать любой тип, включая другие варианты. Он похож на тип Qt QVariant.

В случае, если вариант содержит тип, который не поддерживается напрямую QDBusArgument, значение возвращаемого QDBusVariant будет содержать другой QDBusArgument. Вам необходимо самостоятельно его извлечь в другой тип.

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

Это перегруженный метод.

Извлекает массив байтов из потока D-Bus и возвращает его как QByteArray.

QStringList и QByteArray — единственные два не-примитивных типа, которые напрямую поддерживаются QDBusArgument из-за их широкого использования в приложениях Qt.

Другие массивы поддерживаются через составные типы в Qt D-Bus.

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

MyType item = qdbus_cast<Type>(argument);

MyType item;
argument >> item;