Класс QCborStreamWriter

Класс QCborStreamWriter — это простой кодировщик CBOR, работающий с односторонним потоком. Подробнее...

Этот класс был представлен в Qt 5.12.

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

Примечание: Все функции в этом классе являются взаимоисключающими.

Публичные функции

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

Этот класс можно использовать для быстрого кодирования потока CBOR-содержимого непосредственно в QByteArray или QIODevice. CBOR — это компактное двоичное представление объектов, очень компактная форма двоичной кодировки данных, совместимая с JSON. Она была создана рабочей группой IETF Constrained RESTful Environments (CoRE), которая использовала ее во многих новых RFC. Она предназначена для использования вместе с протоколом CoAP.

QCborStreamWriter предоставляет API, подобный StAX, аналогичный QXmlStreamWriter. Он довольно низкоуровневый и требует определённых знаний о кодировании CBOR. Для более простого API см. QCborValue и особенно функцию кодирования QCborValue::toCbor().

Типичное использование QCborStreamWriter заключается в создании объекта на целевом QByteArray или QIODevice, а затем вызове одного из перегруженных append() для кодирования нужного типа. Для создания массивов и словарей QCborStreamWriter предоставляет перегрузки startArray() и startMap(), которые должны быть завершены соответствующими функциями endArray() и endMap().

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

{ "label": "journald", "autoDetect": false, "condition": "libs.journald", "output": [ "privateFeature" ] }

   writer.startMap(4);    // 4 elements in the map

   writer.append(QLatin1String("label"));
   writer.append(QLatin1String("journald"));

   writer.append(QLatin1String("autoDetect"));
   writer.append(false);

   writer.append(QLatin1String("condition"));
   writer.append(QLatin1String("libs.journald"));

   writer.append(QLatin1String("output"));
   writer.startArray(1);
   writer.append(QLatin1String("privateFeature"));
   writer.endArray();

   writer.endMap();

Поддержка CBOR

QCborStreamWriter поддерживает все возможности CBOR, необходимые для создания канонических и строгих потоков. Он реализует почти все функции, указанные в RFC 7049.

В следующей таблице перечислены поддерживаемые QCborStreamWriter возможности CBOR.

Каноническое кодирование CBOR

Каноническое кодирование CBOR определяется разделом 3.9 RFC 7049. Каноническое кодирование не является требованием для функциональности декодирования CBOR в Qt, но оно может потребоваться для некоторых протоколов. В частности, протоколы, которые требуют возможности идентичного воспроизведения одного и того же потока, могут потребовать этого.

Для того, чтобы считаться "каноническим", поток CBOR должен соответствовать следующим требованиям:

• Целые числа должны быть минимальными. QCborStreamWriter всегда делает это (нет необходимости в действиях пользователя, и невозможно записать длинные целые числа).
• Длины массивов, словарей и строк должны быть минимальными. Как и выше, QCborStreamWriter автоматически делает это.
• Массивы, словари и строки должны использовать явную длину. QCborStreamWriter всегда делает это для строк; для массивов и словарей, убедитесь, что вы используете перегрузки startArray() и startMap() с явной длиной.
• Ключи в каждом словаре должны быть отсортированы в порядке возрастания. QCborStreamWriter не предлагает никакой помощи в этом пункте: разработчик должен убедиться, что перед вызовом append() для пар словаря.
• Значения с плавающей точкой должны быть минимальными. QCborStreamWriter не будет преобразовывать значения с плавающей точкой; разработчик должен самостоятельно выполнить эту проверку перед вызовом append() (см. примеры этих функций).

Строгий режим CBOR

Режим строгости определяется разделом 3.10 RFC 7049. Что касается канонического кодирования выше, QCborStreamWriter позволяет создавать строгие потоки CBOR, но не требует их и не проверяет, является ли вывод таковым.

• Ключи в массиве должны быть уникальными. QCborStreamWriter не выполняет проверку ключей словаря.
• Теги могут быть обязательными только для правильных типов в соответствии с их спецификацией. QCborStreamWriter не выполняет проверку использования тегов.
• Строки текста должны быть правильно закодированы в UTF-8. QCborStreamWriter всегда записывает правильный UTF-8 для строк, добавленных с помощью append(), но не выполняет проверку для строк, добавленных с помощью appendTextString().

