QDataStream Class

The QDataStream class provides serialization of binary data to a QIODevice. More…

List of all members, including inherited members

Public Types

Public Functions

Detailed Description

A data stream is a binary stream of encoded information that is independent of the host's operating system, CPU and byte order. The format is compatible with Qt's QDataStream: numbers are big-endian by default, a QString is written as UTF-16 code units behind a byte-length prefix, and a null QString or QByteArray is written as the length 0xFFFFFFFF.

Write values with << and read them back, in the same order, with >>:

QByteArray bytes;
QDataStream out(&bytes, QIODevice::WriteOnly);
out << qint32(42) << QString("text");

QDataStream in(bytes);
qint32 number;
QString text;
in >> number >> text;

Read and write errors are recorded in status() instead of being reported by return values. Reading a QList, QMap or QHash clears the container if an error occurs. Enumerations are streamed as their underlying integer type.

See also QTextStream, QIODevice, QBuffer and QFile.

Differences from Qt

Member Type Documentation

enum QDataStream::ByteOrder

Describes the byte order used to encode multi-byte numbers.

enum QDataStream::FloatingPointPrecision

Selects the precision of floating-point values in the stream, for versions Qt_4_6 and later.

enum QDataStream::Status

Describes the state of the stream.

enum QDataStream::Version

Selects the version of the stream format, which determines how some types are encoded. Streams default to Qt_DefaultCompiledVersion. The names are those of the Qt release that introduced the format; versions that share a format share a value.

Member Function Documentation

QDataStream::QDataStream()

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

See also setDevice().

[explicit] QDataStream::QDataStream(QIODevice *d)

Constructs a data stream that uses the I/O device d. The stream does not take ownership of the device.

See also setDevice() and device().

QDataStream::QDataStream(QByteArray *array, QIODeviceBase::OpenMode mode)

Constructs a data stream that operates on the byte array array, which must outlive the stream. The stream owns an internal QBuffer opened with the given mode (QIODevice::ReadOnly, QIODevice::WriteOnly or QIODevice::ReadWrite). Written data is stored in array.

See also QBuffer.

[explicit] QDataStream::QDataStream(const QByteArray &data)

Constructs a read-only data stream that operates on a copy of data.

QDataStream::~QDataStream()

Destroys the data stream. Any device given to the constructor or to setDevice() is left open; an internal buffer created by the byte array constructors is released.

void QDataStream::abortTransaction()

Aborts a read transaction because the data is corrupt. Sets the status to ReadCorruptData, and for the outermost transaction commits the device transaction, so that the bad data is not read again.

This function was introduced in 5.7.

See also startTransaction() and rollbackTransaction().

bool QDataStream::atEnd() const

Returns true if the I/O device has reached the end position, or if there is no device set; otherwise returns false.

See also QIODevice::atEnd().

ByteOrder QDataStream::byteOrder() const

Returns the current byte order setting, which is BigEndian unless changed.

See also setByteOrder().

bool QDataStream::commitTransaction()

Completes a read transaction. Returns true if no read error occurred during the transaction; otherwise returns false.

For the outermost transaction, if the status is ReadPastEnd the device transaction is rolled back, so that the data is read again later; otherwise it is committed. An inner transaction only reports the status.

This function was introduced in 5.7.

See also startTransaction() and rollbackTransaction().

QIODevice * QDataStream::device() const

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

See also setDevice().

FloatingPointPrecision QDataStream::floatingPointPrecision() const

Returns the floating-point precision of the stream.

See also FloatingPointPrecision and setFloatingPointPrecision().

bool QDataStream::isDeviceTransactionStarted() const

Returns true if a read transaction is in progress on the stream's device; otherwise returns false.

This function was introduced in 5.7.

See also QIODevice::isTransactionStarted().

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

Writes a signed byte v to the stream and returns a reference to the stream. If the data cannot be written, the status is set to WriteFailed.

See also status().

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

