1QDataStream(3qt)                                              QDataStream(3qt)
2
3
4

NAME

6       QDataStream - Serialization of binary data to a QIODevice
7

SYNOPSIS

9       All the functions in this class are reentrant when Qt is built with
10       thread support.</p>
11
12       #include <qdatastream.h>
13
14   Public Members
15       QDataStream ()
16       QDataStream ( QIODevice * d )
17       QDataStream ( QByteArray a, int mode )
18       virtual ~QDataStream ()
19       QIODevice * device () const
20       void setDevice ( QIODevice * d )
21       void unsetDevice ()
22       bool atEnd () const
23       bool eof () const  (obsolete)
24       enum ByteOrder { BigEndian, LittleEndian }
25       int byteOrder () const
26       void setByteOrder ( int bo )
27       bool isPrintableData () const
28       void setPrintableData ( bool enable )
29       int version () const
30       void setVersion ( int v )
31       QDataStream & operator>> ( Q_INT8 & i )
32       QDataStream & operator>> ( Q_UINT8 & i )
33       QDataStream & operator>> ( Q_INT16 & i )
34       QDataStream & operator>> ( Q_UINT16 & i )
35       QDataStream & operator>> ( Q_INT32 & i )
36       QDataStream & operator>> ( Q_UINT32 & i )
37       QDataStream & operator>> ( Q_INT64 & i )
38       QDataStream & operator>> ( Q_UINT64 & i )
39       QDataStream & operator>> ( Q_LONG & i )
40       QDataStream & operator>> ( Q_ULONG & i )
41       QDataStream & operator>> ( float & f )
42       QDataStream & operator>> ( double & f )
43       QDataStream & operator>> ( char *& s )
44       QDataStream & operator<< ( Q_INT8 i )
45       QDataStream & operator<< ( Q_UINT8 i )
46       QDataStream & operator<< ( Q_INT16 i )
47       QDataStream & operator<< ( Q_UINT16 i )
48       QDataStream & operator<< ( Q_INT32 i )
49       QDataStream & operator<< ( Q_UINT32 i )
50       QDataStream & operator<< ( Q_INT64 i )
51       QDataStream & operator<< ( Q_UINT64 i )
52       QDataStream & operator<< ( Q_LONG i )
53       QDataStream & operator<< ( Q_ULONG i )
54       QDataStream & operator<< ( float f )
55       QDataStream & operator<< ( double f )
56       QDataStream & operator<< ( const char * s )
57       QDataStream & readBytes ( char *& s, uint & l )
58       QDataStream & readRawBytes ( char * s, uint len )
59       QDataStream & writeBytes ( const char * s, uint len )
60       QDataStream & writeRawBytes ( const char * s, uint len )
61

DESCRIPTION