Некорректный поток CBOR

Также возможно неправильное использование QCborStreamWriter и создание некорректных потоков CBOR, которые не будут декодированы получателем. Следующие действия приведут к созданию некорректных потоков:

• Добавление тега без добавления соответствующего помеченного значения (QCborStreamWriter не выдает диагностики).
• Добавление слишком большого или слишком малого количества элементов в массив или словарь с явной длиной (endMap() и endArray() вернут false, а QCborStreamWriter будет регистрировать предупреждение с помощью qWarning()).

См. также QCborStreamReader, QCborValue и QXmlStreamWriter.

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

QCborStreamWriter::QCborStreamWriter(QByteArray *data)

Создаёт объект QCborStreamWriter, который будет добавлять поток в data. Все потоковые операции выполняются сразу в массив байтов без необходимости сброса буферов.

Следующий пример записывает число в массив байтов и возвращает его.

   QByteArray encodedNumber(qint64 value)
   {
       QByteArray ba;
       QCborStreamWriter writer(&ba);
       writer.append(value);
       return ba;
   }

QCborStreamWriter не принимает владение над data.

QCborStreamWriter::QCborStreamWriter(QIODevice *device)

Создаёт объект QCborStreamWriter, который будет записывать поток в device. Устройство должно быть открыто до первого вызова append(). Этот конструктор может быть использован с любым классом, производным от QIODevice, таким как QFile, QProcess или QTcpSocket.

QCborStreamWriter не имеет буферизации, поэтому каждый вызов append() приведёт к одному или нескольким вызовам метода write() устройства.

Следующий пример записывает пустой словарь в файл:

   QFile f("output", QIODevice::WriteOnly);
   QCborStreamWriter writer(&f);
   writer.startMap(0);
   writer.endMap();

QCborStreamWriter не принимает владение над device.

См. также device() и setDevice().

QCborStreamWriter::~QCborStreamWriter()

Удаляет этот объект QCborStreamWriter и освобождает все связанные ресурсы.

QCborStreamWriter не выполняет проверку ошибок, чтобы убедиться, что все необходимые элементы были записаны в поток до уничтожения объекта. Это обязанность программиста.

void QCborStreamWriter::append(quint64 u)

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

Добавляет 64-битовое беззнаковое значение u в поток CBOR, создавая значение CBOR Беззнакового целого. В следующем примере мы записываем значения 0, 2³² и UINT64_MAX.

   writer.append(0U);
   writer.append(Q_UINT64_C(4294967296));
   writer.append(std::numeric_limits<quint64>::max());

См. также QCborStreamReader::isUnsignedInteger() и QCborStreamReader::toUnsignedInteger().

void QCborStreamWriter::append(qint64 i)

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

Добавляет 64-битовое знаковое значение i в поток CBOR. Это создаст значение CBOR Беззнакового целого или CBOR Отрицательного целого в зависимости от знака параметра. В следующем примере мы записываем значения 0, -1, 2³² и INT64_MAX.

   writer.append(0);
   writer.append(-1);
   writer.append(Q_INT64_C(4294967296));
   writer.append(std::numeric_limits<qint64>::max());

См. также QCborStreamReader::isInteger() и QCborStreamReader::toInteger().

void QCborStreamWriter::append(QCborNegativeInteger n)

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

Добавляет 64-битовое отрицательное значение n в поток CBOR. QCborNegativeInteger — это 64-битный перечисление, содержащий абсолютное значение отрицательного числа, которое мы хотим записать. Если n равно нулю, записанное значение будет эквивалентно 2⁶⁴ (то есть -18 446 744 073 709 551 616).

В следующем примере мы записываем значения -1, -2³² и INT64_MIN:

   writer.append(QCborNegativeInteger(1));
   writer.append(QCborNegativeInteger(Q_INT64_C(4294967296)));
   writer.append(QCborNegativeInteger(-quint64(std::numeric_limits<qint64>::min())));