This is an overloaded function.

Writes an unsigned byte v to the stream.

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

This is an overloaded function.

Writes a signed 16-bit integer v to the stream, using the stream's byte order.

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

This is an overloaded function.

Writes an unsigned 16-bit integer v to the stream, using the stream's byte order.

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

This is an overloaded function.

Writes a signed 32-bit integer v to the stream, using the stream's byte order.

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

This is an overloaded function.

Writes an unsigned 32-bit integer v to the stream, using the stream's byte order.

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

This is an overloaded function.

Writes a signed 64-bit integer v to the stream, using the stream's byte order.

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

This is an overloaded function.

Writes an unsigned 64-bit integer v to the stream, using the stream's byte order.

QDataStream & QDataStream::operator<<(long v)

This is an overloaded function.

Writes the long v to the stream as a signed 64-bit integer, whatever the size of long is on the platform. An Nt addition: Qt has no operators for long, so that a std::size_t cannot be written there without a cast.

QDataStream & QDataStream::operator<<(unsigned long v)

This is an overloaded function.

Writes the unsigned long v to the stream as a 64-bit integer. An Nt addition.

QDataStream & QDataStream::operator<<(char v)

This is an overloaded function.

Writes the character v to the stream as a single byte.

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

This is an overloaded function.

Writes the boolean v to the stream as a single byte, 0 or 1.

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

This is an overloaded function.

Writes the floating-point value v to the stream. With a version of Qt_4_6 or later and the default double precision, it is written as a 64-bit value.

See also setFloatingPointPrecision().

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

This is an overloaded function.

Writes the floating-point value v to the stream. With single precision and a version of Qt_4_6 or later, it is written as a 32-bit value.

See also setFloatingPointPrecision().

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

This is an overloaded function.

Writes the null-terminated string s to the stream as a 32-bit length, which includes the terminating null byte, followed by the bytes. A null pointer is written as a length of 0.

See also writeBytes().

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

Reads a signed byte from the stream into v and returns a reference to the stream. If the data cannot be read, v is set to 0 and the status is set to ReadPastEnd.

See also status().

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

This is an overloaded function.

Reads an unsigned byte from the stream into v.

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

This is an overloaded function.

Reads a signed 16-bit integer from the stream into v, using the stream's byte order.

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

This is an overloaded function.

Reads an unsigned 16-bit integer from the stream into v, using the stream's byte order.

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

This is an overloaded function.

Reads a signed 32-bit integer from the stream into v, using the stream's byte order.

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

This is an overloaded function.

Reads an unsigned 32-bit integer from the stream into v, using the stream's byte order.

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

This is an overloaded function.

Reads a signed 64-bit integer from the stream into v, using the stream's byte order.

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

This is an overloaded function.

Reads an unsigned 64-bit integer from the stream into v, using the stream's byte order.

QDataStream & QDataStream::operator>>(long &v)

This is an overloaded function.

Reads a 64-bit integer from the stream into v, a long, which is how operator<<(long) writes one on every platform. An Nt addition: Qt has no operators for long.

QDataStream & QDataStream::operator>>(unsigned long &v)

This is an overloaded function.

Reads a 64-bit integer from the stream into v, an unsigned long. An Nt addition.

QDataStream & QDataStream::operator>>(char &v)

This is an overloaded function.

Reads a byte from the stream into the character v.

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

This is an overloaded function.

Reads a boolean from the stream into v. A byte other than 0 is read as true.

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

This is an overloaded function.

Reads a floating-point value from the stream into v. With a version of Qt_4_6 or later and the default double precision, a 64-bit value is read and narrowed to float.

See also setFloatingPointPrecision().

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

This is an overloaded function.

Reads a floating-point value from the stream into v. With single precision and a version of Qt_4_6 or later, a 32-bit value is read and widened to double.

See also setFloatingPointPrecision().

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

This is an overloaded function.

