Класс QDBusArgument

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

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

См. также 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 с аргументом типа QMetaType::Int. Для массива INT32 она вернёт QVariant, содержащий QDBusArgument.

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

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

bool QDBusArgument::atEnd() const

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

void QDBusArgument::beginArray(QMetaType id)

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

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

// Append an array of MyElement types
QDBusArgument &operator<<(QDBusArgument &argument, const MyArray &myArray)
{
    argument.beginArray(qMetaTypeId<MyElement>());
    for (const auto &element : myArray)
        argument << element;
    argument.endArray();
    return argument;
}

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

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

void QDBusArgument::beginMap(QMetaType keyMetaType, QMetaType valueMetaType)

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

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

// Append a dictionary that associates ints to MyValue types
QDBusArgument &operator<<(QDBusArgument &argument, const MyDictionary &myDict)
{
    argument.beginMap(QMetaType::fromType<int>(), QMetaType::fromType<MyValue>());
    MyDictionary::const_iterator i;
    for (i = myDict.cbegin(); i != myDict.cend(); ++i) {
        argument.beginMapEntry();
        argument << i.key() << i.value();
        argument.endMapEntry();
    }
    argument.endMap();
    return argument;
}

Обычно вам не нужно предоставлять функцию operator<< или operator>> для ассоциативных контейнеров, таких как QHash или std::map, так как Qt D-Bus предоставляет общие шаблоны для маршаллирования данных.

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

void QDBusArgument::beginMap() const

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

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

// Extract a MyDictionary map that associates integers to MyElement items
const QDBusArgument &operator>>(const QDBusArgument &argument, MyDictionary &myDict)
{
    argument.beginMap();
    myDict.clear();

    while (!argument.atEnd()) {
        int key;
        MyElement value;
        argument.beginMapEntry();
        argument >> key >> value;
        argument.endMapEntry();
        myDict.insert(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.

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)

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

Добавляет переданный QStringListarg в поток D-Bus, как ARRAY of STRING.

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

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

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

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

Добавляет QByteArray, заданную arg, как ARRAY of BYTE в поток 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;