QIODevice 类

成员函数文档

QIODevice::QIODevice()

构建一个QIODevice对象。

[显式] QIODevice::QIODevice(QObject *parent)

使用给定的parent构建一个QIODevice对象。

[虚拟 noexcept] QIODevice::~QIODevice()

析构函数是虚拟的，QIODevice是一个抽象基类。此析构函数不调用close，但子类析构函数可能会。如果您不确定，请在销毁QIODevice之前调用close()。

[信号] void QIODevice::aboutToClose()

当设备即将关闭时，会发出此信号。如果您需要在设备关闭之前执行某些操作（例如，如果您有数据在另一个缓冲区中，需要将其写入设备），请连接此信号。

[虚拟] bool QIODevice::atEnd() const

如果当前读写位置在设备末尾（即在设备上没有更多可读数据），则返回true；否则返回false。

对于某些设备，即使还有更多数据要读取，atEnd()也可以返回true。此特殊情况仅适用于响应您调用read()时生成数据的设备（例如，Unix和macOS上的/dev或/proc文件，或在所有平台上的控制台输入/stdin）。

另请参阅bytesAvailable、read和isSequential。

[虚拟] qint64 QIODevice::bytesAvailable() const

返回可读的字节数。此函数通常与顺序设备一起使用，以确定在读取之前要在缓冲区中分配多少字节。

重新实现此函数的子类必须调用基本实现，以便包含QIODevice的缓冲区大小。示例

qint64 CustomDevice::bytesAvailable() const
{
    return buffer.size() + QIODevice::bytesAvailable();
}

另请参阅 bytesToWrite()，readyRead() 和 isSequential()。

[虚函数] qint64 QIODevice::bytesToWrite() const

对于缓冲设备，此函数返回等待写入的字节数。对于没有缓冲区的设备，此函数返回0。

重新实现此函数的子类必须调用基类实现，以便包含QIODevice缓冲区的大小。

另请参阅 bytesAvailable，bytesWritten 和 isSequential。

[信号] void QIODevice::bytesWritten(qint64 bytes)

每当向设备的当前写入通道写入数据负载时，都会发出此信号。将bytes参数设置为在此负载中写入的字节数。

bytesWritten()不会递归发出；如果您在连接到bytesWritten()信号的槽中重新进入事件循环或调用waitForBytesWritten()，则不会重新发出信号（尽管waitForBytesWritten()可能仍然返回true）。

另请参阅 readyRead。

[虚拟函数] bool QIODevice::canReadLine() const

如果可以从设备中读取一个完整的数据行，则返回true；否则返回false。

注意，无缓冲区设备因为没有确定可以读取内容的途径，总是返回false。

通常与readyRead()信号一起调用此函数。

重新实现此函数的子类必须调用基类实现，以便包含QIODevice缓冲区的内容。

bool CustomDevice::canReadLine() const
{
    return buffer.contains('\n') || QIODevice::canReadLine();
}

另请参阅 readyRead 和 readLine。

[信号] void QIODevice::channelBytesWritten(int channel, qint64 bytes)

每当向设备写入数据负载时，都会发出此信号。将bytes参数设置为在此负载中写入的字节数，而channel是他们被写入的通道。与bytesWritten不同，无论当前写入通道如何，都会发出。

channelBytesWritten()可以被递归发出 - 即使是对同一通道。

另请参阅 bytesWritten 和 channelReadyRead。

[信号] void QIODevice::channelReadyRead(int channel)

当可从设备读取新数据时，会发出此信号。将channel参数设置为数据到达的读取通道索引。与readyRead不同，无论当前读取通道如何，都会发出。

channelReadyRead()可以被递归发出 - 即使是对同一通道。

另请参阅 readyRead() 和 channelBytesWritten().

[虚函数] void QIODevice::close()

首先发出 aboutToClose()，然后关闭设备并设置其 OpenMode 为 NotOpen。错误字符串也被重置。

另请参阅 setOpenMode() 和 QIODeviceBase::OpenMode。

void QIODevice::commitTransaction()

完成一个读取事务。

对于顺序设备，事务期间在内部缓冲区中记录的所有数据都将被丢弃。

另请参阅 startTransaction() 和 rollbackTransaction。

int QIODevice::currentReadChannel() const

