1QDataStream(3qt) QDataStream(3qt)
2
6 QDataStream - Serialization of binary data to a QIODevice
7
9 All the functions in this class are reentrant when Qt is built with
10 thread support.</p>
11 #include <qdatastream.h>
13 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
63 The QDataStream class provides serialization of binary data to a
64 QIODevice.
65 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 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 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 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 Example (write binary data to a stream):
83 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 Example (read binary data from a stream):
91 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 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 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 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 ('\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 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 If you want the data to be compatible with an earlier version of Qt use
122 setVersion().
123 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 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 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 Then read it in with:
145 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 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
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 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 See also QTextStream, QVariant, and Input/Output and Networking.
191 Member Type Documentation
194 The byte order used for reading/writing the data.
195 QDataStream::BigEndian - the default
197 QDataStream::LittleEndian
199
202 Constructs a data stream that has no IO device.
203 See also setDevice().
205
207 Constructs a data stream that uses the IO device d.
208 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 See also setDevice() and device().
215
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 Example:
222 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 The QByteArray::setRawData() function is not for the inexperienced.
231
233 Destroys the data stream.
234 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
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 See also QIODevice::atEnd().
246
248 Returns the current byte order setting -- either BigEndian or
249 LittleEndian.
250 See also setByteOrder().
252
254 Returns the IO device currently set.
255 See also setDevice() and unsetDevice().
257
259 This function is obsolete. It is provided to keep old source working.
260 We strongly advise against using it in new code.
261 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 Returns FALSE if the current position of the read/write head of the IO
266 device is somewhere before the end position.
267 See also QIODevice::atEnd().
269
271 Returns TRUE if the printable data flag has been set; otherwise returns
272 FALSE.
273 See also setPrintableData().
275
277 Writes a signed byte, i, to the stream and returns a reference to the
278 stream.
279
281 This is an overloaded member function, provided for convenience. It
282 behaves essentially like the above function.
283 Writes an unsigned byte, i, to the stream and returns a reference to
285 the stream.
286
288 This is an overloaded member function, provided for convenience. It
289 behaves essentially like the above function.
290 Writes a signed 16-bit integer, i, to the stream and returns a
292 reference to the stream.
293
295 This is an overloaded member function, provided for convenience. It
296 behaves essentially like the above function.
297 Writes an unsigned 16-bit integer, i, to the stream and returns a
299 reference to the stream.
300
302 This is an overloaded member function, provided for convenience. It
303 behaves essentially like the above function.
304 Writes a signed 32-bit integer, i, to the stream and returns a
306 reference to the stream.
307
309 This is an overloaded member function, provided for convenience. It
310 behaves essentially like the above function.
311 Writes an unsigned integer, i, to the stream as a 32-bit unsigned
313 integer (Q_UINT32). Returns a reference to the stream.
314
316 This is an overloaded member function, provided for convenience. It
317 behaves essentially like the above function.
318 Writes a signed 64-bit integer, i, to the stream and returns a
320 reference to the stream.
321
323 This is an overloaded member function, provided for convenience. It
324 behaves essentially like the above function.
325 Writes an unsigned 64-bit integer, i, to the stream and returns a
327 reference to the stream.
328
330 This is an overloaded member function, provided for convenience. It
331 behaves essentially like the above function.
332 Writes a signed integer i, of the system's word length, to the stream
334 and returns a reference to the stream.
335
337 This is an overloaded member function, provided for convenience. It
338 behaves essentially like the above function.
339 Writes an unsigned integer i, of the system's word length, to the
341 stream and returns a reference to the stream.
342
344 This is an overloaded member function, provided for convenience. It
345 behaves essentially like the above function.
346 Writes a 32-bit floating point number, f, to the stream using the
348 standard IEEE754 format. Returns a reference to the stream.
349
351 This is an overloaded member function, provided for convenience. It
352 behaves essentially like the above function.
353 Writes a 64-bit floating point number, f, to the stream using the
355 standard IEEE754 format. Returns a reference to the stream.
356
358 This is an overloaded member function, provided for convenience. It
359 behaves essentially like the above function.
360 Writes the '\0'-terminated string s to the stream and returns a
362 reference to the stream.
363 The string is serialized using writeBytes().
365
367 Reads a signed byte from the stream into i, and returns a reference to
368 the stream.
369
371 This is an overloaded member function, provided for convenience. It
372 behaves essentially like the above function.
373 Reads an unsigned byte from the stream into i, and returns a reference
375 to the stream.
376
378 This is an overloaded member function, provided for convenience. It
379 behaves essentially like the above function.
380 Reads a signed 16-bit integer from the stream into i, and returns a
382 reference to the stream.
383
385 This is an overloaded member function, provided for convenience. It
386 behaves essentially like the above function.
387 Reads an unsigned 16-bit integer from the stream into i, and returns a
389 reference to the stream.
390
392 This is an overloaded member function, provided for convenience. It
393 behaves essentially like the above function.
394 Reads a signed 32-bit integer from the stream into i, and returns a
396 reference to the stream.
397
399 This is an overloaded member function, provided for convenience. It
400 behaves essentially like the above function.
401 Reads an unsigned 32-bit integer from the stream into i, and returns a
403 reference to the stream.
404
406 This is an overloaded member function, provided for convenience. It
407 behaves essentially like the above function.
408 Reads a signed 64-bit integer from the stream into i, and returns a
410 reference to the stream.
411
413 This is an overloaded member function, provided for convenience. It
414 behaves essentially like the above function.
415 Reads an unsigned 64-bit integer from the stream, into i, and returns a
417 reference to the stream.
418
420 This is an overloaded member function, provided for convenience. It
421 behaves essentially like the above function.
422 Reads a signed integer of the system's word length from the stream into
424 i, and returns a reference to the stream.
425
427 This is an overloaded member function, provided for convenience. It
428 behaves essentially like the above function.
429 Reads an unsigned integer of the system's word length from the stream,
431 into i, and returns a reference to the stream.
432
434 This is an overloaded member function, provided for convenience. It
435 behaves essentially like the above function.
436 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
441 This is an overloaded member function, provided for convenience. It
442 behaves essentially like the above function.
443 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
448 This is an overloaded member function, provided for convenience. It
449 behaves essentially like the above function.
450 Reads the '\0'-terminated string s from the stream and returns a
452 reference to the stream.
453 Space for the string is allocated using new -- the caller must destroy
455 it with delete[].
456
458 Reads the buffer s from the stream and returns a reference to the
459 stream.
460 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 The l parameter will be set to the length of the buffer.
466 The serialization format is a Q_UINT32 length specifier first, then l
468 bytes of data. Note that the data is not encoded.
469 See also readRawBytes() and writeBytes().
471
473 Reads len bytes from the stream into s and returns a reference to the
474 stream.
475 The buffer s must be preallocated. The data is not encoded.
477 See also readBytes(), QIODevice::readBlock(), and writeRawBytes().
479
481 Sets the serialization byte order to bo.
482 The bo parameter can be QDataStream::BigEndian or
484 QDataStream::LittleEndian.
485 The default setting is big endian. We recommend leaving this setting
487 unless you have special requirements.
488 See also byteOrder().
490
492 void QDataStream::setDevice(QIODevice *d )
493 Sets the IO device to d.
495 See also device() and unsetDevice().
497
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 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 We recommend only enabling printable data for debugging purposes.
508
510 Sets the version number of the data serialization format to v.
511 You don't need to set a version if you are using the current version of
513 Qt.
514 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 <center>.nf
523 </center>
525 See also version().
527
529 Unsets the IO device. This is the same as calling setDevice( 0 ).
530 See also device() and setDevice().
532
534 Returns the version number of the data serialization format. In Qt 3.1,
535 this number is 5.
536 See also setVersion().
538
540 Writes the length specifier len and the buffer s to the stream and
541 returns a reference to the stream.
542 The len is serialized as a Q_UINT32, followed by len bytes from s. Note
544 that the data is not encoded.
545 See also writeRawBytes() and readBytes().
547
549 Writes len bytes from s to the stream and returns a reference to the
550 stream. The data is not encoded.
551 See also writeBytes(), QIODevice::writeBlock(), and readRawBytes().
553
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
565 Generated automatically from the source code.
566
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 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 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).
581Trolltech AS 2 February 2007 QDataStream(3qt)