class QIODevice#

《QIODevice》类是Qt中所有I/O设备的基接口类。更多…

Inheritance diagram of PySide6.QtCore.QIODevice

继承自： QSerialPort、QNetworkReply、QLocalSocket、QAbstractSocket、QUdpSocket、QTcpSocket、QProcess、QFileDevice、QSaveFile、QFile、QTemporaryFile、QSslSocket、QBuffer、QCoapReply、QCoapResourceDiscoveryReply、QBluetoothSocket

概要#

方法#

虚拟方法#

信号#

注意

本文档可能包含从 C++ 自动翻译到 Python 的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译有任何问题，也可以通过在 https:/bugreports.qt.io/projects/PYSIDE 创建工单来告知我们。

详细描述#

警告

本节包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

QIODevice 为支持读取和写入数据块的设备提供了一个共通实现和抽象接口，如 QFile、QBuffer 和 QTcpSocket。 QIODevice 是一个抽象类，不能被实例化，但常用于定义的接口来提供设备无关的 I/O 特性。例如，Qt 的 XML 类操作一个 QIODevice 指针，这使得它们可以与各种设备（如文件和缓冲区）一起使用。

在访问设备之前，必须调用 open() 来设置正确的 OpenMode（如 ReadOnly 或 ReadWrite）。然后您可以使用 write() 或 putChar() 向设备写入，通过调用 read()、readLine() 或 readAll() 进行读取。完成对设备的操作后，请调用 close()。

QIODevice 区分两种类型的设备：随机访问设备和顺序设备。

  • 随机访问设备支持使用 seek() 在任意位置进行查找。通过调用 pos() 可以获取文件的当前位置。例如，QFile 和 QBuffer 是随机访问设备的示例。

  • 顺序设备不支持随机位置查找。数据必须顺序读取。函数 pos() 和 size() 对顺序设备不适用。QTcpSocket 和 QProcess 是顺序设备的示例。

您可以使用 isSequential() 函数来确定设备的类型。

QIODevice 在有新数据可供读取时发出 readyRead() 信号；例如，如果新数据已到达网络或如果已附加到您的文件的额外数据。您可以通过调用 bytesAvailable() 来确定当前可读的字节数。在异步设备（如QTcpSocket）编程中，常将 bytesAvailable() 与 readyRead() 信号一起使用，因为数据片段可能在任意时间点到达。每当向设备写入数据负载时，QIODevice 就会发射 bytesWritten() 信号。使用 bytesToWrite() 来确定当前待写入的数据量。

某些QIODevice子类（如QTcpSocket和QProcess）是异步的。这意味着I/O函数，如write()或read()，总是立即返回，而与设备本身的通信可能发生在返回到事件循环时。QIODevice提供了一些函数，允许您强制这些操作立即执行，同时阻止调用线程并避免进入事件循环。这允许QIODevice子类在没有事件循环的情况下使用，或者在一个独立的线程中使用

  • waitForReadyRead() - 此函数将暂停调用线程的操作，直到有新数据可供读取。

  • waitForBytesWritten() - 此函数将暂停调用线程的操作，直到将一份数据写入设备。

  • waitFor….() - QIODevice子类实现了特定于设备的阻塞函数。例如，QProcess有一个名为waitForStarted()的函数，它暂停调用线程的操作，直到进程开始。

从主线程或GUI线程调用这些函数可能会导致您的用户界面冻结。示例

gzip = QProcess()
gzip.start("gzip", QStringList() << "-c")
if not gzip.waitForStarted():
    return False
gzip.write("uncompressed data")
compressed = QByteArray()
while gzip.waitForReadyRead():
    compressed += gzip.readAll()

通过继承 QIODevice，您可以为自己的I/O设备提供相同的接口。只有继承自 QIODevice 的类需要实现受保护的 readData() 和 writeData() 函数。 QIODevice 使用这些函数来实现所有其便利函数，例如 getChar()、readLine() 和 write() 等等。 QIODevice 还会为您处理访问控制，因此在调用 writeData() 时，您可以安全地假设设备已以写入模式打开。

某些子类，如 QFile 和 QTcpSocket，使用内存缓冲区进行数据的中间存储。这降低了必须进行设备访问调用的次数，这些调用通常非常缓慢。缓冲区使得如 getChar() 和 putChar() 这样的函数变得更快，因为它们可以在内存缓冲区上操作，而无需直接在设备上操作。然而，某些I/O操作与缓冲区不兼容。例如，如果有多个用户打开相同的设备并逐个字符读取，他们可能最终读取的是同一数据，而他们本意是读取不同的数据块。因此，QIODevice 允许您通过将无缓冲标志传递给 open() 来绕过任何缓冲区。当继承 QIODevice 时，请记住在以无缓冲模式打开设备时绕过早先可能使用的任何缓冲区。

通常，来自异步设备的数据流是分Fragment化的，数据块可以在任意时间点到达。为了处理数据结构的不完整读取，请使用由QIODevice实现的交易机制。请参阅startTransaction()和相关函数的更多详细信息。

