QDataStream类

成员函数文档

QDataStream::QDataStream()

构造一个不包含I/O设备的数据流。

另请参阅 setDevice()。

[显式] QDataStream::QDataStream(QIODevice *d)

构造一个使用I/O设备 d 的数据流。

另请参阅 setDevice() 和 device()。

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

构造一个在字节缓冲区 a 上操作的数据流。 mode 描述了如何使用设备。

或者，如果您只想从字节缓冲区中读取，可以使用 QDataStream(const QByteArray &)。

由于 QByteArray 不是一个 QIODevice 子类，内部将创建一个 QBuffer 来封装字节缓冲区。

QDataStream::QDataStream(const QByteArray &a)

构造一个在字节缓冲区 a 上操作的可读数据流。如果想要向字节缓冲区写入，请使用 QDataStream(QByteArray*, int)。

由于 QByteArray 不是一个 QIODevice 子类，内部将创建一个 QBuffer 来封装字节缓冲区。

[noexcept] QDataStream::~QDataStream()

销毁数据流。

析构函数不会影响当前的I/O设备，除非它是一个内部I/O设备（例如一个 QBuffer）处理在构造函数中传入的 QByteArray，在这种情况下，内部I/O设备将被销毁。

void QDataStream::abortTransaction()

终止一个读取事务。

此函数通常用于在高级协议错误或流同步丢失后丢弃事务。

如果在一个内部事务上调用此函数，终止将委托给最外层事务，并且随后开始的所有内部事务将强制失败。

对外层事务而言，将丢弃恢复点以及流内的任何内部复制数据。不会影响流的当前读取位置。

将数据流的状况设置为

另请参阅 startTransaction()、commitTransaction() 和 rollbackTransaction()。

QDataStream::ByteOrder QDataStream::byteOrder() const

如果I/O设备已达到末尾位置（流或文件的末尾）或未设置I/O设备，则返回 true；否则返回 false。

另请参阅 QIODevice::atEnd()。

QDataStream::ByteOrder QDataStream::byteOrder() const

返回当前的字节顺序设置 - 要么是 BigEndian，要么是 LittleEndian。

另请参阅 setByteOrder()。

bool QDataStream::commitTransaction()

完成一次读取事务。如果在事务过程中没有发生读取错误，则返回 true；否则返回 false。

如果在一个内部事务上调用，提交将推迟到最外层的 commitTransaction()、rollbackTransaction 或 abortTransaction() 调用发生。

否则，如果流状态表示已经读取到数据末尾，该函数将把流数据恢复到 startTransaction() 调用点。在这种情况下，需要等待更多数据的到达，然后重新开始一个新的事务。如果数据流读取了损坏的数据或任何内部事务被终止，此函数将终止事务。

另请参阅startTransaction()、rollbackTransaction() 和 abortTransaction()。

QIODevice *QDataStream::device() const

返回当前设置的 I/O 设备，如果没有设置设备，则返回 nullptr。

另请参阅 setDevice()。

QDataStream::FloatingPointPrecision QDataStream::floatingPointPrecision() const

返回数据流的浮点精度。

另请参阅FloatingPointPrecision 和 setFloatingPointPrecision()。

[since 6.7] QDataStream &QDataStream::readBytes(char *&s, qint64 &l)

从流中读取缓冲区 s 并返回对流的引用。

缓冲区 s 使用 new [] 分配。使用 delete [] 操作符销毁它。

l 参数被设置为缓冲区的长度。如果读取的内容为空，l 被设置为 0，s 被设置为 nullptr。

序列化格式是一个长度指定符，然后是 l 字节的数据。如果版本小于 6.7 或元素数量小于 0xfffffffe（2^32 -2），长度指定符为一个 quint32，否则有一个扩展值 0xfffffffe 后跟一个 quint64 实际值。对于支持 isNull() 的容器，它被编码为一个所有位都设置的单个 quint32，没有数据。

此函数自 Qt 6.7 引入。

另请参阅readRawData() 和 writeBytes()。

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

从流中读取最多 len 字节到 s 并返回读取的字节数。如果发生错误，此函数返回 -1。

缓冲区 s 必须预先分配。数据不会被解码。

另请参阅readBytes()、QIODevice::read() 和 writeRawData()。

void QDataStream::resetStatus()

重置数据流的状况。

另请参阅 Status，status() 和 setStatus。

void QDataStream::rollbackTransaction()

撤销一个读取事务。

此函数通常用于在提交事务前检测到读取不完整时回滚事务。

如果在内部事务上调用，撤销会被委托给最外层事务，并且随后开始的内部事务将被迫失败。

对于最外层事务，将流数据恢复到 startTransaction() 调用的点。如果数据流已读取损坏的数据或任何内部事务已中止，则此函数中止事务。

如果前面的流操作成功，设置数据流的状态为

另请参阅 startTransaction，commitTransaction 和 abortTransaction。

void QDataStream::setByteOrder(QDataStream::ByteOrder bo)

设置序列化字节顺序为 bo。

bo 参数可以是 QDataStream::BigEndian 或 QDataStream::LittleEndian。

默认设置是大端。我们不推荐更改此设置，除非您有特殊要求。

另请参阅 byteOrder。

void QDataStream::setDevice(QIODevice *d)

void QDataStream::setDevice(QIODevice *d)