返回当前读取通道的索引。

另请参阅 setCurrentReadChannel()，readChannelCount() 和 QProcess。

int QIODevice::currentWriteChannel() const

返回当前写入通道的索引。

另请参阅 setCurrentWriteChannel() 和 writeChannelCount。

QString QIODevice::errorString() const

返回上次设备发生错误的可读描述。

另请参阅 setErrorString。

bool QIODevice::getChar(char *c)

从设备读取一个字符并将其存储在 c 中。如果 c 是 nullptr，则字符将被丢弃。成功时返回 true；否则返回 false。

另请参阅 read，putChar 和 ungetChar。

bool QIODevice::isOpen() const

如果设备是打开的，则返回 true；否则返回 false。设备打开是指它可以从其中读取和/或写入。默认情况下，如果 openMode() 返回 NotOpen，则此函数返回 false。

另请参阅 openMode() 和 QIODeviceBase::OpenMode。

bool QIODevice::isReadable() const

如果可以从设备读取数据，则返回 true；否则返回 false。使用 bytesAvailable() 来确定可以读取多少字节。

这是一个便利函数，用于检查设备的 OpenMode 是否包含 OnlyRead 标志。

另请参阅 openMode() 和 OpenMode。

[虚函数] bool QIODevice::isSequential() const

如果此设备为顺序设备，则返回 true；否则返回 false。

串行设备与随机存取设备不同，没有起始、结束、大小或当前位置的概念，并且不支持定位。只能当设备报告有数据可用时才能从设备读取。最常见的串行设备是网络套接字。在Unix中，如 /dev/zero 和 FIFO 管道等特殊文件也是串行设备。

另一方面，常规文件支持随机访问。它们既有大小也有当前位置，并且支持在数据流中进行前后定位。常规文件是非顺序的。

另请参阅 bytesAvailable。

bool QIODevice::isTextModeEnabled() const

如果启用了文本标志，则返回true；否则返回false。

另请参阅 setTextModeEnabled。

bool QIODevice::isTransactionStarted() const

如果设备上正在处理事务，则返回true；否则返回false。

另请参阅 startTransaction。

bool QIODevice::isWritable() const

如果可以向设备写入数据，则返回true；否则返回false。

这是一个方便函数，它会检查设备的OpenMode是否包含写只标志。

另请参阅 openMode() 和 OpenMode。

[虚拟] bool QIODevice::open(QIODeviceBase::OpenMode mode)

打开设备并将其OpenMode设置为mode。如果成功，则返回true；否则返回false。应从任何重新实现open()或其他打开设备的函数中调用此函数。

另请参阅 openMode() 和 QIODeviceBase::OpenMode。

QIODeviceBase::OpenMode QIODevice::openMode() const

返回设备已打开的模式；即只读或只写。

另请参阅 setOpenMode()和OpenMode。

qint64 QIODevice::peek(char *data, qint64 maxSize)

从设备读取最多maxSize字节到data中，不具有副作用（即，如果您在peek()之后调用read()，您将获得相同的数据）。返回读取的字节数。如果发生错误，例如尝试在只写模式下查看设备，则此函数返回-1。

当没有更多数据可供读取时返回0。

示例

bool isExeFile(QFile *file)
{
    char buf[2];
    if (file->peek(buf, sizeof(buf)) == sizeof(buf))
        return (buf[0] == 'M' && buf[1] == 'Z');
    return false;
}

另请参阅 read。

QByteArray QIODevice::peek(qint64 maxSize)

这是一个重载函数。

查看设备最多maxSize字节，并将查看的数据作为QByteArray返回。

示例

bool isExeFile(QFile *file)
{
    return file->peek(2) == "MZ";
}

该函数没有报告错误的方法；返回空QByteArray可以表示当前没有可查看的数据，或者发生了错误。

另请参阅 read。

[虚拟] qint64 QIODevice::pos() const

对于随机访问设备，此函数返回数据写入或读取的位置。对于顺序设备或已关闭的设备，其中不存在“当前位置”的概念，则返回0。

设备的当前读写位置由QIODevice内部维护，因此无需重新实现此函数。当子类化QIODevice时，请使用QIODevice::seek()来通知QIODevice设备位置的变化。

