QIODevice

X_Nice

已于 2024-09-22 17:22:38 修改

阅读量444

点赞数 7

CC 4.0 BY-SA版权

文章标签： c++ qt

于 2024-09-19 11:23:02 首次发布

本文链接：https://blog.youkuaiyun.com/weixin_43446462/article/details/142349593

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()信号，每当有数据负载被写入设备时。使用bytestwrite()来确定当前等待写入的数据量。

QIODevice的某些子类，如QTcpSocket和QProcess，是异步的。这意味着诸如write()或read()之类的I/O函数总是立即返回，而与设备本身的通信可能在控制返回到事件循环时发生。QIODevice提供的函数允许您在阻塞调用线程且不进入事件循环的情况下强制立即执行这些操作。这允许QIODevice子类在没有事件循环的情况下使用，或者在单独的线程中使用:
waitForReadyRead()：这个函数挂起调用线程中的操作，直到有新的数据可供读取。
waitForBytesWritten() ：这个函数挂起调用线程中的操作，直到一个数据负载被写入设备。

通过子类化QIODevice，您可以为自己的I/O设备提供相同的接口。QIODevice的子类只需要实现受保护的readData()和writeData()函数。QIODevice使用这些函数来实现它所有的便利函数，比如getChar()， readLine()和write()。QIODevice还为您处理访问控制，因此，如果调用writeData()，您可以放心地假设设备以写模式打开。

一些子类，如QFile和QTcpSocket，使用内存缓冲区来实现数据的中间存储。这减少了所需设备访问调用的次数，这些调用通常非常缓慢。缓冲使得像getChar()和putChar()这样的函数更快，因为它们可以在内存缓冲区上操作，而不是直接在设备本身上操作。但是，某些I/O操作不能很好地使用缓冲区。例如，如果几个用户打开相同的设备并逐个字符地读取它，当他们打算每个人读取一个单独的块时，他们可能最终读取相同的数据。出于这个原因，QIODevice允许您通过将Unbuffered标志传递给open()来绕过任何缓冲。当子类化QIODevice时，记得在设备以Unbuffered模式打开时绕过任何可能使用的缓冲区。

通常，来自异步设备的传入数据流是碎片化的，数据块可以在任意时间点到达。为了处理数据结构的不完全读取，可以使用QIODevice实现的事务机制。请参阅startTransaction()和相关函数了解更多细节。

一些顺序设备支持通过多个通道进行通信。这些通道表示具有独立顺序传递特性的独立数据流。打开设备后，您可以通过调用readChannelCount()和writeChannelCount()函数来确定通道的数量。要在通道之间切换，分别调用setCurrentReadChannel()和setCurrentWriteChannel()。QIODevice还提供了额外的信号来处理每个通道的异步通信。

class Q_CORE_EXPORT QIODevice : public QObject
{
Q_OBJECT
public:

设备打开模式

    enum OpenModeFlag {
        NotOpen = 0x0000,
        ReadOnly = 0x0001,
        WriteOnly = 0x0002,
        ReadWrite = ReadOnly | WriteOnly,
        Append = 0x0004,
        Truncate = 0x0008,
        Text = 0x0010,
        Unbuffered = 0x0020,
        NewOnly = 0x0040,
        ExistingOnly = 0x0080
    };

Q_DECLARE_FLAGS(OpenMode, OpenModeFlag)

QIODevice();
explicit QIODevice(QObject *parent);
virtual ~QIODevice();

获取设备打开模式

