QIODevice 类

成员函数文档编制

QIODevice:: QIODevice ()

构造 QIODevice 对象。

QIODevice:: QIODevice ( QObject * parent )

构造 QIODevice 对象采用给定 parent .

[virtual] QIODevice:: ~QIODevice ()

析构函数是虚拟的，且 QIODevice 是抽象基类。此析构函数不调用 close ()，但子类析构函数可能会。若有疑问，调用 close () 之后销毁 QIODevice .

[signal] void QIODevice:: aboutToClose ()

This signal is emitted when the device is about to close. Connect this signal if you have operations that need to be performed before the device closes (e.g., if you have data in a separate buffer that needs to be written to the device).

[virtual] bool QIODevice:: atEnd () const

返回 true 若当前读写位置在设备的末端 (即：设备中没有更多可供读取的数据)；否则返回 false .

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

另请参阅 bytesAvailable (), read ()，和 isSequential ().

[virtual] qint64 QIODevice:: bytesAvailable () const

Returns the number of bytes that are available for reading. This function is commonly used with sequential devices to determine the number of bytes to allocate in a buffer before reading.

Subclasses that reimplement this function must call the base implementation in order to include the size of the buffer of QIODevice 。范例：

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

另请参阅 bytesToWrite (), readyRead ()，和 isSequential ().

[virtual] qint64 QIODevice:: bytesToWrite () const

For buffered devices, this function returns the number of bytes waiting to be written. For devices with no buffer, this function returns 0.

Subclasses that reimplement this function must call the base implementation in order to include the size of the buffer of QIODevice .

另请参阅 bytesAvailable (), bytesWritten ()，和 isSequential ().

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

This signal is emitted every time a payload of data has been written to the device's current write channel. The bytes 自变量是在此有效负载中写入的设置字节数。

bytesWritten() is not emitted recursively; if you reenter the event loop or call waitForBytesWritten () inside a slot connected to the bytesWritten() signal, the signal will not be reemitted (although waitForBytesWritten () may still return 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 )

This signal is emitted every time a payload of data has been written to the device. The bytes argument is set to the number of bytes that were written in this payload, while channel is the channel they were written to. Unlike bytesWritten (), it is emitted regardless of the current write channel .

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

该函数在 Qt 5.7 引入。

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

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

This signal is emitted when new data is available for reading from the device. The channel argument is set to the index of the read channel on which the data has arrived. Unlike readyRead (), it is emitted regardless of the current read channel .

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

该函数在 Qt 5.7 引入。

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

[virtual] void QIODevice:: close ()

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

另请参阅 setOpenMode () 和 OpenMode .

void QIODevice:: commitTransaction ()

完成读取事务。

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

该函数在 Qt 5.7 引入。

另请参阅 startTransaction () 和 rollbackTransaction ().

int QIODevice:: currentReadChannel () const

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

该函数在 Qt 5.7 引入。

另请参阅 setCurrentReadChannel (), readChannelCount ()，和 QProcess .

int QIODevice:: currentWriteChannel () const

Returns the the index of the current write channel.

该函数在 Qt 5.7 引入。

另请参阅 setCurrentWriteChannel () 和 writeChannelCount ().

QString QIODevice:: errorString () const

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

另请参阅 setErrorString ().

bool QIODevice:: getChar ( char * c )

从设备读取 1 字符并把它存储在 c 。若 c is 0, the character is discarded. Returns true 当成功时；否则返回 false .

另请参阅 read (), putChar ()，和 ungetChar ().

bool QIODevice:: isOpen () const

返回 true 若设备是打开的；否则返回 false 。设备是打开的若可以读/写。默认情况下，此函数返回 false if openMode () 返回 NotOpen .

另请参阅 openMode () 和 OpenMode .

bool QIODevice:: isReadable () const

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

这是方便的校验函数若 OpenMode 的设备包含 ReadOnly 标志。

另请参阅 openMode () 和 OpenMode .

[virtual] bool QIODevice:: isSequential () const

返回 true 若此设备是顺序的；否则返回 false。

Sequential devices, as opposed to a random-access devices, have no concept of a start, an end, a size, or a current position, and they do not support seeking. You can only read from the device when it reports that data is available. The most common example of a sequential device is a network socket. On Unix, special files such as /dev/zero and fifo pipes are sequential.

Regular files, on the other hand, do support random access. They have both a size and a current position, and they also support seeking backwards and forwards in the data stream. Regular files are non-sequential.

另请参阅 bytesAvailable ().

bool QIODevice:: isTextModeEnabled () const

返回 true 若 文本 标志被启用；否则返回 false .

另请参阅 setTextModeEnabled ().

bool QIODevice:: isTransactionStarted () const

返回 true 若事务在设备上正在进行中，否则 false .

该函数在 Qt 5.7 引入。

另请参阅 startTransaction ().

bool QIODevice:: isWritable () const

返回 true 若可以把数据写入设备；否则返回 false。

这是方便的校验函数若 OpenMode 的设备包含 WriteOnly 标志。

另请参阅 openMode () 和 OpenMode .

[virtual] bool QIODevice:: open ( OpenMode mode )

