Класс 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 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().

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<<(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 QString &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;