    OpenMode openMode() const;

设置设备文本模式状态

void setTextModeEnabled(bool enabled);
	如果enabled为true，此函数将在设备上设置Text标志;否则将删除Text标志。
	这个特性对于在QIODevice上提供自定义行结束处理的类很有用。
	在调用这个函数之前应该打开IO设备。

获取设备文本模式状态

bool isTextModeEnabled() const;
	如果启用了Text标志，则返回true;否则返回false。

获取设备打开状态值

bool isOpen() const;
	如果设备处于打开状态，则返回true;否则返回false。
	如果一个设备可以被读和/或写，那么它就是打开的。
	默认情况下，如果openMode()返回NotOpen，则此函数返回false。

获取设备可读状态值

bool isReadable() const;
	如果数据可以从设备读取，则返回true;否则返回false。
	使用bytesAvailable()来确定可以读取多少字节。
	这是一个方便的函数，用于检查设备的OpenMode是否包含ReadOnly标志。

获取设备可写状态值

bool isWritable() const;
	如果数据可以写入设备，则返回true;否则返回false。
	这是一个方便的函数，用于检查设备的OpenMode是否包含WriteOnly标志。

获取设备是否是顺序的

virtual bool isSequential() const;
	如果此设备是顺序的，则返回true;否则返回false。
	顺序设备，与随机访问设备相反，没有开始、结束、大小或当前位置的概念，并且它们不支持查找。
	只有当设备报告数据可用时，才能从设备读取数据。顺序设备最常见的例子是网络套接字。
	在Unix上，特殊文件，如/dev/zero和fifo管道是顺序的。
	另一方面，常规文件确实支持随机访问。
	它们同时具有大小和当前位置，并且还支持在数据流中向后和向前查找。
	常规文件是非顺序的。

获取通道

int readChannelCount() const;
	如果设备处于打开状态，则返回可用读通道的数量;否则返回0。
	这个函数是在Qt 5.7中引入的。
    
int writeChannelCount() const;
	如果设备是打开的，返回可用写通道的数目;否则返回0。
	这个函数是在Qt 5.7中引入的。 

int currentReadChannel() const;
	返回当前读通道的索引。
	这个函数是在Qt 5.7中引入的。

void setCurrentReadChannel(int channel);
	将QIODevice的当前读通道设置为给定通道。当前输入通道由函数read()、readAll()、readLine()和getChar()使用。
	它还决定哪个通道触发QIODevice发出readyRead()。
	这个函数是在Qt 5.7中引入的。

int currentWriteChannel() const;
	返回当前写通道的索引。
	这个函数是在Qt 5.7中引入的。
    
void setCurrentWriteChannel(int channel);
	将QIODevice的当前写通道设置为给定的通道。当前输出通道由函数write()、putChar()使用。
	它还决定哪个通道触发QIODevice发出bytesWritten()。
	这个函数是在Qt 5.7中引入的。

以指定的模式打开设备

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

关闭设备

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

获取读写位置

virtual qint64 pos() const;
	对于随机访问设备，此函数返回数据写入或读取的位置。
	对于顺序设备或封闭设备，其中没有“当前位置”的概念，返回0。
	设备的当前读/写位置是由QIODevice内部维护的，所以不需要重新实现这个功能。
	当子类化QIODevice时，使用QIODevice::seek()通知QIODevice关于设备位置的变化。

获取设备大小

virtual qint64 size() const;
	对于打开的随机访问设备，此函数返回设备的大小。对于打开的顺序设备，返回bytesAvailable()。
	如果设备关闭，返回的大小将不反映设备的实际大小。

调整设备读写位置

virtual bool seek(qint64 pos);
	对于随机访问设备，此函数将当前位置设置为pos，成功时返回true，发生错误时返回false。
	对于顺序设备，默认行为是产生警告并返回false。
	当子类化QIODevice时，你必须在函数的开始调用QIODevice::seek()，
	以确保与QIODevice的内置缓冲区的完整性。

判断是否到达文件尾部

virtual bool atEnd() const;
	如果当前读写位置位于设备的末尾(即设备上没有更多可读取的数据)，则返回true;否则返回false。
	对于某些设备，即使有更多的数据要读取，atEnd()也可以返回true。
	这种特殊情况仅适用于直接响应您调用read()的设备(例如，Unix和macOS上的/dev或/proc文件，
	或所有平台上的控制台输入/ stdin)。

复位读写设备

virtual bool reset();
	查找随机存取设备输入的开始。成功时返回true;否则返回false(例如，如果设备未打开)。
	注意，当在QFile上使用QTextStream时，调用QFile上的reset()将不会得到预期的结果，
	因为QTextStream缓冲了文件。使用QTextStream::seek()函数代替。

可读已写字符值

virtual qint64 bytesAvailable() const;
	返回可用于读取的字节数。此函数通常用于顺序设备，用于在读取之前确定要在缓冲区中分配的字节数。
	重新实现此函数的子类必须调用基本实现，以便包含QIODevice的缓冲区大小。例子:
	qint64 CustomDevice::bytesAvailable() const
	{
		return buffer.size() + QIODevice::bytesAvailable();
	}
	
virtual qint64 bytesToWrite() const;   	
	对于缓冲设备，此函数返回等待写入的字节数。对于没有缓冲区的设备，此函数返回0。
	重新实现此函数的子类必须调用基本实现，以便包含QIODevice的缓冲区大小。

读取设置接收缓冲区数据

qint64 read(char *data, qint64 maxlen);
	从设备读取最多maxSize字节为数据，并返回读取的字节数。
	如果发生错误，例如试图从以WriteOnly模式打开的设备中读取时，此函数返回-1。
	当没有数据可读时返回0。然而，读取超过流的结尾被认为是错误，
	因此在这些情况下，此函数返回-1(即在关闭的套接字上读取或在进程死亡后读取)。
	
QByteArray read(qint64 maxlen);
	这是一个重载函数。
	从设备中最多读取maxSize字节，并将读取的数据作为QByteArray返回。
	该函数没有报告错误的方法;返回一个空的QByteArray可能意味着当前没有数据可读，或者发生了错误。
	    
QByteArray readAll();
	从设备中读取所有剩余的数据，并将其作为字节数组返回。
	这个函数没有报告错误的方法;返回一个空的QByteArray可能意味着当前没有数据可读，或者发生了错误。
	    
qint64 readLine(char *data, qint64 maxlen);
	该函数从设备读取一行ASCII字符(最大maxSize-1字节)，将字符存储在data中，并返回读取的字节数。如果一行无法读取但没有发生错误，则此函数返回0。如果发生错误，此函数返回可读取内容的长度，如果没有读取，则返回-1。
	结束的'\0'字节总是附加到data后，因此maxSize必须大于1。
	一直读取数据，直到满足以下条件之一:
	读取第一个'\n'字符。
	maxSize -读取1个字节。
	设备端数据被检测到。
	换行符('\n')包含在缓冲区中。如果在读取maxSize-1字节之前没有遇到换行符，则不会向缓冲区插入换行符。在windows上，换行符被替换为'\n'。
	这个函数调用readLineData()，它通过重复调用getChar()来实现。您可以通过在自己的子类中重新实现readLineData()来提供更有效的实现。
    
QByteArray readLine(qint64 maxlen = 0);
	这是一个重载函数。
	从设备中读取一行，但不超过maxSize字符，并以字节数组的形式返回结果。
	这个函数没有报告错误的方法;返回一个空的QByteArray可能意味着当前没有数据可读，或者发生了错误。

virtual bool canReadLine() const;
	如果可以从设备读取整行数据，则返回true;否则返回false。
	请注意，没有缓冲的设备无法确定可以读取的内容，因此总是返回false。
	这个函数通常与readyRead()信号一起调用。
	重新实现此函数的子类必须调用基实现，以便包含QIODevice缓冲区的内容。例子:
	bool CustomDevice::canReadLine() const
	{
		return buffer.contains('\n') || QIODevice::canReadLine();
	}

void startTransaction();
	完成读事务。
	对于顺序设备，事务期间记录在内部缓冲区中的所有数据将被丢弃。
	这个函数是在Qt 5.7中引入的。

void commitTransaction();
	完成读事务。
	对于顺序设备，事务期间记录在内部缓冲区中的所有数据将被丢弃。
	这个函数是在Qt 5.7中引入的。

void rollbackTransaction();
	回滚读事务。
	将输入流恢复到startTransaction()调用的点。
	此函数通常用于在提交事务之前检测到读取不完整时回滚事务。
	这个函数是在Qt 5.7中引入的。

bool isTransactionStarted() const;
	如果设备上的事务正在进行，则返回true，否则返回false。
	这个函数是在Qt 5.7中引入的。

向设备写入数据

qint64 write(const char *data, qint64 len);
	从data向设备写入最多maxSize字节的数据。返回实际写入的字节数，如果发生错误则返回-1。

qint64 write(const char *data);
	这是一个重载函数。 
	将数据从以零结尾的8位字符字符串写入设备。返回实际写入的字节数，如果发生错误则返回-1。
	这个等价于
	QIODevice::write(data, qstrlen(data));
	
inline qint64 write(const QByteArray &data)
	{ return write(data.constData(), data.size()); }
	这是一个重载函数。
	将byteArray的内容写入设备。返回实际写入的字节数，如果发生错误则返回-1。

qint64 peek(char *data, qint64 maxlen);
	从设备读取最多maxSize字节为数据，没有副作用(即，如果在peek()之后调用read()，您将获得相同的数据)。返回读取的字节数。如果发生错误，例如试图窥视以WriteOnly模式打开的设备时，此函数返回-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;
	}