打开设备并设置其 OpenMode to mode 。返回 true 若成功；否则返回 false . This function should be called from any reimplementations of open() or other functions that open the device.

另请参阅 openMode () 和 OpenMode .

OpenMode QIODevice:: openMode () const

返回设备被打开的模式；即： ReadOnly or WriteOnly .

另请参阅 setOpenMode () 和 OpenMode .

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

读取最多 maxSize 字节从设备到 data ，无副作用 (即：若调用 read () after peek(), you will get the same data). Returns the number of bytes read. If an error occurs, such as when attempting to peek a device opened in WriteOnly 模式，此函数返回 -1。

0 is returned when no more data is available for reading.

范例：

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

该函数在 Qt 4.1 引入。

另请参阅 read ().

QByteArray QIODevice:: peek ( qint64 maxSize )

这是重载函数。

窥视最多 maxSize 字节从设备，返回窥视数据作为 QByteArray .

范例：

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

此函数没有办法报告错误；返回空 QByteArray can mean either that no data was currently available for peeking, or that an error occurred.

该函数在 Qt 4.1 引入。

另请参阅 read ().

[virtual] qint64 QIODevice:: pos () const

For random-access devices, this function returns the position that data is written to or read from. For sequential devices or closed devices, where there is no concept of a "current position", 0 is returned.

The current read/write position of the device is maintained internally by QIODevice , so reimplementing this function is not necessary. When subclassing QIODevice ，使用 QIODevice::seek () to notify QIODevice about changes in the device position.

另请参阅 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。

该函数在 Qt 5.7 引入。

另请参阅 writeChannelCount () 和 QProcess .

[signal] void QIODevice:: readChannelFinished ()

This signal is emitted when the input (reading) stream is closed in this device. It is emitted as soon as the closing is detected, which means that there might still be data available for reading with read ().

该函数在 Qt 4.4 引入。

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

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

读取到 maxSize 字节从设备到 data ，并返回读取字节数；返回 -1 若发生错误。

If there are no bytes to be read and there can never be more bytes available (examples include socket closed, pipe closed, sub-process finished), this function returns -1.

此函数被调用由 QIODevice 。重实现此函数，当创建子类为 QIODevice .

When reimplementing this function it is important that this function reads all the required data before returning. This is required in order for QDataStream 能够在类中运转。 QDataStream assumes all the requested information was read and therefore does not retry reading if there was a problem.

This function might be called with a maxSize of 0, which can be used to perform post-reading operations.

另请参阅 read (), readLine ()，和 writeData ().

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

This function reads a line of ASCII characters from the device, up to a maximum of maxSize - 1 bytes, stores the characters in data , and returns the number of bytes read. If a line could not be read but no error ocurred, this function returns 0. If an error occurs, this function returns the length of what could be read, or -1 if nothing was read.

A terminating '\0' byte is always appended to data , so maxSize must be larger than 1.

Data is read until either of the following conditions are met:

• The first '\n' character is read.
• maxSize - 1 bytes are read.
• The end of the device data is detected.

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

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
    }
}
							

The newline character ('\n') is included in the buffer. If a newline is not encountered before maxSize - 1 bytes are read, a newline will not be inserted into the buffer. On windows newline characters are replaced with '\n'.

此函数调用 readLineData (), which is implemented using repeated calls to getChar (). You can provide a more efficient implementation by reimplementing readLineData () in your own subclass.

另请参阅 getChar (), read ()，和 write ().

QByteArray QIODevice:: readLine ( qint64 maxSize = 0)

这是重载函数。

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

此函数没有办法报告错误；返回空 QByteArray 可以意味着目前没有数据可供读取，或发生错误。

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

读取到 maxSize 字符到 data 并返回读取的字符数。

此函数被调用由 readLine (), and provides its base implementation, using getChar (). Buffered devices can improve the performance of readLine () by reimplementing this function.

readLine () appends a '\0' byte to data ; readLineData() does not need to do this.

If you reimplement this function, be careful to return the correct value: it should return the number of bytes read in this line, including the terminating newline, or 0 if there is no line to be read at this point. If an error occurs, it should return -1 if and only if no bytes were read. Reading past EOF is considered an error.

[signal] void QIODevice:: readyRead ()

This signal is emitted once every time new data is available for reading from the device's current read channel. It will only be emitted again once new data is available, such as when a new payload of network data has arrived on your network socket, or when a new block of data has been appended to your device.

readyRead() is not emitted recursively; if you reenter the event loop or call waitForReadyRead () inside a slot connected to the readyRead() signal, the signal will not be reemitted (although waitForReadyRead () may still return true).

