doc/src/files-and-resources/datastreamformat.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:FDL$
  10 ** GNU Free Documentation License
  11 ** Alternatively, this file may be used under the terms of the GNU Free
  12 ** Documentation License version 1.3 as published by the Free Software
  13 ** Foundation and appearing in the file included in the packaging of
  14 ** this file.
  15 **
  16 ** Other Usage
  17 ** Alternatively, this file may be used in accordance with the terms
  18 ** and conditions contained in a signed written agreement between you
  19 ** and Nokia.
  20 **
  21 **
  22 **
  23 **
  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 */