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

Примечание: Использование Простых типов, для которых нет спецификации, может привести к ошибкам валидации у удалённого получателя. Кроме того, значения простых типов от 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 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().