63       The QDataStream class provides serialization of binary data to a
64       QIODevice.
65
66       A data stream is a binary stream of encoded information which is 100%
67       independent of the host computer's operating system, CPU or byte order.
68       For example, a data stream that is written by a PC under Windows can be
69       read by a Sun SPARC running Solaris.
70
71       You can also use a data stream to read/write raw unencoded binary data.
72       If you want a "parsing" input stream, see QTextStream.
73
74       The QDataStream class implements the serialization of C++'s basic data
75       types, like char, short, int, char*, etc. Serialization of more complex
76       data is accomplished by breaking up the data into primitive units.
77
78       A data stream cooperates closely with a QIODevice. A QIODevice
79       represents an input/output medium one can read data from and write data
80       to. The QFile class is an example of an IO device.
81
82       Example (write binary data to a stream):
83
84           QFile file( "file.dat" );
85           file.open( IO_WriteOnly );
86           QDataStream stream( &file ); // we will serialize the data into the file
87           stream << "the answer is";   // serialize a string
88           stream << (Q_INT32)42;       // serialize an integer
89
90       Example (read binary data from a stream):
91
92           QFile file( "file.dat" );
93           file.open( IO_ReadOnly );
94           QDataStream stream( &file );  // read the data serialized from the file
95           QString str;
96           Q_INT32 a;
97           stream >> str >> a;           // extract "the answer is" and 42
98
99       Each item written to the stream is written in a predefined binary
100       format that varies depending on the item's type. Supported Qt types
101       include QBrush, QColor, QDateTime, QFont, QPixmap, QString, QVariant
102       and many others. For the complete list of all Qt types supporting data
103       streaming see the Format of the QDataStream operators.
104
105       For integers it is best to always cast to a Qt integer type for
106       writing, and to read back into the same Qt integer type. This ensures
107       that you get integers of the size you want and insulates you from
108       compiler and platform differences.
109
110       To take one example, a char* string is written as a 32-bit integer
111       equal to the length of the string including the NUL byte ('&#92;0'),
112       followed by all the characters of the string including the NUL byte.
113       When reading a char* string, 4 bytes are read to create the 32-bit
114       length value, then that many characters for the char* string including
115       the NUL are read.
116
117       The initial IODevice is usually set in the constructor, but can be
118       changed with setDevice(). If you've reached the end of the data (or if
119       there is no IODevice set) atEnd() will return TRUE.
120
121       If you want the data to be compatible with an earlier version of Qt use
122       setVersion().
123
124       If you want the data to be human-readable, e.g. for debugging, you can
125       set the data stream into printable data mode with setPrintableData().
126       The data is then written slower, in a bloated but human readable
127       format.
128
129       If you are producing a new binary data format, such as a file format
130       for documents created by your application, you could use a QDataStream
131       to write the data in a portable format. Typically, you would write a
132       brief header containing a magic string and a version number to give
133       yourself room for future expansion. For example:
134
135           QFile file( "file.xxx" );
136           file.open( IO_WriteOnly );
137           QDataStream stream( &file );
138           // Write a header with a "magic number" and a version
139           stream << (Q_UINT32)0xA0B0C0D0;
140           stream << (Q_INT32)123;
141           // Write the data
142           stream << [lots of interesting data]
143
144       Then read it in with:
145
146           QFile file( "file.xxx" );
147           file.open( IO_ReadOnly );
148           QDataStream stream( &file );
149           // Read and check the header
150           Q_UINT32 magic;
151           stream >> magic;
152           if ( magic != 0xA0B0C0D0 )
153               return XXX_BAD_FILE_FORMAT;
154           // Read the version
155           Q_INT32 version;
156           stream >> version;
157           if ( version < 100 )
158               return XXX_BAD_FILE_TOO_OLD;
159           if ( version > 123 )
160               return XXX_BAD_FILE_TOO_NEW;
161           if ( version <= 110 )
162               stream.setVersion(1);
163           // Read the data
164           stream >> [lots of interesting data];
165           if ( version > 120 )
166               stream >> [data new in XXX version 1.2];
167           stream >> [other interesting data];
168
169       You can select which byte order to use when serializing data. The
170       default setting is big endian (MSB first). Changing it to little endian
171       breaks the portability (unless the reader also changes to little
172       endian). We recommend keeping this setting unless you have special
173       requirements.
174

Reading and writing raw binary data

176       You may wish to read/write your own raw binary data to/from the data
177       stream directly. Data may be read from the stream into a preallocated
178       char* using readRawBytes(). Similarly data can be written to the stream
179       using writeRawBytes(). Notice that any encoding/decoding of the data
180       must be done by you.
181
182       A similar pair of functions is readBytes() and writeBytes(). These
183       differ from their raw counterparts as follows: readBytes() reads a
184       Q_UINT32 which is taken to be the length of the data to be read, then
185       that number of bytes is read into the preallocated char*; writeBytes()
186       writes a Q_UINT32 containing the length of the data, followed by the
187       data. Notice that any encoding/decoding of the data (apart from the
188       length Q_UINT32) must be done by you.
189
190       See also QTextStream, QVariant, and Input/Output and Networking.
191
192   Member Type Documentation

QDataStream::ByteOrder

194       The byte order used for reading/writing the data.
195
196       QDataStream::BigEndian - the default
197
198       QDataStream::LittleEndian
199

MEMBER FUNCTION DOCUMENTATION

QDataStream::QDataStream ()

202       Constructs a data stream that has no IO device.
203
204       See also setDevice().
205

QDataStream::QDataStream ( QIODevice * d )

207       Constructs a data stream that uses the IO device d.
208
209       Warning: If you use QSocket or QSocketDevice as the IO device d for
210       reading data, you must make sure that enough data is available on the
211       socket for the operation to successfully proceed; QDataStream does not
212       have any means to handle or recover from short-reads.
213
214       See also setDevice() and device().
215

QDataStream::QDataStream ( QByteArray a, int mode )