Обратите внимание, как эта функция может использоваться для кодирования чисел, которые не могут поместиться в стандартном 64-битном знаковом целочисленном типе данных, таком как qint64. То есть, если n больше std::numeric_limits<qint64>::max() или равно 0, это будет представлять отрицательное число, меньшее std::numeric_limits<qint64>::min().

См. также QCborStreamReader::isNegativeInteger() и QCborStreamReader::toNegativeInteger().

void QCborStreamWriter::append(const QByteArray &ba)

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

Добавляет массив байтов ba в поток, создавая значение CBOR Строки байтов. QCborStreamWriter попытается записать всю строку за один раз.

Следующий пример загрузит и добавит содержимое файла в поток:

   void writeFile(QCborStreamWriter &writer, const QString &fileName)
   {
       QFile f(fileName);
       if (f.open(QIODevice::ReadOnly))
           writer.append(f.readAll());
   }

Как показывает пример, в отличие от JSON, CBOR не требует экранирования для бинарного содержимого.

См. также appendByteString(), QCborStreamReader::isByteArray() и QCborStreamReader::readByteArray().

void QCborStreamWriter::append(QLatin1String str)

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

Добавляет текстовую строку str в поток, создавая значение CBOR Текстовой строки. QCborStreamWriter попытается записать всю строку за один раз.

Следующий пример добавляет простую строку в поток:

   writer.append(QLatin1String("Hello, World"));

Примечание по производительности: CBOR требует, чтобы все текстовые строки были закодированы в UTF-8, поэтому эта функция будет перебирать символы в строке, чтобы определить, является ли содержимое US-ASCII или нет. Если обнаружатся символы за пределами US-ASCII, будет выделена память и выполнено преобразование в UTF-8. Если эта проверка не нужна, используйте appendTextString() вместо этого.

См. также QCborStreamReader::isString() и QCborStreamReader::readString().

void QCborStreamWriter::append(QStringView str)

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

Добавляет текстовую строку str в поток, создавая значение CBOR Текстовой строки. QCborStreamWriter попытается записать всю строку за один раз.

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

   void writeString(QCborStreamWriter &writer, const QString &str)
   {
       writer.append(str);
   }

См. также QCborStreamReader::isString() и QCborStreamReader::readString().

void QCborStreamWriter::append(QCborTag tag)

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

Добавляет тег CBOR tag в поток, создавая значение CBOR Тега. Все теги должны следовать за другим типом, для которого они придают значение.

В следующем примере мы добавляем тег CBOR 36 (Регулярное выражение) и шаблон QRegularExpression в поток:

   void writeRxPattern(QCborStreamWriter &writer, const QRegularExpression &rx)
   {
       writer.append(QCborTag(36));
       writer.append(rx.pattern());
   }

См. также QCborStreamReader::isTag() и QCborStreamReader::toTag().

void QCborStreamWriter::append(QCborKnownTags tag)

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

Добавляет тег CBOR tag в поток, создавая значение CBOR Тега. Все теги должны следовать за другим типом, для которого они придают значение.

В следующем примере мы добавляем тег CBOR 1 (Unix time_t) и целое число, представляющее текущее время, полученное с помощью функции time(), в поток:

   void writeCurrentTime(QCborStreamWriter &writer)
   {
       writer.append(QCborKnownTags::UnixTime_t);
       writer.append(time(nullptr));
   }

См. также QCborStreamReader::isTag() и QCborStreamReader::toTag().

void QCborStreamWriter::append(QCborSimpleType st)

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

Добавляет простой тип CBOR st в поток, создавая значение CBOR Простого типа. В следующем примере мы записываем простой тип для Null, а также тип 32, для которого у Qt нет поддержки.

  writer.append(QCborSimpleType::Null);
  writer.append(QCborSimpleType(32));

Примечание: Использование простых типов, для которых нет спецификации, может привести к ошибкам проверки со стороны удаленного получателя. Кроме того, простые типы со значениями от 24 до 31 (включительно) зарезервированы и не должны использоваться.

См. также QCborStreamReader::isSimpleType() и QCborStreamReader::toSimpleType().

