QIODevice Class

成员函数文档

从该设备读取一行数据到buffer ，并返回buffer 中包含读取数据的子集。

如果buffer 的大小小于该行的长度，则只读取并返回适合buffer 的字符。在这种情况下，再次调用readLineInto() 将读取该行的剩余部分。要确定是否读取了整行，首先要检查设备是否为atEnd() ，以防最后一行没有以换行结束。如果不是atEnd()，则验证返回的视图是否以"\n "结束。否则，需要再次调用readLineInto() 。

结果行可能会有行尾字符（"\n "或"\r\n"），因此可能需要调用QByteArrayView::trimmed() 。

如果出现错误，该函数将返回空值QByteArrayView 。否则，它将是buffer 的子跨度。如果当前没有数据可供读取，或者设备是atEnd() ，则此函数将返回空值QByteArrayView 。

请注意，返回值不以空值结束。如果需要空结束，可以通过buffer.chopped(1) ，然后在buffer[result.size()] 插入"\0"。

此函数在 Qt 6.9 中引入。

另请参阅 readLine() 。

QIODevice::QIODevice()

构造一个 QIODevice 对象。

[explicit] QIODevice::QIODevice(QObject *parent)

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

[virtual noexcept] QIODevice::~QIODevice()

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

[signal] void QIODevice::aboutToClose()

该信号在设备即将关闭时发出。如果需要在设备关闭前执行操作（例如，需要将独立缓冲区中的数据写入设备），请连接此信号。

[virtual] bool QIODevice::atEnd() const

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

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

另请参阅 bytesAvailable()、read() 和isSequential()。

[virtual] qint64 QIODevice::bytesAvailable() const

返回可供读取的字节数。该函数通常用于顺序设备，以确定在读取前在缓冲区中分配的字节数。

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

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

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

[virtual] qint64 QIODevice::bytesToWrite() const

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

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

另请参阅 bytesAvailable()、bytesWritten() 和isSequential()。

[signal] void QIODevice::bytesWritten(qint64 bytes)

每次向设备的当前写入通道写入有效数据时，都会发出该信号。bytes 参数设置为写入该有效负载的字节数。

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

另请参阅 readyRead()。

[virtual] bool QIODevice::canReadLine() const

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

请注意，无缓冲设备无法确定可读取的内容，因此总是返回 false。

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

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

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

另请参阅 readyRead() 和readLine()。

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

每次向设备写入有效数据时都会发出该信号。bytes 参数设置为写入该有效负载的字节数，而channel 则是写入的通道。与bytesWritten() 不同的是，它与current write channel 无关。

channelBytesWritten() 可以递归发送，即使是同一个通道。

另请参阅 bytesWritten() 和channelReadyRead()。

[signal] void QIODevice::channelReadyRead(int channel)

当有新数据可从设备读取时，就会发出该信号。channel 参数设置为数据已到达的读取通道的索引。与readyRead() 不同的是，该信号的发出与current read channel 无关。

channelReadyRead()可以递归发送，即使是同一通道。

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

[virtual] 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 是否包含只读标记。

另请参阅 openMode() 和OpenMode 。

[virtual] bool QIODevice::isSequential() const

如果该设备是顺序设备，则返回true ；否则返回 false。

顺序设备与随机存取设备不同，没有开始、结束、大小或当前位置的概念，也不支持寻道。只有当设备报告数据可用时，才能从设备读取数据。顺序设备最常见的例子就是网络套接字。在 Unix 上，/dev/zero 和 fifo 管道等特殊文件都是顺序文件。

而普通文件则支持随机存取。它们既有大小，也有当前位置，还支持在数据流中前后查找。正则文件是非顺序文件。

另请参见 bytesAvailable()。

bool QIODevice::isTextModeEnabled() const

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

另请参阅 setTextModeEnabled() 。

bool QIODevice::isTransactionStarted() const

如果设备上正在进行交易，则返回true ，否则返回false 。

另请参阅 startTransaction() 。

bool QIODevice::isWritable() const

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

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

另请参阅 openMode() 和OpenMode 。

[virtual] 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() 。

[virtual] 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 ，并返回读取的字节数。如果发生错误，例如尝试从只写模式下打开的设备中读取数据时发生错误，该函数将返回 -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 。

[signal] void QIODevice::readChannelFinished()

当输入（读取）流在该设备中关闭时，会发出该信号。该信号在检测到关闭时立即发出，这意味着仍有数据可通过read() 读取。

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

[pure virtual protected] qint64 QIODevice::readData(char *data, qint64 maxSize)

