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

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

Каноническое кодирование 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 не выполняет проверку на это.

В отличие от перегрузки QLatin1String функции append(), эта функция не ограничена 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 попытается записать всю строку в одном блоке.

В отличие от перегрузки QByteArray функции append(), эта функция не ограничена размерами 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 не выполняет проверку на это.

В отличие от перегрузки QLatin1String функции append(), эта функция не ограничена 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().