void QCborStreamWriter::append(std::nullptr_t)

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

Добавляет значение CBOR Null в поток. Эта функция эквивалентна (и реализована как): Параметр игнорируется.

   writer.append(QCborSimpleType::Null);

См. также appendNull(), append(QCborSimpleType) и QCborStreamReader::isNull().

void QCborStreamWriter::append(qfloat16 f)

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

Добавляет число с плавающей точкой f в поток, создавая значение CBOR 16-битного числа с половинной точностью. Следующий код можно использовать для преобразования C++ float в qfloat16 в случае отсутствия потери точности и добавления его, или, вместо этого, добавления float.

   void writeFloat(QCborStreamWriter &writer, float f)
   {
       qfloat16 f16 = f;
       if (qIsNaN(f) || f16 == f)
           writer.append(f16);
       else
           writer.append(f);
   }

См. также QCborStreamReader::isFloat16() и QCborStreamReader::toFloat16().

void QCborStreamWriter::append(float f)

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

Добавляет число с плавающей точкой f в поток, создавая значение CBOR 32-битного числа с одинарной точностью. Следующий код можно использовать для преобразования C++ double в float в случае отсутствия потери точности и добавления его, или, вместо этого, добавления double.

   void writeFloat(QCborStreamWriter &writer, double d)
   {
       float f = d;
       if (qIsNaN(d) || d == f)
           writer.append(f);
       else
           writer.append(d);
   }

См. также QCborStreamReader::isFloat() и QCborStreamReader::toFloat().

void QCborStreamWriter::append(double d)

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

Добавляет число с плавающей точкой d в поток, создавая значение CBOR 64-битного числа с двойной точностью. QCborStreamWriter всегда добавляет число как есть, не выполняя проверки, является ли число канонической формой NaN, бесконечности, является ли оно поднормализованным или может быть записано в более коротком формате.

Следующий код выполняет все эти проверки, кроме проверки на поднормализованное число, которая, как ожидается, будет учтена системой FPU или эмуляцией чисел с плавающей точкой напрямую.

   void writeDouble(QCborStreamWriter &writer, double d)
   {
       float f;
       if (qIsNaN(d)) {
           writer.append(qfloat16(qQNaN()));
       } else if (qIsInf(d)) {
           writer.append(d < 0 ? -qInf() : qInf());
       } else if ((f = d) == d) {
           qfloat16 f16 = f;
           if (f16 == f)
               writer.append(f16);
           else
               writer.append(f);
       } else {
           writer.append(d);
       }
   }

Определение, можно ли преобразовать double в целое число без потери точности, предоставляется читателю в качестве упражнения.

См. также QCborStreamReader::isDouble() и QCborStreamReader::toDouble().

void QCborStreamWriter::append(bool b)

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

Добавляет булево значение b в поток, создавая либо значение CBOR False, либо значение CBOR True. Эта функция эквивалентна (и реализована как):

   writer.append(b ? QCborSimpleType::True : QCborSimpleType::False);

См. также appendNull(), appendUndefined(), QCborStreamReader::isBool(), и QCborStreamReader::toBool().

void QCborStreamWriter::append(const char *str, qsizetype size = -1)

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

Добавляет size байтов текста, начиная с str в поток, создавая значение CBOR Строка текста. QCborStreamWriter попытается записать всю строку в один кусок. Если size равно -1, эта функция запишет strlen(\a str) байтов.

Ожидается, что строка, на которую указывает str, будет правильно закодирована в UTF-8. QCborStreamWriter не выполняет проверки на это.

В отличие от перегрузки append() для QLatin1String, эта функция не ограничена 2 ГБ. Однако обратите внимание, что ни QCborStreamReader, ни QCborValue не поддерживают чтение потоков CBOR со строками текста, превышающими 2 ГБ.

См. также append(QLatin1String), append(QStringView), QCborStreamReader::isString(), и QCborStreamReader::readString().

void QCborStreamWriter::appendByteString(const char *data, qsizetype len)

Добавляет len байтов данных, начиная с data в поток, создавая значение CBOR Строка байтов. QCborStreamWriter попытается записать всю строку в один кусок.