QByteArray peek(qint64 maxlen);
	这是一个重载函数。
	从设备中窥视最多maxSize字节，返回作为QByteArray窥视的数据。
	这个函数没有报告错误的方法;返回一个空的QByteArray可能意味着当前没有数据可供窥视，或者发生了错误。

qint64 skip(qint64 maxSize);
	从设备中跳过最多maxSize字节。返回实际跳过的字节数，如果出错则返回-1。
	这个函数不等待，只丢弃已经可以读取的数据。
	如果在文本模式下打开设备，则行结束符将被转换为'\n'符号，并与read()和peek()行为相同，作为单个字节计数。
	此函数适用于所有设备，包括无法seek()的顺序设备。它被优化为在调用peek()之后跳过不需要的数据。
	对于随机访问设备，skip()可用于从当前位置向前查找。不允许使用负的maxSize值。
	这个函数在Qt 5.10中被引入。

virtual bool waitForReadyRead(int msecs);
	阻塞，直到有新的数据可供读取，并且readyRead()信号已经发出，或者直到msecs毫秒过去。
	如果msecs为-1，则该函数不会超时。
	如果有新的数据可供读取，则返回true;否则返回false(如果操作超时或发生错误)。
	此函数可以在没有事件循环的情况下运行。它在编写非gui应用程序和在非gui线程中执行I/O操作时非常有用。
	如果从连接到readyRead()信号的插槽内调用，readyRead()将不会被重新发出。
	重新实现此函数以为自定义设备提供阻塞API。默认实现不做任何事情，并返回false。
	警告:从主线程(GUI)调用此函数可能会导致用户界面冻结。