设置 I/O 设备为 d，它可以是 nullptr 以取消当前 I/O 设备的设置。

另请参阅 device。

void QDataStream::setFloatingPointPrecision(QDataStream::FloatingPointPrecision precision)

将数据流的浮点精度设置为 precision。如果浮点精度是 DoublePrecision 而数据流的版本是 Qt_4_6 或更高版本，所有浮点数将以 64 位精度写入和读取。如果浮点精度是 SinglePrecision 且版本是 Qt_4_6 或更高版本，所有浮点数将以 32 位精度写入和读取。

对于先于 Qt_4_6 的版本，数据流中浮点数的精度取决于调用的流操作符。

默认是 DoublePrecision。

请注意，此属性不影响 qfloat16 实例的序列化或反序列化。

另请参阅 floatingPointPrecision。

void QDataStream::setStatus(QDataStream::Status status)

将数据流的状态设置为提供的 status。

在调用 resetStatus() 方法之前，所有对 setStatus() 的后续调用均被忽略。

另请参阅 Status，status() 和 resetStatus。

void QDataStream::setVersion(int 版本号)

将数据序列化格式的版本号设置为指定的 版本号，这是一组 Version 枚举值的其中一个。

如果您正在使用 Qt 的当前版本，则不必设置版本号，但为了您自己的自定义二进制格式，我们建议您这样做；请参阅详细描述中的 Versioning。

为了适应新的功能，Qt 一些类在各个版本中的数据流序列化格式可能已发生变化。如果您想读取由 Qt 更早版本创建的数据，或写入可由使用 Qt 更早版本编译的程序读取的数据，请使用此函数来修改由 QDataStream 使用的序列化格式。

Version 枚举提供了不同 Qt 版本的符号常数。例如

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

另请参阅 version() 和 Version。

qint64 QDataStream::skipRawData(qint64 长度)

跳过设备的 长度 字节。返回实际上跳过的字节数，或在出错时返回 -1。

这与在长度为 长度 的缓冲区上调用 readRawData() 并忽略该缓冲区等效。

另请参阅 QIODevice::seek。

void QDataStream::startTransaction()

在流上开始新的读取事务。

在读取操作序列中定义了可以恢复的点。对于顺序设备，读取的数据将在内部复制，以便在不完整的读取的情况下进行恢复。对于随机访问设备，此函数保存流的当前位置。通过调用 commitTransaction()、rollbackTransaction 或 abortTransaction() 来完成当前事务。

一旦启动了事务，后续对此函数的调用将使事务递归。内部事务作为最外层事务的代理（即，向最外层事务报告读取操作的状态，最外层事务可以恢复流的当前位置）。

在事务期间（包括内部事务失败）发生错误时，从数据流中读取将暂停（所有后续的读取操作返回空/零值），并强制后续内部事务失败。启动新的最外层事务可以从这种状态恢复。这种行为使得不必单独错误检查每个读取操作。

另请参阅 commitTransaction、rollbackTransaction 和 abortTransaction。

QDataStream::Status QDataStream::status() const

返回数据流的当前状态。

另请参阅状态、设置状态和重置状态。

int QDataStream::version() const

返回数据序列化格式的版本号。

另请参阅设置版本和版本。

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

将长度指示符 len 和缓冲区 s 写入流中，并返回流的一个引用。

len 作为 quint32 和可选的 quint64 进行序列化，接着是来自 s 的 len 字节。请注意，数据未进行编码。

另请参阅写入原始数据和读取字节数。

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

将 s 中的 len 字节写入流中。返回实际写入的字节数，或出错时返回 -1。数据未进行编码。

另请参阅写入字节数、QIODevice::write 和 读取原始数据。

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

将有符号字节 i 写入流中，并返回流的引用。

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

这是一个重载函数。

将无符号字节 i 写入流中，并返回流的引用。

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

这是一个重载函数。

将有符号 16 位整数 i 写入流中，并返回流的引用。

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

这是一个重载函数。

将无符号 16 位整数 i 写入流中，并返回流的引用。

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

这是一个重载函数。

将有符号 32 位整数 i 写入流中，并返回流的引用。

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

这是一个重载函数。

将整数 i 写入流中作为 32 位无符号整数 (quint32)，并返回流的引用。

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

这是一个重载函数。

将带符号的64位整数，i写入数据流，并返回数据流的引用。

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

这是一个重载函数。

将无符号的64位整数，i写入数据流，并返回数据流的引用。

QDataStream &QDataStream::operator<<(std::nullptr_t ptr)

这是一个重载函数。

模拟写入std::nullptr_t，ptr到数据流中，并返回数据流的引用。此函数实际上不会向数据流写入任何内容，因为std::nullptr_t值被存储为0个字节。

QDataStream &QDataStream::operator<<(bool )

将布尔值，i写入数据流。返回数据流的引用。

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

这是一个重载函数。

使用标准的IEEE 754格式将浮点数，f写入数据流。返回数据流的引用。

另请参阅setFloatingPointPrecision。

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

这是一个重载函数。

使用标准的IEEE 754格式将浮点数，f写入数据流。返回数据流的引用。

另请参阅setFloatingPointPrecision。

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

这是一个重载函数。

将以'\0'结尾的字符串，s写入数据流并返回数据流的引用。

使用序列化字符串。