注意： 开发者实现的类派生自 QIODevice : you should always emit readyRead() when new data has arrived (do not emit it only because there's data still to be read in your buffers). Do not emit readyRead() in other conditions.

另请参阅 bytesWritten ().

[virtual] bool QIODevice:: reset ()

Seeks to the start of input for random-access devices. Returns true on success; otherwise returns false (for example, if the device is not open).

Note that when using a QTextStream 在 QFile , calling reset() on the QFile will not have the expected result because QTextStream buffers the file. Use the QTextStream::seek () function instead.

另请参阅 seek ().

void QIODevice:: rollbackTransaction ()

回滚读取事务。

Restores the input stream to the point of the startTransaction () call. This function is commonly used to rollback the transaction when an incomplete read was detected prior to committing the transaction.

该函数在 Qt 5.7 引入。

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

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

For random-access devices, this function sets the current position to pos , returning true on success, or false if an error occurred. For sequential devices, the default behavior is to produce a warning and return false.

When subclassing QIODevice , you must call QIODevice::seek() at the start of your function to ensure integrity with QIODevice 's built-in buffer.

另请参阅 pos () 和 isSequential ().

void QIODevice:: setCurrentReadChannel ( int channel )

设置当前读取通道为 QIODevice 到给定 channel . The current input channel is used by the functions read (), readAll (), readLine ()，和 getChar (). It also determines which channel triggers QIODevice to emit readyRead ().

该函数在 Qt 5.7 引入。

另请参阅 currentReadChannel (), readChannelCount ()，和 QProcess .

void QIODevice:: setCurrentWriteChannel ( int channel )

Sets the current write channel of the QIODevice 到给定 channel . The current output channel is used by the functions write (), putChar (). It also determines which channel triggers QIODevice to emit bytesWritten ().

该函数在 Qt 5.7 引入。

另请参阅 currentWriteChannel () 和 writeChannelCount ().

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

Sets the human readable description of the last device error that occurred to str .

另请参阅 errorString ().

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

设置 OpenMode of the device to openMode . Call this function to set the open mode if the flags change after the device has been opened.

另请参阅 openMode () 和 OpenMode .

void QIODevice:: setTextModeEnabled ( bool enabled )

若 enabled 为 true，此函数设置 文本 标志在设备；否则 文本 flag is removed. This feature is useful for classes that provide custom end-of-line handling on a QIODevice .

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

另请参阅 isTextModeEnabled (), open ()，和 setOpenMode ().

[virtual] qint64 QIODevice:: size () const

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

若设备是关闭的，返回尺寸不会反映设备的实际大小。

另请参阅 isSequential () 和 pos ().

void QIODevice:: startTransaction ()

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

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

注意： 嵌套事务不被支持。

该函数在 Qt 5.7 引入。

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

void QIODevice:: ungetChar ( char c )

Puts the character c back into the device, and decrements the current position unless the position is 0. This function is usually called to "undo" a getChar () operation, such as when writing a backtracking parser.

若 c was not previously read from the device, the behavior is undefined.

注意： This function is not available while a transaction is in progress.

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

For buffered devices, this function waits until a payload of buffered written data has been written to the device and the bytesWritten () 信号已发射，或直到 msecs milliseconds have passed. If msecs is -1, this function will not time out. For unbuffered devices, it returns immediately.

返回 true if a payload of data was written to the device; otherwise returns false (i.e. if the operation timed out, or if an error occurred).

This function can operate without an event loop. It is useful when writing non-GUI applications and when performing I/O operations in a non-GUI thread.

If called from within a slot connected to the bytesWritten () signal, bytesWritten () will not be reemitted.

Reimplement this function to provide a blocking API for a custom device. The default implementation does nothing, and returns false .

警告： Calling this function from the main (GUI) thread might cause your user interface to freeze.

另请参阅 waitForReadyRead ().

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

阻塞直到有新的数据可供读取且 readyRead () 信号已发射，或直到 msecs 毫秒已过去。若 msecs 为 -1，此函数不会超时。

返回 true if new data is available for reading; otherwise returns false (if the operation timed out or if an error occurred).

This function can operate without an event loop. It is useful when writing non-GUI applications and when performing I/O operations in a non-GUI thread.

If called from within a slot connected to the readyRead () signal, readyRead () will not be reemitted.

Reimplement this function to provide a blocking API for a custom device. The default implementation does nothing, and returns false .

警告： Calling this function from the main (GUI) thread might cause your user interface to freeze.

另请参阅 waitForBytesWritten ().

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

写入最多 maxSize 字符的数据从 data 到设备。返回实际写入字节数；或 -1，若发生错误。

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

qint64 QIODevice:: write (const char * data )

这是重载函数。

把数据从 8 位字符的零终止字符串写入设备。返回实际写入字节数；或 -1，若发生错误。这相当于

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

该函数在 Qt 4.5 引入。

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

qint64 QIODevice:: write (const QByteArray & byteArray )

这是重载函数。

写入内容为 byteArray 到设备。返回实际写入字节数；或 -1，若发生错误。

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

int QIODevice:: writeChannelCount () const

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

该函数在 Qt 5.7 引入。

另请参阅 readChannelCount ().

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

写入直到 maxSize 字节来自 data 到设备。返回写入字节数，或 -1 若发生错误。

此函数被调用由 QIODevice 。重实现此函数，当创建子类为 QIODevice .

当重实现此函数时，此函数在返回前写入所有可用数据很重要。这是必需的为使 QDataStream 能够在类中运转。 QDataStream 假定所有信息已写入，因此不会试着再写入若存在问题。

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