Reads a length-prefixed byte string from the stream, allocates a buffer with new char[] for it and stores the pointer in s. The string is null-terminated. The caller must free it with delete[]. s is nullptr if the string is empty or an error occurs.

See also readBytes().

QDataStream & QDataStream::readBytes(char *&s, qint64 &len)

Reads the buffer s from the stream and returns a reference to the stream.

The buffer s is allocated using new char[], and null-terminated. Ownership passes to the caller, who must free it with delete[]. The length of the data, not counting the terminator, is stored in len. Both are cleared to nullptr and 0 if the length is zero or if an error occurs.

The data is expected in the format written by writeBytes().

See also readRawData() and writeBytes().

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

Reads at most len bytes from the stream into s and returns the number of bytes read, or -1 if there is no device or len is negative. If fewer than len bytes could be read, the status is set to ReadPastEnd. The bytes are read as they are, with no length prefix and no byte order conversion.

See also readBytes(), writeRawData() and skipRawData().

void QDataStream::resetStatus()

Resets the status of the data stream to Ok.

See also status() and setStatus().

void QDataStream::rollbackTransaction()

Reverts a read transaction, typically because the data read so far is incomplete. Sets the status to ReadPastEnd unless another error was already recorded. For the outermost transaction, the device transaction is rolled back if the status is ReadPastEnd and committed otherwise.

This function was introduced in 5.7.

See also startTransaction() and abortTransaction().

void QDataStream::setByteOrder(ByteOrder o)

Sets the byte order of the stream to o. It should be set before any data is read or written.

See also byteOrder().

void QDataStream::setDevice(QIODevice *d)

Sets the I/O device to d, which can be nullptr to unset the current device. The stream does not take ownership of d. An internal buffer created by a byte array constructor is released.

See also device().

void QDataStream::setFloatingPointPrecision(FloatingPointPrecision p)

Sets the floating-point precision of the stream to p. It affects stream versions Qt_4_6 and later.

See also FloatingPointPrecision and floatingPointPrecision().

void QDataStream::setStatus(Status status)

Sets the status of the data stream to status, unless an error was already recorded. The first error is kept until resetStatus() is called.

See also Status, status() and resetStatus().

void QDataStream::setVersion(int v)

Sets the version number of the data serialization format to v, one of the Version values.

See also version() and Version.

int QDataStream::skipRawData(int len)

Skips len bytes from the stream and returns the number of bytes actually skipped, or -1 if there is no device or len is negative. If fewer than len bytes could be skipped, the status is set to ReadPastEnd.

See also readRawData().

void QDataStream::startTransaction()

Starts a read transaction on the stream, and on its device for the outermost call. Transactions may be nested; only the outermost one acts on the device.

Use transactions to read a message that may not have arrived completely: read it, then call commitTransaction(). If the data ran out, the read position goes back to where the transaction started, so the message can be read again when more data is available:

in.startTransaction();
QString name;
qint32 value;
in >> name >> value;
if (!in.commitTransaction())
    return; // wait for more data

The outermost call resets the status to Ok.

This function was introduced in 5.7.

See also commitTransaction(), rollbackTransaction() and abortTransaction().

Status QDataStream::status() const

Returns the status of the data stream.

See also Status, setStatus() and resetStatus().

int QDataStream::version() const

Returns the version number of the data serialization format.

See also setVersion() and Version.

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

Writes the length specifier len and the buffer s to the stream and returns a reference to the stream.

The len is serialized as a quint32, followed by len bytes from s. If len is negative or too large for a quint32, nothing is written and the status is set to SizeLimitExceeded.

See also writeRawData() and readBytes().

int QDataStream::writeRawData(const char *s, int len)

Writes len bytes from s to the stream and returns the number of bytes written, or -1 if there is no device, the stream is in an error state or len is negative. If the device does not accept all the bytes, the status is set to WriteFailed. The bytes are written as they are, with no length prefix and no byte order conversion.

See also writeBytes() and readRawData().