另请参阅isSequential()和seek。

bool QIODevice::putChar(char c)

将字符c写入设备。成功时返回true；否则返回false。

另请参阅write、getChar和ungetChar。

qint64 QIODevice::read(char *data, qint64 maxSize)

从设备读取最多maxSize个字节到data中，并返回读取的字节数。如果发生错误，例如尝试从以WriteOnly模式打开的设备读取时，此函数返回-1。

当没有更多数据可供读取时返回0。但是，读取到流结束时被视为错误，因此在此情况下返回-1（即，在已关闭的套接字或在进程死亡后读取）。

另请参阅readData、readLine和write。

QByteArray QIODevice::read(qint64 maxSize)

这是一个重载函数。

从设备读取最多maxSize个字节，并以QByteArray的形式返回读取的数据。

此函数没有报告错误的方法；返回空QByteArray可以表示目前没有数据可供读取，或者发生了错误。

QByteArray QIODevice::readAll()

从设备读取所有剩余数据，并以字节数组的形式返回。

此函数没有报告错误的方法；返回空QByteArray可以表示目前没有数据可供读取，或者发生了错误。此函数也没有表明可能有更多数据可读但无法读取的方法。

int QIODevice::readChannelCount() const

如果设备已打开，则返回可用的读取通道数；否则返回0。

另请参阅writeChannelCount和QProcess。

[信号] void QIODevice::readChannelFinished()

当此设备中的输入（读取）流关闭时发出的信号。一旦检测到关闭，就会发出此信号，这意味着仍然可以使用 read() 读取数据。

另请参阅 atEnd() 和 read()。

[纯虚受保护的] qint64 QIODevice::readData(char *data, qint64 maxSize)

从设备读取最多 maxSize 字节到 data 中，并返回读取的字节数或在发生错误时返回 -1。

如果没有可读取的字节，并且永远不会有更多字节可供读取（例如套接字关闭、管道关闭、子进程结束），则此函数返回 -1。

此函数由 QIODevice 调用。创建 QIODevice 的子类时重新实现此函数。

在重新实现此函数时，必须在返回之前读取所有必需的数据。这是为了使 QDataStream 能够操作该类。 QDataStream 假设所有请求的信息都已读取，因此即使在出现问题时也不会重试读取。

此函数可能以 0 作为 maxSize 调用，这可以用于执行读取后的操作。

另请参阅 read()、readLine() 和 writeData()。

qint64 QIODevice::readLine(char *data, qint64 maxSize)

此函数从设备读取一行 ASCII 字符，最多读取 maxSize - 1 字节，并将字符存储在 data 中，返回读取的字节数。如果无法读取行但未发生错误，则此函数返回 0。如果发生错误，则返回可以读取的长度，如果什么都没读取则返回 -1。

始终将终止 '\0' 字节附加到 data 上，因此 maxSize 必须大于 1。

读取数据直到以下任一条件满足

• 读取到第一个 '\n' 字符。
• maxSize - 1 字节被读取。
• 检测到设备数据的末尾。

例如，以下代码从文件读取一行字符

QFile file("box.txt");
if (file.open(QFile::ReadOnly)) {
    char buf[1024];
    qint64 lineLength = file.readLine(buf, sizeof(buf));
    if (lineLength != -1) {
        // the line is available in buf
    }
}

缓冲区包含换行符('\n')。如果没有在读取 maxSize - 1 字节前找到换行符，则不会在缓冲区中插入换行符。在 Windows 上，换行符会被替换为 '\n'。

请注意，在顺序设备上，数据可能不会立即可用，这可能导致返回部分行。在读取之前调用 canReadLine() 函数，可以检查是否可以读取完整的行（包括换行符）。

此函数调用 readLineData()，该函数通过重复调用 getChar() 实现。您可以通过在自己的子类中重新实现 readLineData() 来提供更高效的实现。

另请参阅 getChar()、read()、canReadLine() 和 write()。

QByteArray QIODevice::readLine(qint64 maxSize = 0)

这是一个重载函数。

从设备中读取一行，但不超过maxSize个字符，并以字节数组的形式返回结果。

此函数没有报告错误的方法；返回空QByteArray可以表示目前没有数据可供读取，或者发生了错误。

