Класс QDBusArgument

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

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

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

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

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

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

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

Класс используется для отправки аргументов через 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()

Конструирует пустой аргумент QDBusArgument.

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

QDBusArgument::QDBusArgument(const QDBusArgument &other)

Конструирует копию объекта QDBusArgument other.

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

QDBusArgument::QDBusArgument(QDBusArgument &&other)

Конструктор копирования перемещения.

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.

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

// 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, принимающих один шаблонный параметр, вам не нужно объявлять функцию operator<<, так как Qt D-Bus предоставляет универсальные шаблоны для обработки данных маршалинга. То же самое относится к контейнерам последовательностей STL, таким как std::list, std::vector, и т. д.

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

void QDBusArgument::beginArray() const

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

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

// 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, принимающих один шаблонный параметр, вам не нужно объявлять функцию operator>>, так как Qt D-Bus предоставляет универсальные шаблоны для обработки данных демаршалинга. То же самое относится к контейнерам последовательностей STL, таким как std::list, std::vector, и т. д.

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

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

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

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

// 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, вам не нужно объявлять функцию operator<<, так как Qt D-Bus предоставляет универсальные шаблоны для обработки данных маршалинга.

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

void QDBusArgument::beginMap() const

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

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

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

Если тип, который вы хотите размаршалить, — это QMap или QHash, вам не нужно объявлять функцию operator>>, так как 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().

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 &QDBusArgument::operator<<(uchar arg)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добавляет QStringList, заданный arg, в виде ARRAY of STRING в поток D-Bus.

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

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

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

Это перегруженный функцией.

Добавляет QByteArray, заданный arg, в качестве ARRAY of BYTE в поток D-Bus.

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

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

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

Оператор перемещающей присваивания.

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

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

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

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

Это перегруженный функцией.

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

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

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

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;