217       Constructs a data stream that operates on a byte array, a, through an
218       internal QBuffer device. The mode is a QIODevice::mode(), usually
219       either IO_ReadOnly or IO_WriteOnly.
220
221       Example:
222
223           static char bindata[] = { 231, 1, 44, ... };
224           QByteArray a;
225           a.setRawData( bindata, sizeof(bindata) );   // a points to bindata
226           QDataStream stream( a, IO_ReadOnly );       // open on a's data
227           stream >> [something];                      // read raw bindata
228           a.resetRawData( bindata, sizeof(bindata) ); // finished
229
230       The QByteArray::setRawData() function is not for the inexperienced.
231

QDataStream::~QDataStream () [virtual]

233       Destroys the data stream.
234
235       The destructor will not affect the current IO device, unless it is an
236       internal IO device processing a QByteArray passed in the constructor,
237       in which case the internal IO device is destroyed.
238

bool QDataStream::atEnd () const

240       Returns TRUE if the IO device has reached the end position (end of the
241       stream or file) or if there is no IO device set; otherwise returns
242       FALSE, i.e. if the current position of the IO device is before the end
243       position.
244
245       See also QIODevice::atEnd().
246

int QDataStream::byteOrder () const

248       Returns the current byte order setting -- either BigEndian or
249       LittleEndian.
250
251       See also setByteOrder().
252

QIODevice * QDataStream::device () const

254       Returns the IO device currently set.
255
256       See also setDevice() and unsetDevice().
257

bool QDataStream::eof () const

259       This function is obsolete. It is provided to keep old source working.
260       We strongly advise against using it in new code.
261
262       Returns TRUE if the IO device has reached the end position (end of
263       stream or file) or if there is no IO device set.
264
265       Returns FALSE if the current position of the read/write head of the IO
266       device is somewhere before the end position.
267
268       See also QIODevice::atEnd().
269

bool QDataStream::isPrintableData () const

271       Returns TRUE if the printable data flag has been set; otherwise returns
272       FALSE.
273
274       See also setPrintableData().
275

QDataStream & QDataStream::operator<< ( Q_INT8 i )

277       Writes a signed byte, i, to the stream and returns a reference to the
278       stream.
279

QDataStream & QDataStream::operator<< ( Q_UINT8 i )

281       This is an overloaded member function, provided for convenience. It
282       behaves essentially like the above function.
283
284       Writes an unsigned byte, i, to the stream and returns a reference to
285       the stream.
286

QDataStream & QDataStream::operator<< ( Q_INT16 i )

288       This is an overloaded member function, provided for convenience. It
289       behaves essentially like the above function.
290
291       Writes a signed 16-bit integer, i, to the stream and returns a
292       reference to the stream.
293

QDataStream & QDataStream::operator<< ( Q_UINT16 i )

295       This is an overloaded member function, provided for convenience. It
296       behaves essentially like the above function.
297
298       Writes an unsigned 16-bit integer, i, to the stream and returns a
299       reference to the stream.
300

QDataStream & QDataStream::operator<< ( Q_INT32 i )

302       This is an overloaded member function, provided for convenience. It
303       behaves essentially like the above function.
304
305       Writes a signed 32-bit integer, i, to the stream and returns a
306       reference to the stream.
307

QDataStream & QDataStream::operator<< ( Q_UINT32 i )

309       This is an overloaded member function, provided for convenience. It
310       behaves essentially like the above function.
311
312       Writes an unsigned integer, i, to the stream as a 32-bit unsigned
313       integer (Q_UINT32). Returns a reference to the stream.
314

QDataStream & QDataStream::operator<< ( Q_INT64 i )

316       This is an overloaded member function, provided for convenience. It
317       behaves essentially like the above function.
318
319       Writes a signed 64-bit integer, i, to the stream and returns a
320       reference to the stream.
321

QDataStream & QDataStream::operator<< ( Q_UINT64 i )

323       This is an overloaded member function, provided for convenience. It
324       behaves essentially like the above function.
325
326       Writes an unsigned 64-bit integer, i, to the stream and returns a
327       reference to the stream.
328

QDataStream & QDataStream::operator<< ( Q_LONG i )

330       This is an overloaded member function, provided for convenience. It
331       behaves essentially like the above function.
332
333       Writes a signed integer i, of the system's word length, to the stream
334       and returns a reference to the stream.
335