从设备读取最多maxSize 字节到data ，并返回读取的字节数，如果发生错误则返回-1。

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

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

在重新实现该函数时，重要的是该函数在返回前读取所有需要的数据。这是QDataStream 能够对该类进行操作的必要条件。QDataStream 假定所有请求的信息都已读取，因此如果出现问题，不会重试读取。

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

另请参阅 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 字节之前未遇到换行符，则不会在缓冲区中插入换行符。在窗口中，换行符将被替换为"\n"。

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

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

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

QByteArray QIODevice::readLine(qint64 maxSize = 0)

这是一个重载函数。

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

如果maxSize 为 0 或未指定，则读取的行可以是任意长度，从而实现无限制读取。

生成的行可能会有行尾字符（"\n "或"\r\n"），因此可能需要调用QByteArray::trimmed() 。

该函数无法报告错误；返回空QByteArray 意味着当前没有数据可供读取，或者发生了错误。

[virtual protected] qint64 QIODevice::readLineData(char *data, qint64 maxSize)

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

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

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

如果重新实现该函数，请注意返回正确的值：它应返回本行已读取的字节数，包括终止换行符，如果此时没有要读取的行，则返回 0。如果发生错误，则只有在没有读取字节的情况下才会返回-1。超过 EOF 的读取将被视为错误。

[since 6.9] bool QIODevice::readLineInto(QByteArray *line, qint64 maxSize = 0)

从设备读取一行，但不超过maxSize 个字符。并将其作为字节数组存储在line 中。

如果maxSize 为 0 或未指定，则该行可以是任意长度，从而实现无限制读取。

读取的行可能会有行尾字符（"\n "或"\r\n"），因此可能需要调用QByteArray::trimmed() 。

如果当前没有数据可供读取，或者发生了错误，该函数将返回false 并将line 设置为empty 。否则返回true 。

请注意，在任何情况下，调用前line 的内容都会被丢弃，但其capacity() 的内容永远不会减少。

此函数在 Qt 6.9 中引入。

另请参阅 readAll()、readLine() 和QTextStream::readLineInto()。

[signal] void QIODevice::readyRead()

每次从设备当前读取通道读取新数据时，都会发出一次该信号。只有当有新数据可用时，如网络套接字上有新的网络数据负载，或有新的数据块被添加到设备上时，才会再次发出该信号。

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

实现派生自QIODevice 的类的开发人员注意：当有新数据到达时，应始终发出 readyRead() 信号（不要因为缓冲区中仍有数据需要读取才发出该信号）。在其他情况下，请勿发出 readyRead()。

另请参阅 bytesWritten().

[virtual] bool QIODevice::reset()

搜索随机存取设备的输入起始位置。成功时返回 true，否则返回false （例如，如果设备未打开）。

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

另请参阅 seek()。

void QIODevice::rollbackTransaction()

回滚读取事务。

将输入流恢复到调用startTransaction() 时的位置。当提交事务前检测到未完成读取时，该函数通常用于回滚事务。

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

[virtual] 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()。

[virtual protected, since 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 ，则行为未定义。

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

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

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

该函数可以在没有事件循环的情况下运行。在编写非图形用户界面应用程序和在非图形用户界面线程中执行 I/O 操作时，该函数非常有用。

如果在连接到bytesWritten() 信号的槽中调用该函数，将不会重新发送bytesWritten() 信号。

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

另请参阅 waitForReadyRead().

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

阻塞，直至有新数据可供读取且readyRead() 信号已发出，或msecs 毫秒已过。如果毫秒数为-1，则该函数不会超时。

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

该函数可以在没有事件循环的情况下运行。在编写非图形用户界面应用程序和在非图形用户界面线程中执行 I/O 操作时，该函数非常有用。

如果在连接到readyRead() 信号的槽中调用该函数，将不会重新发送readyRead() 信号。

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

另请参阅 waitForBytesWritten().

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

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

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

qint64 QIODevice::write(const QByteArray &data)

这是一个重载函数。

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

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

qint64 QIODevice::write(const char *data)

这是一个重载函数。

向设备写入由 8 位字符组成的零字节字符串数据。返回实际写入的字节数，如果发生错误则返回-1。这等同于

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

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

int QIODevice::writeChannelCount() const

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

另请参阅 readChannelCount().

[pure virtual protected] qint64 QIODevice::writeData(const char *data, qint64 maxSize)

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

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

在重新实现该函数时，重要的是该函数在返回前写入所有可用数据。QDataStream QDataStream 假定所有信息都已写入，因此在出现问题时不会重试写入。

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