Класс QCborStreamWriter

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

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

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

Открытые функции

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

Этот класс можно использовать для быстрого кодирования потока содержимого 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));

См. также 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 QList<QString> &values)
   {
       writer.startArray();
       for (const QString &s : values)
           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 QList<QPair<int, QString>> &values)
   {
       writer.startMap();
       for (const auto pair : values) {
           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().