QDataStream & QDataStream::operator<< ( Q_ULONG i )

337       This is an overloaded member function, provided for convenience. It
338       behaves essentially like the above function.
339
340       Writes an unsigned integer i, of the system's word length, to the
341       stream and returns a reference to the stream.
342

QDataStream & QDataStream::operator<< ( float f )

344       This is an overloaded member function, provided for convenience. It
345       behaves essentially like the above function.
346
347       Writes a 32-bit floating point number, f, to the stream using the
348       standard IEEE754 format. Returns a reference to the stream.
349

QDataStream & QDataStream::operator<< ( double f )

351       This is an overloaded member function, provided for convenience. It
352       behaves essentially like the above function.
353
354       Writes a 64-bit floating point number, f, to the stream using the
355       standard IEEE754 format. Returns a reference to the stream.
356

QDataStream & QDataStream::operator<< ( const char * s )

358       This is an overloaded member function, provided for convenience. It
359       behaves essentially like the above function.
360
361       Writes the '&#92;0'-terminated string s to the stream and returns a
362       reference to the stream.
363
364       The string is serialized using writeBytes().
365

QDataStream & QDataStream::operator>> ( Q_INT8 & i )

367       Reads a signed byte from the stream into i, and returns a reference to
368       the stream.
369

QDataStream & QDataStream::operator>> ( Q_UINT8 & i )

371       This is an overloaded member function, provided for convenience. It
372       behaves essentially like the above function.
373
374       Reads an unsigned byte from the stream into i, and returns a reference
375       to the stream.
376

QDataStream & QDataStream::operator>> ( Q_INT16 & i )

378       This is an overloaded member function, provided for convenience. It
379       behaves essentially like the above function.
380
381       Reads a signed 16-bit integer from the stream into i, and returns a
382       reference to the stream.
383

QDataStream & QDataStream::operator>> ( Q_UINT16 & i )

385       This is an overloaded member function, provided for convenience. It
386       behaves essentially like the above function.
387
388       Reads an unsigned 16-bit integer from the stream into i, and returns a
389       reference to the stream.
390

QDataStream & QDataStream::operator>> ( Q_INT32 & i )

392       This is an overloaded member function, provided for convenience. It
393       behaves essentially like the above function.
394
395       Reads a signed 32-bit integer from the stream into i, and returns a
396       reference to the stream.
397

QDataStream & QDataStream::operator>> ( Q_UINT32 & i )

399       This is an overloaded member function, provided for convenience. It
400       behaves essentially like the above function.
401
402       Reads an unsigned 32-bit integer from the stream into i, and returns a
403       reference to the stream.
404

QDataStream & QDataStream::operator>> ( Q_INT64 & i )

406       This is an overloaded member function, provided for convenience. It
407       behaves essentially like the above function.
408
409       Reads a signed 64-bit integer from the stream into i, and returns a
410       reference to the stream.
411

QDataStream & QDataStream::operator>> ( Q_UINT64 & i )

413       This is an overloaded member function, provided for convenience. It
414       behaves essentially like the above function.
415
416       Reads an unsigned 64-bit integer from the stream, into i, and returns a
417       reference to the stream.
418

QDataStream & QDataStream::operator>> ( Q_LONG & i )

420       This is an overloaded member function, provided for convenience. It
421       behaves essentially like the above function.
422
423       Reads a signed integer of the system's word length from the stream into
424       i, and returns a reference to the stream.
425

QDataStream & QDataStream::operator>> ( Q_ULONG & i )

427       This is an overloaded member function, provided for convenience. It
428       behaves essentially like the above function.
429
430       Reads an unsigned integer of the system's word length from the stream,
431       into i, and returns a reference to the stream.
432

QDataStream & QDataStream::operator>> ( float & f )

434       This is an overloaded member function, provided for convenience. It
435       behaves essentially like the above function.
436
437       Reads a 32-bit floating point number from the stream into f, using the
438       standard IEEE754 format. Returns a reference to the stream.
439

QDataStream & QDataStream::operator>> ( double & f )

441       This is an overloaded member function, provided for convenience. It
442       behaves essentially like the above function.
443
444       Reads a 64-bit floating point number from the stream into f, using the
445       standard IEEE754 format. Returns a reference to the stream.
446

QDataStream & QDataStream::operator>> ( char *& s )

