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

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

перечисление 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)

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

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

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;