diff options
author | Øystein Heskestad <oystein.heskestad@qt.io> | 2022-08-24 17:54:37 +0200 |
---|---|---|
committer | Øystein Heskestad <oystein.heskestad@qt.io> | 2022-09-01 19:03:00 +0200 |
commit | 855a9ca217ad3b9d8eb8f6544698a174323843fc (patch) | |
tree | 7694c33d990df202896f0b8bbaa766da1daef11a | |
parent | 2e8c84cda25de38d64669a9d078d87c7d2bf451c (diff) |
Add CBOR documentation
Add documentation of usage of CBOR in convert and cbordump examples,
add a CBOR overview, and add links to them other places in the
documentation.
Task-number: QTBUG-85912
Change-Id: I518792db63647bf9ddd4507d8d4b7ef056192f82
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
-rw-r--r-- | examples/corelib/serialization/cbordump/doc/images/cbordump.png | bin | 0 -> 48004 bytes | |||
-rw-r--r-- | examples/corelib/serialization/cbordump/doc/src/cbordump.qdoc | 52 | ||||
-rw-r--r-- | examples/corelib/serialization/cbordump/main.cpp | 2 | ||||
-rw-r--r-- | examples/corelib/serialization/convert/cborconverter.cpp | 14 | ||||
-rw-r--r-- | examples/corelib/serialization/convert/doc/images/convert.png | bin | 0 -> 49201 bytes | |||
-rw-r--r-- | examples/corelib/serialization/convert/doc/src/convert.qdoc | 80 | ||||
-rw-r--r-- | examples/corelib/serialization/savegame/doc/src/savegame.qdoc | 2 | ||||
-rw-r--r-- | src/corelib/doc/src/cbor.qdoc | 78 | ||||
-rw-r--r-- | src/corelib/doc/src/datastreamformat.qdoc | 3 | ||||
-rw-r--r-- | src/corelib/doc/src/qtcore-index.qdoc | 1 | ||||
-rw-r--r-- | src/corelib/serialization/qcborarray.cpp | 3 | ||||
-rw-r--r-- | src/corelib/serialization/qcborcommon.cpp | 1 | ||||
-rw-r--r-- | src/corelib/serialization/qcbormap.cpp | 3 | ||||
-rw-r--r-- | src/corelib/serialization/qcborstreamreader.cpp | 3 | ||||
-rw-r--r-- | src/corelib/serialization/qcborstreamwriter.cpp | 1 | ||||
-rw-r--r-- | src/corelib/serialization/qcborvalue.cpp | 3 |
16 files changed, 236 insertions, 10 deletions
diff --git a/examples/corelib/serialization/cbordump/doc/images/cbordump.png b/examples/corelib/serialization/cbordump/doc/images/cbordump.png Binary files differnew file mode 100644 index 0000000000..72232c1a95 --- /dev/null +++ b/examples/corelib/serialization/cbordump/doc/images/cbordump.png diff --git a/examples/corelib/serialization/cbordump/doc/src/cbordump.qdoc b/examples/corelib/serialization/cbordump/doc/src/cbordump.qdoc new file mode 100644 index 0000000000..c3565e184d --- /dev/null +++ b/examples/corelib/serialization/cbordump/doc/src/cbordump.qdoc @@ -0,0 +1,52 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example serialization/cbordump + \title Cbordump Example + + \brief The Cbordump example demonstrates how to parse files in CBOR-format. + + The Cbordump example reads from files or stdin content in CBOR-format and + dumps the decoded content to stdout. The cbordump utility can output in + CBOR diagnostic notation (which is similar to JSON), or it can have a + verbose output where each byte input is displayed with the encoding beside + it. This example shows how to use the QCborStreamReader class directly to + parse CBOR content. + + \sa QCborStreamReader + + \image cbordump.png + + \section1 The Cbordumper Class + + The Cbordumper class contains a QCborStreamReader object that is + initialized using the QFile object argument passed to the CborDumper + constructor. Based on the arguments the dump function calls either + dumpOne() or dumpOneDetailed() to dump the contents to stdout, + + \snippet serialization/cbordump/main.cpp 0 + + \section2 The dumpOne() Function + + The type() function of the QCborStreamReader is used in a switch statement + to print out for each type. If the type is an array or map, the content is + iterated upon, and for each entry the dumpOne() function is called + recursively with a higher indentation argument. If the type is a tag, it + is printed out and dumpOne() is called once without increasing the + indentation argument. + + \section2 The dumpOneDetailed() Function + + This function dumps out both the incoming bytes and the decoded contents + on the same line. It uses lambda functions to print out the bytes and + decoded content, but otherwise has a similar structure as dumpOne(). + + \section1 CborDescription + + The tagDescriptions table, describing the CBOR-tags available, is + automatically generated from an XML-file available from the iana.org + website. + + \sa {CBOR Support in Qt} + */ diff --git a/examples/corelib/serialization/cbordump/main.cpp b/examples/corelib/serialization/cbordump/main.cpp index 126a5c5833..16ff27d701 100644 --- a/examples/corelib/serialization/cbordump/main.cpp +++ b/examples/corelib/serialization/cbordump/main.cpp @@ -87,6 +87,7 @@ enum { Value64Bit = 27 }; +//! [0] struct CborDumper { enum DumpOption { @@ -113,6 +114,7 @@ private: qint64 offset = 0; DumpOptions opts; }; +//! [0] Q_DECLARE_OPERATORS_FOR_FLAGS(CborDumper::DumpOptions) static int cborNumberSize(quint64 value) diff --git a/examples/corelib/serialization/convert/cborconverter.cpp b/examples/corelib/serialization/convert/cborconverter.cpp index 0f49de2551..8c88d42af3 100644 --- a/examples/corelib/serialization/convert/cborconverter.cpp +++ b/examples/corelib/serialization/convert/cborconverter.cpp @@ -57,6 +57,7 @@ QT_END_NAMESPACE static QVariant convertCborValue(const QCborValue &value); +//! [0] static QVariant convertCborMap(const QCborMap &map) { VariantOrderedMap result; @@ -83,8 +84,9 @@ static QVariant convertCborValue(const QCborValue &value) return convertCborMap(value.toMap()); return value.toVariant(); } - +//! [0] enum TrimFloatingPoint { Double, Float, Float16 }; +//! [1] static QCborValue convertFromVariant(const QVariant &v, TrimFloatingPoint fpTrimming) { if (v.userType() == QMetaType::QVariantList) { @@ -114,6 +116,7 @@ static QCborValue convertFromVariant(const QVariant &v, TrimFloatingPoint fpTrim return QCborValue::fromVariant(v); } +//! [1] QString CborDiagnosticDumper::name() { @@ -216,6 +219,7 @@ bool CborConverter::probeFile(QIODevice *f) return f->isReadable() && f->peek(3) == QByteArray("\xd9\xd9\xf7", 3); } +//! [2] QVariant CborConverter::loadFile(QIODevice *f, Converter *&outputConverter) { const char *ptr = nullptr; @@ -250,9 +254,11 @@ QVariant CborConverter::loadFile(QIODevice *f, Converter *&outputConverter) return contents.toVariant(); return convertCborValue(contents); } - +//! [2] +//! [3] void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStringList &options) { + //! [3] bool useSignature = true; bool useIntegers = true; enum { Yes, No, Always } useFloat16 = Yes, useFloat = Yes; @@ -311,7 +317,7 @@ void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStri qPrintable(s), optionHelp); exit(EXIT_FAILURE); } - + //! [4] QCborValue v = convertFromVariant(contents, useFloat16 == Always ? Float16 : useFloat == Always ? Float : Double); QCborStreamWriter writer(f); @@ -327,4 +333,4 @@ void CborConverter::saveFile(QIODevice *f, const QVariant &contents, const QStri opts |= QCborValue::UseFloat16; v.toCbor(writer, opts); } - +//! [4] diff --git a/examples/corelib/serialization/convert/doc/images/convert.png b/examples/corelib/serialization/convert/doc/images/convert.png Binary files differnew file mode 100644 index 0000000000..8d6816a626 --- /dev/null +++ b/examples/corelib/serialization/convert/doc/images/convert.png diff --git a/examples/corelib/serialization/convert/doc/src/convert.qdoc b/examples/corelib/serialization/convert/doc/src/convert.qdoc new file mode 100644 index 0000000000..dc3264a469 --- /dev/null +++ b/examples/corelib/serialization/convert/doc/src/convert.qdoc @@ -0,0 +1,80 @@ +// Copyright (C) 2022 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \example serialization/convert + \title Convert Example + + \brief The Convert example demonstrates how to convert between different + serialization formats. + + The Convert example converts between the serialization formats JSON, CBOR, + XML, QDataStream and text. It can also auto detect the format being used. + Not all formats support both input and output, and they have different + sets of which types they support. QDataStream and XML are the richest, + followed by CBOR, then JSON, and then the plain text one. + + \image convert.png + + \section1 The Converter Class + + The Converter class is the abstract superclass for all the converters to + and from all the formats. They all convert to and from the QVariant class, + which is used to represent all the datastructures internally. + The name() function returns the name of the converter. The directions() + function is used to determine if a converter can be used for input, output, + or both. The outputOptions() and optionsHelp() functions are used to get + and query which options are used by the different converters. The + probeFile() function is used to determine if a file has the same file + format as the converter. The loadFile() function deserializes the given + file, while the saveFile() serializes to the given file. + + \section1 The CborConverter Class + + The CborConverter class shows how to serialize to and from the CBOR-format. + There is also a CborDiagnosticDumper class to output in CBOR diagnostic + notation. That is similar to JSON, but not exactly, because it allows + displaying the contents of a CBOR stream losslessly, while a conversion + to JSON is lossy. + + The convertCborValue() function is used to convert a QCborValue to a + QVariant. It uses the helper functions convertCborMap() and + convertCborArray(). + \snippet serialization/convert/cborconverter.cpp 0 + + A CBOR-file is read using loadFile() function. + \snippet serialization/convert/cborconverter.cpp 2 + + The convertFromVariant() function is used to convert a QVariant to a + QCborValue. + \snippet serialization/convert/cborconverter.cpp 1 + + A CBOR-file is written using the saveFile() function. + \snippet serialization/convert/cborconverter.cpp 3 + \snippet serialization/convert/cborconverter.cpp 4 + + \sa {CBOR Support in Qt} + + \section1 The DataStreamConverter Class + + The DataStreamConverter class is used to serialize to and from the + QDataStream format. There is also the DataStreamDumper class for outputting + the data lossless in a non-standardized human readable format. + + \section1 The JsonConverter Class + + The JsonConverter class is used to serialize to and from the JSON-format. + \sa {JSON Support in Qt} + + \section1 The XmlConverter Class + + The XmlConverter class is used to serialize to and from the XML-format. + + \section1 The TextConverter Class + + The TextConverter class is used to serialize to and from a text format. + + \section1 The NullConverter Class + + The NullConverter class is an output serializer that does nothing. +*/ diff --git a/examples/corelib/serialization/savegame/doc/src/savegame.qdoc b/examples/corelib/serialization/savegame/doc/src/savegame.qdoc index 0246ae48bb..233c81dd8b 100644 --- a/examples/corelib/serialization/savegame/doc/src/savegame.qdoc +++ b/examples/corelib/serialization/savegame/doc/src/savegame.qdoc @@ -158,5 +158,5 @@ human-readable JSON files, but you also have the option to use a binary format if it's required, \e without rewriting any code. - \sa {JSON Support in Qt}, {Data Storage} + \sa {JSON Support in Qt}, {CBOR Support in Qt}, {Data Storage} */ diff --git a/src/corelib/doc/src/cbor.qdoc b/src/corelib/doc/src/cbor.qdoc new file mode 100644 index 0000000000..22252bbd88 --- /dev/null +++ b/src/corelib/doc/src/cbor.qdoc @@ -0,0 +1,78 @@ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \group cbor + \title CBOR Support in Qt + \ingroup qt-basic-concepts + \brief An overview of CBOR support in Qt. + + \ingroup frameworks-technologies + + \keyword CBOR + + Qt provides support for dealing with CBOR data. CBOR is a binary format to + store data that has a superset of the types available in JSON, but is more + compact. + + The CBOR support in Qt provides an easy to use C++ API to parse, + modify and save CBOR data. + + More details about the CBOR data format can be found in \l {RFC 7049}. + + \tableofcontents + + \section1 Overview + + CBOR is a format to store structured data. It has three groups of built-in types: + + \list + \li Basic types: integers, floating point, boolean, null, etc. + \li String-like types: strings and byte arrays + \li Containers: arrays and maps + \endlist + + In addition, CBOR can add a "tag" to extend the meaning of the type. The + container types can contain basic types, string-like types and containers. + + \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example} + + \section1 The CBOR Classes + + \section2 The QCborValue Class + + The QCborValue class represents any CBOR type. It also has a simple API for + reading and writing to QCborStreamReader and QCborStreamWriter objects, as + well as manipulating such objects in memory, with the help of QCborArray + and QCborMap. The CborValue API is simplified from the full CBOR data type + and always represents all integers as \l qint64 and all floating-point as + \c double. This means QCborValue is unable to represent CBOR integer values + outside of the range of \l qint64 (-2^63 to 2^63-1). When creating a CBOR + stream, QCborValue::toCbor() can be configured to attempt to write the + shorter single- and half-precision floating-point representations. + + \section2 The QCborArray Class + + The QCborArray class is used to hold an array of QCborValue objects. A + QCborValue object can contain a QCborArray object. It has functions for + converting to and from QVariantList, QStringList, QJsonArray. + + \section2 The QCborMap Class + + The QCborMap class is used to hold an map of QCborValue objects. A + QCborValue object can contain a QCborMap object. It has functions for + converting to and from QVariantMap, QVariantMap, and QJsonObject, but it + can have keys of any type, not just QString. + + \section2 The QCborStreamReader Class + + The QCborStreamReader class is a low level API for reading CBOR data from a + QIODevice, a QByteArray, or a pointer to memory. It has an API similar to + the QXmlStreamReader class. + + \section2 The QCborStreamWriter Class + + The QCborStreamWriter class is a low level API for writing CBOR data to a + QIODevice or a QByteArray. It has an API similar to the QXmlStreamWriter + class. +*/ diff --git a/src/corelib/doc/src/datastreamformat.qdoc b/src/corelib/doc/src/datastreamformat.qdoc index ae8e155bea..b1b2e6ba34 100644 --- a/src/corelib/doc/src/datastreamformat.qdoc +++ b/src/corelib/doc/src/datastreamformat.qdoc @@ -67,5 +67,6 @@ \li QVector4D \endlist - \sa {JSON Support in Qt} + \sa {JSON Support in Qt}, {CBOR Support in Qt} + */ diff --git a/src/corelib/doc/src/qtcore-index.qdoc b/src/corelib/doc/src/qtcore-index.qdoc index 377e199784..99cc114d64 100644 --- a/src/corelib/doc/src/qtcore-index.qdoc +++ b/src/corelib/doc/src/qtcore-index.qdoc @@ -75,6 +75,7 @@ \list \li \l{The Animation Framework} \li \l{JSON Support in Qt} + \li \l{CBOR Support in Qt} \li \l{How to Create Qt Plugins} \li \l{The Event System} \endlist diff --git a/src/corelib/serialization/qcborarray.cpp b/src/corelib/serialization/qcborarray.cpp index 1c8d21af47..95fd47b767 100644 --- a/src/corelib/serialization/qcborarray.cpp +++ b/src/corelib/serialization/qcborarray.cpp @@ -30,7 +30,8 @@ using namespace QtCbor; from those two, though there may be loss of information in some conversions. - \sa QCborValue, QCborMap, QJsonArray, QList + \sa QCborValue, QCborMap, QJsonArray, QList, {Cbordump Example}, + {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp index 648ca59d8b..9168b8c520 100644 --- a/src/corelib/serialization/qcborcommon.cpp +++ b/src/corelib/serialization/qcborcommon.cpp @@ -179,6 +179,7 @@ QDataStream &operator>>(QDataStream &ds, QCborSimpleType &st) validating a CBOR stream. \sa QCborStreamReader, QCborValue, QCborParserError + \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcbormap.cpp b/src/corelib/serialization/qcbormap.cpp index b3b9ea2691..c8895cb42a 100644 --- a/src/corelib/serialization/qcbormap.cpp +++ b/src/corelib/serialization/qcbormap.cpp @@ -46,7 +46,8 @@ using namespace QtCbor; stringified using a one-way method that the conversion back to QCborMap will not undo. - \sa QCborArray, QCborValue, QJsonDocument, QVariantMap + \sa QCborArray, QCborValue, QJsonDocument, QVariantMap, {Cbordump Example} + \sa {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcborstreamreader.cpp b/src/corelib/serialization/qcborstreamreader.cpp index 10b3eb2d45..65edd3a941 100644 --- a/src/corelib/serialization/qcborstreamreader.cpp +++ b/src/corelib/serialization/qcborstreamreader.cpp @@ -151,7 +151,8 @@ static_assert(int(QCborStreamReader::Invalid) == CborInvalidType); parsing from a QByteArray, or reparse(), if it is instead reading directly a the QIDOevice that now has more data available (see setDevice()). - \sa QCborStreamWriter, QCborValue, QXmlStreamReader + \sa QCborStreamWriter, QCborValue, QXmlStreamReader, {Cbordump Example} + \sa {Convert Example}, {JSON Save Game Example} */ /*! diff --git a/src/corelib/serialization/qcborstreamwriter.cpp b/src/corelib/serialization/qcborstreamwriter.cpp index 9f7e30e8cb..0e445451bc 100644 --- a/src/corelib/serialization/qcborstreamwriter.cpp +++ b/src/corelib/serialization/qcborstreamwriter.cpp @@ -175,6 +175,7 @@ Q_DECLARE_TYPEINFO(CborEncoder, Q_PRIMITIVE_TYPE); \endlist \sa QCborStreamReader, QCborValue, QXmlStreamWriter + \sa {Cbordump Example}, {Convert Example}, {JSON Save Game Example} */ class QCborStreamWriterPrivate diff --git a/src/corelib/serialization/qcborvalue.cpp b/src/corelib/serialization/qcborvalue.cpp index c136e80755..1df4a16e97 100644 --- a/src/corelib/serialization/qcborvalue.cpp +++ b/src/corelib/serialization/qcborvalue.cpp @@ -189,7 +189,8 @@ Q_DECL_UNUSED static constexpr quint64 MaximumPreallocatedElementCount = aspects, its API is identical to QCborValue. \sa QCborArray, QCborMap, QCborStreamReader, QCborStreamWriter - QJsonValue, QJsonDocument + \sa QJsonValue, QJsonDocument, {Cbordump Example}, {Convert Example} + \sa {JSON Save Game Example} */ /*! |