448       This is an overloaded member function, provided for convenience. It
449       behaves essentially like the above function.
450
451       Reads the '&#92;0'-terminated string s from the stream and returns a
452       reference to the stream.
453
454       Space for the string is allocated using new -- the caller must destroy
455       it with delete[].
456

QDataStream & QDataStream::readBytes ( char *& s, uint & l )

458       Reads the buffer s from the stream and returns a reference to the
459       stream.
460
461       The buffer s is allocated using new. Destroy it with the delete[]
462       operator. If the length is zero or s cannot be allocated, s is set to
463       0.
464
465       The l parameter will be set to the length of the buffer.
466
467       The serialization format is a Q_UINT32 length specifier first, then l
468       bytes of data. Note that the data is not encoded.
469
470       See also readRawBytes() and writeBytes().
471

QDataStream & QDataStream::readRawBytes ( char * s, uint len )

473       Reads len bytes from the stream into s and returns a reference to the
474       stream.
475
476       The buffer s must be preallocated. The data is not encoded.
477
478       See also readBytes(), QIODevice::readBlock(), and writeRawBytes().
479

void QDataStream::setByteOrder ( int bo )

481       Sets the serialization byte order to bo.
482
483       The bo parameter can be QDataStream::BigEndian or
484       QDataStream::LittleEndian.
485
486       The default setting is big endian. We recommend leaving this setting
487       unless you have special requirements.
488
489       See also byteOrder().
490

void QDataStream::setDevice ( QIODevice * d )

492       void QDataStream::setDevice(QIODevice *d )
493
494       Sets the IO device to d.
495
496       See also device() and unsetDevice().
497

void QDataStream::setPrintableData ( bool enable )

499       If enable is TRUE, data will be output in a human readable format. If
500       enable is FALSE, data will be output in a binary format.
501
502       If enable is TRUE, the write functions will generate output that
503       consists of printable characters (7 bit ASCII). This output will
504       typically be a lot larger than the default binary output, and
505       consequently slower to write.
506
507       We recommend only enabling printable data for debugging purposes.
508

void QDataStream::setVersion ( int v )

510       Sets the version number of the data serialization format to v.
511
512       You don't need to set a version if you are using the current version of
513       Qt.
514
515       In order to accommodate new functionality, the datastream serialization
516       format of some Qt classes has changed in some versions of Qt. If you
517       want to read data that was created by an earlier version of Qt, or
518       write data that can be read by a program that was compiled with an
519       earlier version of Qt, use this function to modify the serialization
520       format of QDataStream.
521
522       <center>.nf
523
524       </center>
525
526       See also version().
527

void QDataStream::unsetDevice ()

529       Unsets the IO device. This is the same as calling setDevice( 0 ).
530
531       See also device() and setDevice().
532

int QDataStream::version () const

534       Returns the version number of the data serialization format. In Qt 3.1,
535       this number is 5.
536
537       See also setVersion().
538

QDataStream & QDataStream::writeBytes ( const char * s, uint len )

540       Writes the length specifier len and the buffer s to the stream and
541       returns a reference to the stream.
542
543       The len is serialized as a Q_UINT32, followed by len bytes from s. Note
544       that the data is not encoded.
545
546       See also writeRawBytes() and readBytes().
547

QDataStream & QDataStream::writeRawBytes ( const char * s, uint len )

549       Writes len bytes from s to the stream and returns a reference to the
550       stream. The data is not encoded.
551
552       See also writeBytes(), QIODevice::writeBlock(), and readRawBytes().
553
554

SEE ALSO

556       http://doc.trolltech.com/qdatastream.html
557       http://www.trolltech.com/faq/tech.html
558
560       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
561       license file included in the distribution for a complete license
562       statement.
563

AUTHOR

565       Generated automatically from the source code.
566

BUGS

568       If you find a bug in Qt, please report it as described in
569       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
570       help you. Thank you.
571
572       The definitive Qt documentation is provided in HTML format; it is
573       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
574       web browser. This man page is provided as a convenience for those users
575       who prefer man pages, although this format is not officially supported
576       by Trolltech.
577
578       If you find errors in this manual page, please report them to qt-
579       bugs@trolltech.com.  Please include the name of the manual page
580       (qdatastream.3qt) and the Qt version (3.3.8).
581
582
583
584Trolltech AS                    2 February 2007               QDataStream(3qt)
Impressum