virtual bool waitForBytesWritten(int msecs);
	对于缓冲的设备，这个函数会一直等待，直到缓冲写入数据的有效负载被写入设备，并且bytesWritten()信号已经发出，或者直到msecs毫秒过去。如果msecs为-1，则该函数不会超时。对于未缓冲的设备，它立即返回。
	如果将数据负载写入设备，则返回true;否则返回false(即，如果操作超时，或者发生错误)。
	此函数可以在没有事件循环的情况下运行。它在编写非gui应用程序和在非gui线程中执行I/O操作时非常有用。
	如果从连接到bytesWritten()信号的插槽内调用，则不会重新发出bytesWritten()。
	重新实现此函数以为自定义设备提供阻塞API。默认实现不做任何事情，并返回false。
	警告:从主线程(GUI)调用此函数可能会导致用户界面冻结。

void ungetChar(char c);
	将字符c放回设备，并减少当前位置，除非位置为0。此函数通常用于“撤消”getChar()操作，例如在编写回溯解析器时。
	如果之前没有从设备中读取c，则行为未定义。
	注意:当事务正在进行时，此功能不可用。

bool putChar(char c);
	将字符c写入设备。成功时返回true;否则返回false。

bool getChar(char *c);
	从设备中读取一个字符并将其存储在c中。如果c为0，则丢弃该字符。成功时返回true;否则返回false。

QString errorString() const;
	返回上一次发生的设备错误的人类可读的描述。

设备状态变更时发送的信号

Q_SIGNALS:
void readyRead();
	每当从设备当前读取通道中读取新数据时，该信号就会发出一次。它只会在有新数据可用时再次发出，
	例如当新的网络数据负载到达您的网络套接字时，或者当一个新的数据块被附加到您的设备时。
	readyRead()不是递归触发的;如果您重新进入事件循环或在连接到readyRead()信号的插槽中调用waitForReadyRead()，则信号将不会被重新发出(尽管waitForReadyRead()可能仍然返回true)。
	对于实现从QIODevice派生类的开发人员，请注意:当新数据到达时，您应该总是发出readyRead()(不要仅仅因为缓冲区中仍有数据要读取而发出)。不要在其他情况下发出readyRead()。