В отличие от перегрузки append() для QByteArray, эта функция не ограничена пределами размера QByteArray. Однако обратите внимание, что ни QCborStreamReader::readByteArray(), ни QCborValue не поддерживают чтение потоков CBOR с массивами байтов, превышающими 2 ГБ.

См. также append(), appendTextString(), QCborStreamReader::isByteArray(), и QCborStreamReader::readByteArray().

void QCborStreamWriter::appendNull()

Добавляет значение CBOR Null в поток. Эта функция эквивалентна (и реализована как):

   writer.append(QCborSimpleType::Null);

См. также append(std::nullptr_t), append(QCborSimpleType), и QCborStreamReader::isNull().

void QCborStreamWriter::appendTextString(const char *utf8, qsizetype len)

Добавляет len байтов текста, начиная с utf8 в поток, создавая значение CBOR Строка текста. QCborStreamWriter попытается записать всю строку в один кусок.

Ожидается, что строка, на которую указывает utf8, будет правильно закодирована в UTF-8. QCborStreamWriter не выполняет проверки на это.

В отличие от перегрузки append() для QLatin1String, эта функция не ограничена 2 ГБ. Однако обратите внимание, что ни QCborStreamReader::readString(), ни QCborValue не поддерживают чтение потоков CBOR со строками текста, превышающими 2 ГБ.

См. также append(QLatin1String), append(QStringView), QCborStreamReader::isString(), и QCborStreamReader::readString().

void QCborStreamWriter::appendUndefined()

Добавляет значение CBOR Undefined в поток. Эта функция эквивалентна (и реализована как):

   writer.append(QCborSimpleType::Undefined);

См. также append(QCborSimpleType) и QCborStreamReader::isUndefined().

QIODevice *QCborStreamWriter::device() const

Возвращает QIODevice, в который записывает этот объект QCborStreamWriter. Устройство должно быть предварительно установлено с помощью конструктора или с помощью setDevice().

Если этот объект был создан путем записи в QByteArray, эта функция вернет внутренний экземпляр QBuffer, который принадлежит QCborStreamWriter.

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

bool QCborStreamWriter::endArray()

Завершает массив, начатый любой из перегрузок startArray(), и возвращает true, если в массив было добавлено правильное количество элементов. Эта функция должна вызываться для каждой startArray().

Возврат false указывает на ошибку в приложении и невосстановимую ошибку в этом потоке. QCborStreamWriter также выводит предупреждение с помощью qWarning(), если это произойдет.

Вызов этой функции, когда текущий контейнер не является массивом, также является ошибкой, хотя QCborStreamWriter в настоящее время не может обнаружить это условие.

См. также startArray(), startArray(quint64), и endMap().

bool QCborStreamWriter::endMap()

Завершает карту, начатую любой из перегрузок startMap(), и возвращает true, если в карту было добавлено правильное количество элементов. Эта функция должна вызываться для каждой startMap().

Возврат false указывает на ошибку в приложении и невосстановимую ошибку в этом потоке. QCborStreamWriter также выводит предупреждение с помощью qWarning(), если это произойдет.

Вызов этой функции, когда текущий контейнер не является картой, также является ошибкой, хотя QCborStreamWriter в настоящее время не может обнаружить это условие.

См. также startMap(), startMap(quint64), и endArray().

void QCborStreamWriter::setDevice(QIODevice *device)

Заменяет устройство или массив байтов, в который пишет этот объект QCborStreamWriter, на device.

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

void QCborStreamWriter::startArray()

Начинает массив CBOR неопределенной длины в потоке CBOR. Каждый вызов startArray() должен быть сопряжен с одним вызовом endArray(), и текущий элемент CBOR расширяется до конца массива.

Массив, созданный этой функцией, не имеет явной длины. Вместо этого его длина подразумевается элементами, содержащимися в нем. Однако обратите внимание, что использование массивов неопределенной длины не соответствует каноническому кодированию CBOR.

Следующий пример добавляет элементы из связанного списка строк, переданных в качестве входных данных:

   void appendList(QCborStreamWriter &writer, const QLinkedList<QString> &list)
   {
       writer.startArray();
       for (const QString &s : list)
           writer.append(s);
       writer.endArray();
   }

