Qt
Internal/Contributor docs for the Qt SDK. <b>Note:</b> These are NOT official API docs; those are found <a href='https://doc.qt.io/'>here</a>.
Loading...
Searching...
No Matches
qtserialization.qdoc
Go to the documentation of this file.
1// Copyright (C) 2022 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3
4/*!
5 \page qtserialization.html
6 \title Qt Serialization
7 \brief Serializations provided by Qt API
8
9 The purpose of serialization is to save the state of an object to be able to
10 recreate it when needed. It allows you to perform actions like:
11
12 \list
13 \li Sending the object to a remote application by using a web service
14 \li Passing the object as a JSON or XML string
15 \li Saving and restoring user information or sharing it across applications
16 \endlist
17
18 The Qt API provides support for serialization for several use cases:
19
20 \list
21 \li \l JSON support in Qt provides an easy to use C++ API to parse, modify
22 and save JSON data. \l {CBOR} {CBOR Support in Qt} is a compact form
23 of binary data encoding that is a superset of JSON.
24 \li \l QDataStream provides serialization of binary data to a QIODevice
25 \li \l {Qt XML C++ Classes} provide C++ implementations of the \l {XML Streaming}
26 and DOM standards for XML
27 \li \l CBOR is Qt's implementation for the CBOR serialization format.
28 \li \l QSettings provides a way of serializing and storing platform independent
29 application settings.
30 \endlist
31
32 \section1 Advantages of JSON and CBOR
33
34 When you use \l JSON information is stored in a QJsonObject and a QJsonDocument
35 takes care to stream values into a QByteArray.
36
37 For example
38 \code
39 QJsonObject jobject;
40 jobject["SensorID"] = m_id;
41 jobject["AmbientTemperature"] = m_ambientTemperature;
42 jobject["ObjectTemperature"] = m_objectTemperature;
43 jobject["AccelerometerX"] = m_accelerometerX;
44 jobject["AccelerometerY"] = m_accelerometerY;
45 jobject["AccelerometerZ"] = m_accelerometerZ;
46 jobject["Altitude"] = m_altitude;
47 jobject["Light"] = m_light;
48 jobject["Humidity"] = m_humidity;
49 QJsonDocument doc( jobject );
50
51 return doc.toJson();
52 \endcode
53
54 JSON has several advantages:
55
56 \list
57 \li Textual JSON is declarative, which makes it readable to humans
58 \li The information is structured
59 \li Exchanging generic information is easy
60 \li JSON allows extending messages with additional values
61 \li Many solutions exist to receive and parse JSON in cloud-based solutions
62 \endlist
63
64 \l CBOR is the Concise Binary Object Representation, a very compact form of
65 binary data encoding that is a superset of JSON. It was created by the IETF
66 Constrained RESTful Environments (CoRE) WG, which has been used in many new
67 RFCs. CBOR shares many of the advantages of JSON, but sacrifices human
68 readability for compactness.
69
70 \section1 Advantages of QDataStream Classes
71
72 \l QDataStream is a viable option when the whole flow of data is determined
73 and not about to change. In addition, both the reader and the writer of the
74 data must be written in Qt.
75
76 Adding support for this to a class requires two additional operators.
77 For example, for a class named SensorInformation:
78
79 \code
80 QDataStream &operator<<(QDataStream &, const SensorInformation &);
81 QDataStream &operator>>(QDataStream &, SensorInformation &);
82 \endcode
83
84 The implementation for the serialization is shown below:
85
86 \code
87 QDataStream &operator<<(QDataStream &out, const SensorInformation &item)
88 {
89 QDataStream::FloatingPointPrecision prev = out.floatingPointPrecision();
90 out.setFloatingPointPrecision(QDataStream::DoublePrecision);
91 out << item.m_id
92 << item.m_ambientTemperature
93 << item.m_objectTemperature
94 << item.m_accelerometerX
95 << item.m_accelerometerY
96 << item.m_accelerometerZ
97 << item.m_altitude
98 << item.m_light
99 << item.m_humidity;
100 out.setFloatingPointPrecision(prev);
101 return out;
102 }
103 \endcode
104
105 Deserialization works similarly, but using the \c {>>} operator.
106 For example, \c {out >> item.m_id}, and so on.
107
108 Usually, using QDataStream is faster than using textual JSON.
109
110 \section1 Advantages of Qt XML C++ Classes
111
112 Qt provides both DOM classes and stream-based classes to read and write
113 XML content.
114
115 Qt provides the QDomDocument class that represents the XML document and
116 two classes for reading and writing the XML through a simple streaming API:
117 QXmlStreamReader and QXmlStreamWriter.
118
119 \section2 The DOM XML Classes
120
121 QDomDocument class represents the entire XML document. It is the root of the
122 document tree and provides primary access to the document's data.
123
124 \section2 The Stream-Based XML Classes
125
126 A stream reader reports an XML document as a stream of tokens. This differs
127 from SAX as SAX applications provide handlers to receive XML events from the
128 parser, whereas the QXmlStreamReader drives the loop, pulling tokens from the
129 reader when they are needed. This pulling approach makes it possible to build
130 recursive descent parsers, allowing XML parsing code to be split into
131 different methods or classes.
132
133 QXmlStreamReader a parser for well-formed XML 1.0, excluding external parsed
134 entities. Hence, data provided to the stream reader adheres to the
135 W3C's criteria for well-formed XML, or an error will be raised. Functions
136 such as \c atEnd(), \c error(), and \c hasError() can be used to test for
137 such errors and obtain a description of them.
138
139 The QXmlStreamWriter is a streaming API that takes care of prefixing namespaces,
140 when the namespaceUri is specified when writing elements or attributes.
141
142 \section1 Classes that Provide Serialization
143
144 \annotatedlist qtserialization
145*/