void channelReadyRead(int channel);
	当有新的数据可以从设备中读取时，就会发出这个信号。channel参数被设置为数据到达的读通道的索引。与readyRead()不同的是，无论当前的读通道是什么，都会触发它。
	channelReadyRead()可以递归地触发——即使是对同一个通道。
	这个函数是在Qt 5.7中引入的

void bytesWritten(qint64 bytes);
	每次将有效载荷的数据写入设备的当前写入通道时，都会发出此信号。bytes参数设置为在此有效负载中写入的字节数。
	bytesWritten()不是递归发出的;如果您重新进入事件循环或在连接到bytesWritten()信号的插槽中调用waitForBytesWritten()，则信号将不会被重新发出(尽管waitForBytesWritten()可能仍然返回true)。

void channelBytesWritten(int channel, qint64 bytes);
	每次将有效载荷的数据写入设备时，都会发出此信号。bytes参数被设置为在此有效负载中写入的字节数，而channel是它们被写入的通道。与bytesWritten()不同的是，无论当前的写通道是什么，都会发出该函数。
	channelBytesWritten()可以递归地发出——即使是对同一个通道。
	这个函数是在Qt 5.7中引入的。

void aboutToClose();
	该信号在设备即将关闭时发出。如果在设备关闭之前有需要执行的操作
	(例如，如果在单独的缓冲区中有需要写入设备的数据)，请连接此信号。

void readChannelFinished();
	当该设备的输入(读)流关闭时发出该信号。一旦检测到关闭，它就会发出，
	这意味着可能仍然有可用的数据可供read()读取。
	这个函数是在Qt 4.4中引入的。

protected:

QIODevice(QIODevicePrivate &dd, QObject *parent = nullptr);

virtual qint64 readData(char *data, qint64 maxlen) = 0;
	从设备读取最大maxSize字节为数据，并返回读取的字节数，如果发生错误则返回-1。
	如果没有要读取的字节，并且永远不会有更多的字节可用(示例包括套接字关闭，管道关闭，子进程完成)，则此函数返回-1。
	这个函数由QIODevice调用。在创建QIODevice的子类时重新实现这个函数。
	在重新实现此函数时，重要的是该函数在返回之前读取所有所需的数据。这是QDataStream能够对类进行操作所必需的。QDataStream假定已读取所有请求的信息，因此如果出现问题，就不会重试读取。
	该函数可以在maxSize为0时调用，该值可用于执行读后操作。

virtual qint64 readLineData(char *data, qint64 maxlen);
	将最大maxSize的字符读入data并返回所读的字符数。
	该函数由readLine()调用，并使用getChar()提供其基本实现。缓冲设备可以通过重新实现这个函数来提高readLine()的性能。
	readLine()将'\0'字节追加到data;readLineData()不需要这样做。
	如果您重新实现这个函数，请注意返回正确的值:它应该返回本行读取的字节数，包括结束换行符，如果此时没有要读取的行，则返回0。如果发生错误，当且仅当没有读取字节时，它应该返回-1。读取超过EOF被认为是错误。

virtual qint64 writeData(const char *data, qint64 len) = 0;
	从数据向设备写入最多maxSize字节。返回写入的字节数，如果发生错误则返回-1。
	这个函数由QIODevice调用。在创建QIODevice的子类时重新实现这个函数。
	当重新实现这个函数时，重要的是这个函数在返回之前写所有可用的数据。这是QDataStream能够对类进行操作所必需的。QDataStream假定所有信息都已写入，因此如果出现问题，就不会重试写入。

调整设备的打开模式

void setOpenMode(OpenMode openMode);
	设置设备的OpenMode为openMode。如果标志在设备打开后改变，调用这个函数来设置打开模式。

设置错误信息

void setErrorString(const QString &errorString);
	将上次发生的设备错误的人类可读描述设置为str。

private:
Q_DECLARE_PRIVATE(QIODevice)
Q_DISABLE_COPY(QIODevice)
};