См. также startArray(quint64), endArray(), startMap(), QCborStreamReader::isArray() и QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startArray(quint64 count)

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

Начинает массив CBOR с явным размером count элементов в потоке CBOR. Каждый вызов startArray должен быть сопряжен с одним вызовом endArray(), и текущий элемент CBOR продолжается до конца массива.

Массив, созданный этой функцией, имеет явный размер, поэтому в поток CBOR необходимо добавить ровно count элементов. Добавление меньшего или большего количества элементов приведёт к ошибке при вызове endArray(), и поток CBOR будет повреждён. Однако массивы с явным размером необходимы для канонического кодирования CBOR.

В следующем примере добавляются все строки, найденные в QStringList, переданной в качестве входных данных:

   void appendList(QCborStreamWriter &writer, const QStringList &list)
   {
       writer.startArray(list.size());
       for (const QString &s : list)
           writer.append(s);
       writer.endArray();
   }

Ограничения по размеру: Параметр этой функции — quint64, что, по-видимому, позволяет использовать до 2⁶⁴-1 элементов в массиве. Однако как QCborStreamWriter, так и QCborStreamReader в настоящее время ограничены 2³²-2 элементами на 32-битных системах и 2⁶⁴-2 элементами на 64-битных. Обратите также внимание, что QCborArray в настоящее время ограничен 2²⁷ элементами на любой платформе.

См. также startArray(), endArray(), startMap(), QCborStreamReader::isArray() и QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap()

Начинает карту CBOR с неопределённым размером в потоке CBOR. Каждый вызов startMap() должен быть сопряжен с одним вызовом endMap(), и текущий элемент CBOR продолжается до конца карты.

Созданная этой функцией карта не имеет явного размера. Вместо этого её размер определяется элементами, содержащимися в ней. Однако следует отметить, что использование карт неопределённого размера не соответствует каноническому кодированию CBOR (для канонического кодирования также требуется, чтобы ключи были уникальными и отсортированными).

В следующем примере добавляются элементы из связанного списка пар «целое число—строка», переданных в качестве входных данных:

   void appendMap(QCborStreamWriter &writer, const QLinkedList<QPair<int, QString>> &list)
   {
       writer.startMap();
       for (const auto pair : list) {
           writer.append(pair.first)
           writer.append(pair.second);
       }
       writer.endMap();
   }

См. также startMap(quint64), endMap(), startArray(), QCborStreamReader::isMap() и QCborStreamReader::isLengthKnown().

void QCborStreamWriter::startMap(quint64 count)

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

Начинает карту CBOR с явным размером count элементов в потоке CBOR. Каждый вызов startMap должен быть сопряжен с одним вызовом endMap(), и текущий элемент CBOR продолжается до конца карты.

Созданная этой функцией карта имеет явный размер, поэтому в поток CBOR необходимо добавить ровно count пар элементов. Добавление меньшего или большего количества элементов приведёт к ошибке при вызове endMap(), и поток CBOR будет повреждён. Однако карты с явным размером необходимы для канонического кодирования CBOR.

В следующем примере добавляются все строки, найденные в QMap, переданной в качестве входных данных:

   void appendMap(QCborStreamWriter &writer, const QMap<int, QString> &map)
   {
       writer.startMap(map.size());
       for (auto it = map.begin(); it != map.end(); ++it) {
           writer.append(it.key());
           writer.append(it.value());
       }
       writer.endMap();
   }

Ограничения по размеру: Параметр этой функции — quint64, что, по-видимому, позволяет использовать до 2⁶⁴-1 пар в карте. Однако как QCborStreamWriter, так и QCborStreamReader в настоящее время ограничены 2³¹-1 элементом на 32-битных системах и 2⁶³-1 элементом на 64-битных. Обратите также внимание, что QCborMap в настоящее время ограничен 2²⁶ элементами на любой платформе.

См. также startMap(), endMap(), startArray(), QCborStreamReader::isMap() и QCborStreamReader::isLengthKnown().