Contents

• Public Types
• Public Functions
• Detailed Description
• Versioning
• Reading and writing raw binary data
• Reading and writing Qt collection classes
• Reading and writing other Qt classes.

Detailed Description

TheQDataStream class provides serialization of binary data to aQIODevice.

A data stream is a binary stream of encoded information which is 100% independent of the host computer's operating system, CPU or byte order. For example, a data stream that is written by a PC under Windows can be read by a Sun SPARC running Solaris.

You can also use a data stream to read/writeraw unencoded binary data. If you want a "parsing" input stream, seeQTextStream.

TheQDataStream class implements the serialization of C++'s basic data types, likechar,short,int,char *, etc. Serialization of more complex data is accomplished by breaking up the data into primitive units.

A data stream cooperates closely with aQIODevice. AQIODevice represents an input/output medium one can read data from and write data to. TheQFile class is an example of an I/O device.

Example (write binary data to a stream):

QFile file("file.dat");file.open(QIODevice::WriteOnly);QDataStream out(&file);// we will serialize the data into the fileout<<QString("the answer is");// serialize a stringout<< (qint32)42;// serialize an integer

Example (read binary data from a stream):

QFile file("file.dat");file.open(QIODevice::ReadOnly);QDataStream in(&file);// read the data serialized from the fileQString str;qint32 a;in>> str>> a;// extract "the answer is" and 42

Each item written to the stream is written in a predefined binary format that varies depending on the item's type. Supported Qt types includeQBrush,QColor,QDateTime,QFont,QPixmap,QString,QVariant and many others. For the complete list of all Qt types supporting data streaming seeSerializing Qt Data Types.

For integers it is best to always cast to a Qt integer type for writing, and to read back into the same Qt integer type. This ensures that you get integers of the size you want and insulates you from compiler and platform differences.

To take one example, achar * string is written as a 32-bit integer equal to the length of the string including the '\0' byte, followed by all the characters of the string including the '\0' byte. When reading achar * string, 4 bytes are read to create the 32-bit length value, then that many characters for thechar * string including the '\0' terminator are read.

The initial I/O device is usually set in the constructor, but can be changed withsetDevice(). If you've reached the end of the data (or if there is no I/O device set)atEnd() will return true.

Versioning

QDataStream's binary format has evolved since Qt 1.0, and is likely to continue evolving to reflect changes done in Qt. When inputting or outputting complex types, it's very important to make sure that the same version of the stream (version()) is used for reading and writing. If you need both forward and backward compatibility, you can hardcode the version number in the application:

stream.setVersion(QDataStream::Qt_4_0);

If you are producing a new binary data format, such as a file format for documents created by your application, you could use aQDataStream to write the data in a portable format. Typically, you would write a brief header containing a magic string and a version number to give yourself room for future expansion. For example:

QFile file("file.xxx");file.open(QIODevice::WriteOnly);QDataStream out(&file);// Write a header with a "magic number" and a versionout<< (quint32)0xA0B0C0D0;out<< (qint32)123;out.setVersion(QDataStream::Qt_4_0);// Write the dataout<< lots_of_interesting_data;

Then read it in with:

QFile file("file.xxx");file.open(QIODevice::ReadOnly);QDataStream in(&file);// Read and check the headerquint32 magic;in>> magic;if (magic!=0xA0B0C0D0)return XXX_BAD_FILE_FORMAT;// Read the versionqint32 version;in>> version;if (version<100)return XXX_BAD_FILE_TOO_OLD;if (version>123)return XXX_BAD_FILE_TOO_NEW;if (version<=110)    in.setVersion(QDataStream::Qt_3_2);else    in.setVersion(QDataStream::Qt_4_0);// Read the datain>> lots_of_interesting_data;if (version>=120)    in>> data_new_in_XXX_version_1_2;in>> other_interesting_data;

You can select which byte order to use when serializing data. The default setting is big endian (MSB first). Changing it to little endian breaks the portability (unless the reader also changes to little endian). We recommend keeping this setting unless you have special requirements.

Reading and writing raw binary data

You may wish to read/write your own raw binary data to/from the data stream directly. Data may be read from the stream into a preallocatedchar * usingreadRawData(). Similarly data can be written to the stream usingwriteRawData(). Note that any encoding/decoding of the data must be done by you.

A similar pair of functions isreadBytes() andwriteBytes(). These differ from theirraw counterparts as follows:readBytes() reads a quint32 which is taken to be the length of the data to be read, then that number of bytes is read into the preallocatedchar *;writeBytes() writes a quint32 containing the length of the data, followed by the data. Note that any encoding/decoding of the data (apart from the length quint32) must be done by you.

Reading and writing Qt collection classes

The Qt container classes can also be serialized to aQDataStream. These includeQList,QLinkedList,QVector,QSet,QHash, andQMap. The stream operators are declared as non-members of the classes.

Reading and writing other Qt classes.

In addition to the overloaded stream operators documented here, any Qt classes that you might want to serialize to aQDataStream will have appropriate stream operators declared as non-member of the class:

QDataStream&operator<<(QDataStream&,constQXxx&);QDataStream&operator>>(QDataStream&,QXxx&);

For example, here are the stream operators declared as non-members of theQImage class:

QDataStream&operator<< (QDataStream& stream,constQImage& image);QDataStream&operator>> (QDataStream& stream,QImage& image);

To see if your favorite Qt class has similar stream operators defined, check theRelated Non-Members section of the class's documentation page.

Member Type Documentation

enum QDataStream::ByteOrder

The byte order used for reading/writing the data.

enum QDataStream::FloatingPointPrecision

The precision of floating point numbers used for reading/writing the data. This will only have an effect if the version of the data stream isQt_4_6 or higher.

Warning: The floating point precision must be set to the same value on the object that writes and the object that reads the data stream.

See alsosetFloatingPointPrecision() andfloatingPointPrecision().

enum QDataStream::Status

This enum describes the current status of the data stream.

enum QDataStream::Version

This enum provides symbolic synonyms for the data serialization format version numbers.

See alsosetVersion() andversion().

Member Function Documentation

QDataStream::QDataStream()

Constructs a data stream that has no I/O device.

See alsosetDevice().

QDataStream::QDataStream(QIODevice * d)

Constructs a data stream that uses the I/O deviced.

Warning: If you useQSocket orQSocketDevice as the I/O deviced for reading data, you must make sure that enough data is available on the socket for the operation to successfully proceed;QDataStream does not have any means to handle or recover from short-reads.

See alsosetDevice() anddevice().

QDataStream::QDataStream(QByteArray * a,QIODevice::OpenMode mode)

Constructs a data stream that operates on a byte array,a. Themode describes how the device is to be used.

Alternatively, you can useQDataStream(constQByteArray &) if you just want to read from a byte array.

SinceQByteArray is not aQIODevice subclass, internally aQBuffer is created to wrap the byte array.

QDataStream::QDataStream(constQByteArray & a)

Constructs a read-only data stream that operates on byte arraya. UseQDataStream(QByteArray*, int) if you want to write to a byte array.

SinceQByteArray is not aQIODevice subclass, internally aQBuffer is created to wrap the byte array.

[virtual]QDataStream::~QDataStream()

Destroys the data stream.

The destructor will not affect the current I/O device, unless it is an internal I/O device (e.g. aQBuffer) processing aQByteArray passed in theconstructor, in which case the internal I/O device is destroyed.

bool QDataStream::atEnd() const

Returns true if the I/O device has reached the end position (end of the stream or file) or if there is no I/O device set; otherwise returns false.

See alsoQIODevice::atEnd().

ByteOrder QDataStream::byteOrder() const

Returns the current byte order setting -- eitherBigEndian orLittleEndian.

See alsosetByteOrder().

QIODevice * QDataStream::device() const

Returns the I/O device currently set, or 0 if no device is currently set.

See alsosetDevice().

FloatingPointPrecision QDataStream::floatingPointPrecision() const

Returns the floating point precision of the data stream.

This function was introduced in Qt 4.6.

See alsoFloatingPointPrecision andsetFloatingPointPrecision().

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

Reads the buffers from the stream and returns a reference to the stream.

The buffers is allocated usingnew. Destroy it with thedelete[] operator.

Thel parameter is set to the length of the buffer. If the string read is empty,l is set to 0 ands is set to a null pointer.

The serialization format is a quint32 length specifier first, thenl bytes of data.

See alsoreadRawData() andwriteBytes().

int QDataStream::readRawData(char * s,int len)

Reads at mostlen bytes from the stream intos and returns the number of bytes read. If an error occurs, this function returns -1.

The buffers must be preallocated. The data isnot encoded.

See alsoreadBytes(),QIODevice::read(), andwriteRawData().

void QDataStream::resetStatus()

Resets the status of the data stream.

See alsoStatus,status(), andsetStatus().

void QDataStream::setByteOrder(ByteOrder bo)

Sets the serialization byte order tobo.

Thebo parameter can beQDataStream::BigEndian orQDataStream::LittleEndian.

The default setting is big endian. We recommend leaving this setting unless you have special requirements.

See alsobyteOrder().

void QDataStream::setDevice(QIODevice * d)

void QDataStream::setDevice(QIODevice *d)

Sets the I/O device tod, which can be 0 to unset to current I/O device.

See alsodevice().

void QDataStream::setFloatingPointPrecision(FloatingPointPrecision precision)

Sets the floating point precision of the data stream toprecision. If the floating point precision isDoublePrecision and the version of the data stream isQt_4_6 or higher, all floating point numbers will be written and read with 64-bit precision. If the floating point precision isSinglePrecision and the version isQt_4_6 or higher, all floating point numbers will be written and read with 32-bit precision.

For versions prior toQt_4_6, the precision of floating point numbers in the data stream depends on the stream operator called.

The default isDoublePrecision.