[虚保护] qint64 QIODevice::readLineData(char *data, qint64 maxSize)

将最多maxSize个字符读取到data中，并返回读取的字符数。

该函数由readLine()调用，并提供其基本实现，使用getChar()。缓冲设备可以通过重新实现此函数来提高readLine()的性能。

readLine()会在data中追加一个'\0'字节；readLineData()不需要这样做。

如果重新实现此函数，请务必返回正确的值：它应返回本行中读取的字节数（包括终止的新行字符），如果在此点没有要读取的行，则返回0。如果发生错误，并且没有读取任何字节，则应返回-1。读取超过EOF被视为错误。

[信号] void QIODevice::readyRead()

每次从设备的当前读取通道读取新数据时，都会发出此信号。仅当新的数据可用时，例如在网络套接字上到达新的网络负载，或者新的数据块追加到设备时，才会再次发出此信号。

readyRead()不会被递归调用；如果您在连接到readyRead()信号的槽中重新进入事件循环或调用waitForReadyRead()，则不会重新发出信号（尽管waitForReadyRead()可能仍然返回true）。

对于实现继承自QIODevice的类的开发人员说明：您应该在新的数据已经到达时始终发出readyRead()信号（不要仅在您的缓冲区中还有要读取的数据时发出它）。不要在其他条件下发出readyRead()信号。

另请参阅 bytesWritten()。

[虚] bool QIODevice::reset()

定位到随机访问设备的输入起始点。如果成功，则返回true；否则返回false（例如，如果设备未打开）。

请注意，当在QFile上使用QTextStream时，在QFile上调用reset()不会得到预期结果，因为QTextStream缓冲文件。请使用QTextStream::seek()函数代替。

另请参阅 seek()。

void QIODevice::rollbackTransaction()

回滚读取事务。

将输入流恢复到startTransaction()调用的位置。此函数通常用于在提交事务之前检测到不完整的读取时回滚事务。

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

[虚] bool QIODevice::seek(qint64 pos)

对于随机访问设备，此函数将当前位置设置为pos，成功返回true，如果发生错误则返回false。对于顺序设备，默认行为是产生警告并返回false。

当继承自QIODevice时，必须在函数开始处调用QIODevice::seek()以确保与QIODevice内置缓冲区的完整性。

另请参阅pos() 和 isSequential。

void QIODevice::setCurrentReadChannel(int channel)

将QIODevice的当前读取通道设置为给定的channel。当前输入通道用于函数 read()、readAll()、readLine() 和 getChar()。它还确定哪个通道触发QIODevice发射 readyRead。

另请参阅currentReadChannel()、readChannelCount() 和 QProcess。

void QIODevice::setCurrentWriteChannel(int channel)

将QIODevice的当前写入通道设置为给定的channel。当前输出通道用于函数write()、putChar()。它还确定哪个通道触发QIODevice发射 bytesWritten。

另请参阅currentWriteChannel() 和 writeChannelCount。

[protected] void QIODevice::setErrorString(const QString &str)

将最后发生的设备错误的可读描述设置为str。

另请参阅errorString。

[protected] void QIODevice::setOpenMode(QIODeviceBase::OpenMode openMode)

将设备的OpenMode设置为openMode。如果设备打开后标志更改，请调用此函数设置打开模式。

另请参阅 openMode() 和 OpenMode。

void QIODevice::setTextModeEnabled(bool enabled)

如果enabled为true，此函数则将在设备上设置Text标记；否则移除Text标记。此功能对于提供了一个QIODevice上的自定义换行符处理的类很有用。

在调用此函数之前应打开IO设备。

另请参阅isTextModeEnabled、open 和 setOpenMode。

[virtual] qint64 QIODevice::size() const

对于打开的随机访问设备，此函数返回设备的大小。对于打开的顺序设备，返回bytesAvailable。

如果设备已关闭，返回的大小将不会反映设备的实际大小。

另请参阅isSequential 和 pos。

qint64 QIODevice::skip(qint64 maxSize)

跳过设备中最多 maxSize 字节。返回实际跳过的字节数，或者在出错时返回 -1。

此函数不会等待，只会丢弃可读取的数据。

如果设备以文本模式打开，则换行符终止符被转换为 '\n' 符号，并且与 read() 和 peek() 的行为相同，算作一个字节的长度。