某些顺序设备支持通过多个通道进行通信。这些通道表示独立排序列的数据流。一旦设备被打开，可以通过调用readChannelCount()和writeChannelCount()函数来确定通道数。要在通道之间切换，分别调用setCurrentReadChannel()和setCurrentWriteChannel()。此外，QIODevice还提供了额外的信号来按通道处理异步通信。

__init__(parent)#
参数：:

parent – QObject

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

__init__()

构建一个QIODevice对象。

aboutToClose()#

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

atEnd()#
返回类型：:

bool

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

对于某些设备，即使还有可读取的数据，atEnd() 方法也可能返回 true。这种情况仅适用于在你调用 read() 方法时生成数据的设备（例如，Unix 和 macOS 上的 /dev 或 /proc 文件，或在所有平台的控制台输入/stdin）。

bytesAvailable()#
返回类型：:

int

警告

本节包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

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

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

def bytesAvailable(self):

    return buffer.size() + QIODevice.bytesAvailable()

参见

bytesToWrite() readyRead() isSequential()

bytesToWrite()#
返回类型：:

int

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

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

bytesWritten(bytes)#
参数：:

bytes – int

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

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

参见

readyRead()

canReadLine()#
返回类型：:

bool

警告

本节包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

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

请注意，无缓冲设备无法确定可以读取什么，因此始终返回false。

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

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

def canReadLine(self):

    return buffer.contains('\n') or QIODevice.canReadLine()

参见

readyRead() 《readLine()

channelBytesWritten(channel, bytes)#
参数：:

  • channel – int

  • bytes – int

每当向设备写入数据负载时，都会发射此信号。《bytes》参数设置为在这个负载中写入的字节数，而《channel》是他们写入的通道。与《bytesWritten()》不同，它会在不管《current write channel》的情况下发射。

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

channelReadyRead(channel)#
参数：:

channel – int

当设备出现可读取的新数据时，会发出该信号。channel 参数设置为已到达数据的读取通道索引。与 readyRead() 不同，它会无条件发出，而不管 current read channel 是否设置了。

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

close()#

首先调用 aboutToClose()，然后关闭设备并将它的 OpenMode 设置为 NotOpen。错误字符串也被重置。

参见

setOpenMode() OpenMode

commitTransaction()#

完成一个读取事务。

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

currentReadChannel()#
返回类型：:

int

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

currentWriteChannel()#
返回类型：:

int

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

errorString()#
返回类型：:

str

返回最后发生的设备错误的可读描述。

getChar()#
返回类型：:

bool

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

isOpen()#
返回类型：:

bool

如果设备打开，则返回true；否则返回false。设备打开意味着它可以被读取或写入。默认情况下，如果openMode()返回NotOpen，则此函数返回false。

参见

openMode() OpenMode

isReadable()#
返回类型：:

bool

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

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

参见

openMode() OpenMode

isSequential()#
返回类型：:

bool

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

与随机访问设备相对，顺序设备没有起始、结束、大小或当前位置的概念，也不支持查找。只有在设备报告数据可用时，您才能从设备中读取。顺序设备最常见的例子是网络套接字。在Unix中，特殊文件如/dev/zero和fifo管道是顺序的。

另一方面，常规文件支持随机访问。它们既有大小，也有当前位置，还可以在数据流中向前和向后查找。常规文件是非顺序的。

isTextModeEnabled()#
返回类型：:

bool

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

isTransactionStarted()#
返回类型：:

bool

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

isWritable()#
返回类型：:

bool

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

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

参见

openMode() OpenMode

open(mode)#
参数：:

mode – OpenModeFlag 组合

返回类型：:

bool

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

参见

openMode() OpenMode

openMode()#
返回类型：:

OpenModeFlag 组合

返回设备打开的模式；即 ReadOnly 或 WriteOnly。

参见

setOpenMode() OpenMode

peek(buffer, maxlen)#
参数：:

  • buffer – PyBuffer

  • maxlen – int

返回类型：:

int

peek(maxlen)
参数：:

maxlen – int

返回类型：:

QByteArray

警告

本节包含从 C++ 自动翻译到 Python 的代码片段，可能包含错误。

这是一个重载函数。

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

示例

def isExeFile(file):

    return file.peek(2) == "MZ"

此函数没有错误报告的方式；返回空的 QByteArray 可能意味着没有当前可供查看的数据，或者发生了错误。

参见

read()

pos()#
返回类型：:

int

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

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

putChar(c)#
参数：:

c – int

返回类型：:

bool

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

read(buffer, maxlen)#
参数：:

  • buffer – PyBuffer

  • maxlen – int

返回类型：:

int

read(maxlen)
参数：:

maxlen – int

返回类型：:

QByteArray

这是一个重载函数。

从设备读取最多maxSize个字节，并将读取的数据作为QByteArray返回。

此函数无法报告错误；返回空QByteArray可能意味着没有可读数据，或者发生错误。

readAll()#
返回类型：:

QByteArray

从设备读取所有剩余数据，并作为字节数组返回。

此函数无法报告错误；返回空QByteArray可能意味着没有可读数据，或者发生错误。此函数也不能指示更多数据可能可用而无法读取。

readChannelCount()#
返回类型：:

int

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

readChannelFinished()#

此信号在输入（读取）流在此设备中关闭时发出。它会在检测到关闭操作后立即发出，这意味着还有可能使用read()读取数据。

参见

atEnd() read()

抽象 readData(maxlen)#
参数：:

maxlen – int

返回类型：:

PyObject

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

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

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

在实现此函数时，重要的是在返回之前读取所有必要的数据。这是为了确保QDataStream能够操作该类。QDataStream假定读取了所有请求的信息，因此如果有问题，则不会重试读取。

此函数可能会以0作为最大值调用，这可以用于执行读取操作之后的操作。

readLine(buffer, maxlen)#
参数：:

  • buffer – PyBuffer

  • maxlen – int

返回类型：:

int

readLine([maxlen=0])
参数：:

maxlen – int

返回类型：:

QByteArray

这是一个重载函数。

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

此函数无法报告错误；返回空QByteArray可能意味着没有可读数据，或者发生错误。

readLineData(maxlen)#
参数：:

maxlen – int

返回类型：:

PyObject

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

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

readLine() 将一个 ‘\0’ 字节追加到 data 中；readLineData() 不需要这样做。

如果你重写此函数，请特别注意返回正确的值：它应该返回读取的包含终止换行符的字符字节数，如果没有要读取的行，则返回 0。如果发生错误，只有在没有读取任何字节的情况下，才返回 -1。读取到文件末尾（EOF）被视为错误。

readyRead()#

每当从设备的当前读渠道可读新数据时，都会发射此信号。它将仅在可读取新车载数据时再次发射，例如，当新的网络数据负载到达你的网络套接字，或者当你将新的数据块追加到你的设备时。

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

注意面向 QIODevice 的类实现的开发者：你应该在新的数据到达时总是发射 readyRead()（不要仅在缓冲区中还有未读数据时发射它）。在其他条件下勿发射 readyRead()。

reset()#
返回类型：:

bool

对随机访问设备求至输入的起始位置。成功时返回 true；否则返回 false（例如，如果设备未打开）。

请注意，当在一个 QFile 上使用 QTextStream 时，调用 QFile 的 reset() 方法不会有预期的结果，因为 QTextStream 缓存了文件。请使用 seek() 函数代替。

参见

seek()

rollbackTransaction()#

撤销读事务。

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

seek(pos)#
参数：:

pos – int

返回类型：:

bool

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

当你从类 QIODevice 继承时，你必须在函数开始时调用 QIODevice::seek() 来确保与其内置缓存的完整性。

setCurrentReadChannel(channel)#
参数：:

channel – int

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

设置 setCurrentWriteChannel(channel)#
参数：:

channel – int

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

setErrorString(errorString)#
参数：:

errorString – 字符串

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

参见

errorString()

setOpenMode(openMode)#
参数：:

openMode – 结合 OpenModeFlag

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

参见

openMode() OpenMode

setTextModeEnabled(enabled)#
参数：:

enabled – bool

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

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

size()#
返回类型：:

int

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

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

skip(maxSize)#
参数：:

maxSize – int

返回类型：:

int

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

此函数不会等待，并且仅丢弃已可供读取的数据。

如果设备以文本模式打开，则将换行符终止符转换为‘\n’符号，并以单个字节的方式与read()和peek()的行为一致。

该函数适用于所有设备，包括那些不能调用 seek() 的顺序设备。它经过优化，以跳过在调用 peek() 之后的不需要的数据。

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

skipData(maxSize)#
参数：:

maxSize – int

返回类型：:

int

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

此函数由 QIODevice 调用。在创建子类时，考虑重写它。

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

startTransaction()#

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

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

注意

不支持事务嵌套。

参见

commitTransaction() rollbackTransaction()

ungetChar(c)#
参数：:

c – int

将字符 c 放回到设备中，并递减当前位置，除非位置为0。此函数通常用于“撤销” getChar() 操作，例如在编写回溯分析器时。

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

注意

在事务进行时，此函数不可用。

waitForBytesWritten(msecs)#
参数：:

msecs – int

返回类型：:

bool

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

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

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

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

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

警告

从主（GUI）线程调用此函数可能会使您的用户界面冻结。

参见

waitForReadyRead()

waitForReadyRead(msecs)#
参数：:

msecs – int

返回类型：:

bool

阻塞直到有可读数据，并且已发出 readyRead() 信号，或者直到 msecs 毫秒已通过。如果 msecs 是 -1，则此函数将不会超时。

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

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

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

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

警告

从主（GUI）线程调用此函数可能会使您的用户界面冻结。

参见

waitForBytesWritten()

write(data)#
参数：:

data – QByteArray

返回类型：:

int

这是一个重载函数。

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

writeChannelCount()#
返回类型：:

int

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

抽象 writeData(data, len)#
参数：:

  • data – str

  • len – int

返回类型：:

int

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

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

在重新实现此函数时，确保在返回之前此函数写入所有可用的数据非常重要。这是为了使QDataStream能够对类进行操作。 QDataStream假设所有信息已写入，因此如果有问题，则不会重试写入。

参见

read() write()