Warning: This property must be set to the same value on the object that writes and the object that reads the data stream.

This function was introduced in Qt 4.6.

See alsofloatingPointPrecision().

void QDataStream::setStatus(Status status)

Sets the status of the data stream to thestatus given.

Subsequent calls to setStatus() are ignored untilresetStatus() is called.

See alsoStatus,status(), andresetStatus().

void QDataStream::setVersion(int v)

Sets the version number of the data serialization format tov.

You don'thave to set a version if you are using the current version of Qt, but for your own custom binary formats we recommend that you do; seeVersioning in the Detailed Description.

To accommodate new functionality, the datastream serialization format of some Qt classes has changed in some versions of Qt. If you want to read data that was created by an earlier version of Qt, or write data that can be read by a program that was compiled with an earlier version of Qt, use this function to modify the serialization format used byQDataStream.

TheVersion enum provides symbolic constants for the different versions of Qt. For example:

QDataStream out(file);out.setVersion(QDataStream::Qt_4_0);

See alsoversion() andVersion.

int QDataStream::skipRawData(int len)

Skipslen bytes from the device. Returns the number of bytes actually skipped, or -1 on error.

This is equivalent to callingreadRawData() on a buffer of lengthlen and ignoring the buffer.

This function was introduced in Qt 4.1.

See alsoQIODevice::seek().

Status QDataStream::status() const

Returns the status of the data stream.

See alsoStatus,setStatus(), andresetStatus().

int QDataStream::version() const

Returns the version number of the data serialization format.

See alsosetVersion() andVersion.

QDataStream & QDataStream::writeBytes(constchar * s,uint len)

Writes the length specifierlen and the buffers to the stream and returns a reference to the stream.

Thelen is serialized as a quint32, followed bylen bytes froms. Note that the data isnot encoded.

See alsowriteRawData() andreadBytes().

int QDataStream::writeRawData(constchar * s,int len)

Writeslen bytes froms to the stream. Returns the number of bytes actually written, or -1 on error. The data isnot encoded.

See alsowriteBytes(),QIODevice::write(), andreadRawData().

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

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

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

Writes a boolean value,i, to the stream. Returns a reference to the stream.

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

This is an overloaded function.

Writes an unsigned byte,i, to the stream and returns a reference to the stream.

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

This is an overloaded function.

Writes an unsigned 16-bit integer,i, to the stream and returns a reference to the stream.

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

This is an overloaded function.

Writes a signed 16-bit integer,i, to the stream and returns a reference to the stream.

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

This is an overloaded function.

Writes a signed 32-bit integer,i, to the stream and returns a reference to the stream.

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

This is an overloaded function.

Writes an unsigned 64-bit integer,i, to the stream and returns a reference to the stream.

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

This is an overloaded function.

Writes a signed 64-bit integer,i, to the stream and returns a reference to the stream.

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

This is an overloaded function.

Writes an unsigned integer,i, to the stream as a 32-bit unsigned integer (quint32). Returns a reference to the stream.

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

This is an overloaded function.

Writes a floating point number,f, to the stream using the standard IEEE 754 format. Returns a reference to the stream.

See alsosetFloatingPointPrecision().

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

This is an overloaded function.

Writes a floating point number,f, to the stream using the standard IEEE 754 format. Returns a reference to the stream.

See alsosetFloatingPointPrecision().

QDataStream & QDataStream::operator<<(constchar * s)

This is an overloaded function.

Writes the '\0'-terminated strings to the stream and returns a reference to the stream.

The string is serialized usingwriteBytes().

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

Reads a signed byte from the stream intoi, and returns a reference to the stream.

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

Reads a boolean value from the stream intoi. Returns a reference to the stream.

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

This is an overloaded function.

Reads an unsigned byte from the stream intoi, and returns a reference to the stream.

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

This is an overloaded function.

Reads an unsigned 16-bit integer from the stream intoi, and returns a reference to the stream.

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

This is an overloaded function.

Reads a signed 16-bit integer from the stream intoi, and returns a reference to the stream.

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

This is an overloaded function.

Reads an unsigned 32-bit integer from the stream intoi, and returns a reference to the stream.

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

This is an overloaded function.

Reads a signed 32-bit integer from the stream intoi, and returns a reference to the stream.

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

This is an overloaded function.

Reads an unsigned 64-bit integer from the stream, intoi, and returns a reference to the stream.

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

This is an overloaded function.

Reads a signed 64-bit integer from the stream intoi, and returns a reference to the stream.

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

This is an overloaded function.

Reads a floating point number from the stream intof, using the standard IEEE 754 format. Returns a reference to the stream.

See alsosetFloatingPointPrecision().

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

This is an overloaded function.

Reads a floating point number from the stream intof, using the standard IEEE 754 format. Returns a reference to the stream.

See alsosetFloatingPointPrecision().

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

This is an overloaded function.

Reads the '\0'-terminated strings from the stream and returns a reference to the stream.

Space for the string is allocated usingnew -- the caller must destroy it withdelete[].