Update copyright headers
[qt:qt.git] / doc / src / files-and-resources / datastreamformat.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page datastreamformat.html
30     \title Serializing Qt Data Types
31     \ingroup qt-network
32     \brief Representations of data types that can be serialized by QDataStream.
33
34     The \l QDataStream allows you to serialize some of the Qt data types.
35     The table below lists the data types that QDataStream can serialize
36     and how they are represented. The format described below is
37     \l{QDataStream::setVersion()}{version 12}.
38
39     It is always best to cast integers to a Qt integer type, such as
40     qint16 or quint32, when reading and writing. This ensures that
41     you always know exactly what size integers you are reading and
42     writing, no matter what the underlying platform and architecture
43     the application happens to be running on.
44
45     \table
46     \row \o bool
47          \o \list
48             \o boolean
49             \endlist
50     \row \o qint8
51          \o \list
52             \o signed byte
53             \endlist
54     \row \o qint16
55          \o \list
56             \o signed 16-bit integer
57             \endlist
58     \row \o qint32
59          \o \list
60             \o signed 32-bit integer
61             \endlist
62     \row \o qint64
63          \o \list
64             \o signed 64-bit integer
65             \endlist
66     \row \o quint8
67          \o \list
68             \o unsigned byte
69             \endlist
70     \row \o quint16
71          \o \list
72             \o unsigned 16-bit integer
73             \endlist
74     \row \o quint32
75          \o \list
76             \o unsigned 32-bit integer
77             \endlist
78     \row \o quint64
79          \o \list
80             \o unsigned 64-bit integer
81             \endlist
82     \row \o \c float
83          \o \list
84             \o 32-bit floating point number using the standard IEEE 754 format
85             \endlist
86     \row \o \c double
87          \o \list
88             \o 64-bit floating point number using the standard IEEE 754 format
89             \endlist
90     \row \o \c {const char *}
91          \o \list
92             \o The string length (quint32)
93             \o The string bytes, excluding the terminating 0
94             \endlist
95     \row \o QBitArray
96          \o \list
97             \o The array size (quint32)
98             \o The array bits, i.e. (size + 7)/8 bytes
99             \endlist
100     \row \o QBrush
101          \o \list
102             \o The brush style (quint8)
103             \o The brush color (QColor)
104             \o If style is CustomPattern, the brush pixmap (QPixmap)
105             \endlist
106     \row \o QByteArray
107          \o \list
108             \o If the byte array is null: 0xFFFFFFFF (quint32)
109             \o Otherwise: the array size (quint32) followed by the array bytes, i.e. size bytes
110             \endlist
111     \row \o \l QColor
112          \o \list
113             \o Color spec (qint8)
114             \o Alpha value (quint16)
115             \o Red value (quint16)
116             \o Green value (quint16)
117             \o Blue value (quint16)
118             \o Pad value (quint16)
119             \endlist
120     \row \o QCursor
121          \o \list
122             \o Shape ID (qint16)
123             \o If shape is BitmapCursor: The bitmap (QPixmap), mask (QPixmap), and hot spot (QPoint)
124             \endlist
125     \row \o QDate
126          \o \list
127             \o Julian day (quint32)
128             \endlist
129     \row \o QDateTime
130          \o \list
131             \o Date (QDate)
132             \o Time (QTime)
133             \o 0 for Qt::LocalTime, 1 for Qt::UTC (quint8)
134             \endlist
135     \row \o QEasingCurve
136          \o \list
137             \o type (quint8)
138             \o func (quint64)
139             \o hasConfig (bool)
140             \o If hasConfig is true then these fields follow:
141             \o list
142                 \o period (double)
143                 \o amplitude (double)
144                 \o overshoot (double)
145             \endlist
146     \row \o QFont
147          \o \list
148             \o The family (QString)
149             \o The point size (qint16)
150             \o The style hint (quint8)
151             \o The char set (quint8)
152             \o The weight (quint8)
153             \o The font bits (quint8)
154             \endlist
155     \row \o QHash<Key, T>
156          \o \list
157             \o The number of items (quint32)
158             \o For all items, the key (Key) and value (T)
159             \endlist
160     \row \o QIcon
161          \o \list
162             \o The number of pixmap entries (quint32)
163             \o For all pixmap entries:
164                \list
165                \o The pixmap (QPixmap)
166                \o The file name (QString)
167                \o The pixmap size (QSize)
168                \o The \l{QIcon::Mode}{mode} (quint32)
169                \o The \l{QIcon::State}{state} (quint32)
170                \endlist
171             \endlist
172     \row \o QImage
173          \o \list
174             \o If the image is null a "null image" marker is saved;
175             otherwise the image is saved in PNG or BMP format (depending
176             on the stream version). If you want control of the format,
177             stream the image into a QBuffer (using QImageIO) and stream
178             that.
179             \endlist
180     \row \o QKeySequence
181          \o \list
182             \o A QList<int>, where each integer is a key in the key sequence
183             \endlist
184     \row \o QLinkedList<T>
185          \o \list
186             \o The number of items (quint32)
187             \o The items (T)
188             \endlist
189     \row \o QList<T>
190          \o \list
191             \o The number of items (quint32)
192             \o The items (T)
193             \endlist
194     \row \o QMap<Key, T>
195          \o \list
196             \o The number of items (quint32)
197             \o For all items, the key (Key) and value (T)
198             \endlist
199     \row \o QMatrix
200          \o \list
201             \o m11 (double)
202             \o m12 (double)
203             \o m21 (double)
204             \o m22 (double)
205             \o dx (double)
206             \o dy (double)
207             \endlist
208     \row \o QMatrix4x4
209          \o \list
210             \o m11 (double)
211             \o m12 (double)
212             \o m13 (double)
213             \o m14 (double)
214             \o m21 (double)
215             \o m22 (double)
216             \o m23 (double)
217             \o m24 (double)
218             \o m31 (double)
219             \o m32 (double)
220             \o m33 (double)
221             \o m34 (double)
222             \o m41 (double)
223             \o m42 (double)
224             \o m43 (double)
225             \o m44 (double)
226             \endlist
227     \row \o QPair<T1, T2>
228          \o \list
229             \o first (T1)
230             \o second (T2)
231             \endlist
232     \row \o QPalette
233          \o The disabled, active, and inactive color groups, each of which consists
234             of the following:
235             \list
236             \o foreground (QBrush)
237             \o button (QBrush)
238             \o light (QBrush)
239             \o midlight (QBrush)
240             \o dark (QBrush)
241             \o mid (QBrush)
242             \o text (QBrush)
243             \o brightText (QBrush)
244             \o buttonText (QBrush)
245             \o base (QBrush)
246             \o background (QBrush)
247             \o shadow (QBrush)
248             \o highlight (QBrush)
249             \o highlightedText (QBrush)
250             \o link (QBrush)
251             \o linkVisited (QBrush)
252             \endlist
253     \row \o QPen
254          \o \list
255             \o The pen styles (quint8)
256             \o The pen width (quint16)
257             \o The pen color (QColor)
258             \endlist
259     \row \o QPicture
260          \o \list
261             \o The size of the picture data (quint32)
262             \o The raw bytes of picture data (char)
263             \endlist
264     \row \o QPixmap
265          \o \list
266             \o Save it as a PNG image.
267             \endlist
268     \row \o QPoint
269          \o \list
270             \o The x coordinate (qint32)
271             \o The y coordinate (qint32)
272             \endlist
273     \row \o QQuaternion
274          \o \list
275             \o The scalar component (double)
276             \o The x coordinate (double)
277             \o The y coordinate (double)
278             \o The z coordinate (double)
279             \endlist
280     \row \o QRect
281          \o \list
282             \o left (qint32)
283             \o top (qint32)
284             \o right (qint32)
285             \o bottom (qint32)
286             \endlist
287     \row \o QRegExp
288          \o \list
289             \o The regexp pattern (QString)
290             \o Case sensitivity (quint8)
291             \o Regular expression syntax (quint8)
292             \o Minimal matching (quint8)
293             \endlist
294     \row \o QRegion
295          \o \list
296             \o The size of the data, i.e. 8 + 16 * (number of rectangles) (quint32)
297             \o 10 (qint32)
298             \o The number of rectangles (quint32)
299             \o The rectangles in sequential order (QRect)
300             \endlist
301     \row \o QSize
302          \o \list
303             \o width (qint32)
304             \o height (qint32)
305             \endlist
306     \row \o QString
307          \o \list
308             \o If the string is null: 0xFFFFFFFF (quint32)
309             \o Otherwise: The string length in bytes (quint32) followed by the data in UTF-16
310             \endlist
311     \row \o QTime
312          \o \list
313             \o Milliseconds since midnight (quint32)
314             \endlist
315     \row \o QTransform
316          \o \list
317             \o m11 (double)
318             \o m12 (double)
319             \o m13 (double)
320             \o m21 (double)
321             \o m22 (double)
322             \o m23 (double)
323             \o m31 (double)
324             \o m32 (double)
325             \o m33 (double)
326             \endlist
327     \row \o QUrl
328          \o \list
329             \o Holds an URL (QString)
330             \endlist
331     \row \o QVariant
332          \o \list
333             \o The type of the data (quint32)
334             \o The null flag (qint8)
335             \o The data of the specified type
336             \endlist
337     \row \o QVector2D
338          \o \list
339             \o the x coordinate (double)
340             \o the y coordinate (double)
341             \endlist
342     \row \o QVector3D
343          \o \list
344             \o the x coordinate (double)
345             \o the y coordinate (double)
346             \o the z coordinate (double)
347             \endlist
348     \row \o QVector4D
349          \o \list
350             \o the x coordinate (double)
351             \o the y coordinate (double)
352             \o the z coordinate (double)
353             \o the w coordinate (double)
354             \endlist
355     \row \o QVector<T>
356          \o \list
357             \o The number of items (quint32)
358             \o The items (T)
359             \endlist
360     \endtable
361 */