Класс QCborStreamWriter

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

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

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

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

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

Класс 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(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(QByteArray *data)

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

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

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

QCborStreamWriter не получает владения data.

QCborStreamWriter::QCborStreamWriter(const QCborStreamWriter &)

Конструктор по умолчанию создаёт экземпляр QCborStreamWriter.

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-битного числа с плавающей запятой половинной точности. Следующий код можно использовать для преобразования float C++ в 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-битного числа с плавающей запятой одинарной точности. Следующий код можно использовать для преобразования double C++ в 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);
       }
   }

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

См. также 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().

QCborStreamWriter &QCborStreamWriter::operator=(const QCborStreamWriter &)

Оператор присваивания по копированию.