此函数适用于所有设备，包括无法 seek() 的顺序设备。它已针对在 peek() 调用后跳过不需要的数据进行优化。

对于随机访问设备，可以使用 skip() 从当前位置向前搜索。不允许使用负的 maxSize 值。

另请参阅skipData()、peek()、seek() 和 read()。

[虚拟受保护，自 6.0 版起] qint64 QIODevice::skipData(qint64 maxSize)

跳过设备中最多 maxSize 字节。返回实际跳过的字节数，或者在出错时返回 -1。

此函数由 QIODevice 调用。在创建 QIODevice 的子类时，请考虑重新实现此函数。

基本实现通过读取到一个虚拟缓冲区来丢弃数据。这很慢，但适用于所有类型的设备。子类可以实现此函数以改进性能。

此函数在 Qt 6.0 版本中被引入。

另请参阅skip()、peek()、seek() 和 read()。

void QIODevice::startTransaction()

在设备上启动一个新的读取事务。

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

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

void QIODevice::ungetChar(char c)

将字符 c 放回设备中，并在当前位置不为 0 的情况下递减当前位置。通常在编写回溯解析器时调用此函数来“撤销”getChar() 操作。

如果c之前未从设备中读取，则行为是未定义的。

[虚拟] bool QIODevice::waitForBytesWritten(int msecs)

对于缓冲设备，该函数等待直到已缓存的写入数据被写入设备并发出bytesWritten() 信号，或者直到 msecs 毫秒已过去。如果 msecs 为 -1，此函数将不会超时。对于无缓冲设备，它将立即返回。

如果向设备写入数据负载，则返回 true；否则返回 false（即如果操作超时或发生错误）。

此函数可以在不需要事件循环的情况下操作。在编写非GUI应用程序以及在非GUI线程中执行I/O操作时很有用。

如果从连接到bytesWritten() 信号的槽中调用它，则bytesWritten() 不会重新发出。

重新实现此函数以提供自定义设备的阻塞API。默认实现不执行任何操作，并返回 false。

另请参阅：waitForReadyRead。

[virtual] bool QIODevice::waitForReadyRead(int msecs)

直到可读取新数据并发出readyRead() 信号或 msecs 毫秒已过去为止阻塞。如果 msecs 为 -1，此函数将不会超时。

如果可读取新数据，则返回 true；否则返回 false（如果操作超时或发生错误）。

此函数可以在不需要事件循环的情况下操作。在编写非GUI应用程序以及在非GUI线程中执行I/O操作时很有用。

如果从连接到readyRead() 信号的槽中调用它，则readyRead() 不会重新发出。

重新实现此函数以提供自定义设备的阻塞API。默认实现不执行任何操作，并返回 false。

另请参阅：waitForBytesWritten。

qint64 QIODevice::write(const char *data, qint64 maxSize)

从 data 中最多写入 maxSize 字节数据到设备。返回实际写入的字节数，如果发生错误则返回 -1。

另请参阅：read() 和 writeData。

qint64 QIODevice::write(const char *data)

这是一个重载函数。

将来自以 null 结尾的8位字符字符串的数据写入设备。如果发生错误则返回实际写入的字节数，或 -1。这等效于

...
QIODevice::write(data, qstrlen(data));
...

另请参阅：read() 和 writeData。

qint64 QIODevice::write(const QByteArray &data)

这是一个重载函数。

将 data 的内容写入设备。如果发生错误则返回实际写入的字节数，或 -1。

另请参阅：read() 和 writeData。

int QIODevice::writeChannelCount() const

如果设备打开则返回可用的写入通道数；否则返回 0。

另请参阅：readChannelCount。

[纯虚保护] qint64 QIODevice::writeData(const char *data, qint64 maxSize)

将数据数组的最多 maxSize 个字节写入设备。返回写入的字节数，或者在发生错误时返回 -1。

此函数由 QIODevice 调用。创建 QIODevice 的子类时重新实现此函数。

在重新实现此函数时，非常重要的一点是实现此函数应写入所有可用的数据后再返回。这是必需的，以便 QDataStream 能够在类上操作。 QDataStream 假设所有信息都已写入，因此当出现问题时不会重试写入。

另请参阅read() 和 write()。