QIODevice Class

The QIODevice class is the abstract base class of all I/O devices. More…

List of all members, including inherited members

Public Functions

Signals

Protected Functions

Detailed Description

QIODevice provides the common interface for devices that can read and write blocks of bytes, such as QFile, QBuffer and QTemporaryFile. A subclass implements readData() and writeData(), and usually reimplements open(), close(), pos(), size() and seek().

Reading and writing go through read(), readLine(), readAll(), write() and friends. These check that the device is open in the right mode, then call readData() or writeData(). For sequential devices (see isSequential()), peek() and ungetChar() keep look-ahead bytes in an internal buffer, which read() and readLine() consume first.

The device is not thread-safe, and the signals are emitted only by subclasses that choose to emit them.

See also QFile, QBuffer, QTextStream and QDataStream.

Differences from Qt

Member Function Documentation

QIODevice::QIODevice()

Constructs a device with no parent. The device is not open.

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

Constructs a device with the given parent. The device is not open.

[override] QIODevice::~QIODevice()

Destroys the device. The device is not closed automatically; subclasses close it in their own destructors.

[signal] void QIODevice::aboutToClose()

This signal is emitted when the device is about to close, before close() releases any resources.

See also close().

[virtual] bool QIODevice::atEnd() const

Returns true if the device is open and there is no more data to read; otherwise returns false.

See also bytesAvailable() and read().

[virtual] qint64 QIODevice::bytesAvailable() const

Returns the number of bytes that are available for reading.

The base implementation returns the number of look-ahead bytes buffered by peek() or ungetChar(). Subclasses reimplement this function and add the base implementation's result to their own.

See also bytesToWrite(), read() and atEnd().

[virtual] qint64 QIODevice::bytesToWrite() const

For buffered devices, returns the number of bytes waiting to be written. The base implementation returns 0.

See also bytesAvailable().

[signal] void QIODevice::bytesWritten(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. It is only emitted by subclasses that buffer writes.

See also readyRead().

[virtual] bool QIODevice::canReadLine() const

Returns true if a complete line of data can be read from the device; otherwise returns false.

The base implementation only looks at the look-ahead buffer.

See also 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 the number of bytes that were written, and channel is the index of the channel they went to. Unlike bytesWritten(), it is emitted whatever the current write channel is.

This function was introduced in 5.7.

See also bytesWritten() and channelReadyRead().

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

This signal is emitted when new data is available for reading on the channel with the index channel. Unlike readyRead(), it is emitted whatever the current read channel is.

This function was introduced in 5.7.

See also readyRead() and channelBytesWritten().

[virtual] void QIODevice::close()

First emits aboutToClose(), then closes the device and sets its open mode to NotOpen. Any buffered look-ahead data is discarded. Does nothing if the device is not open.

Subclasses reimplement this function to release their resources and call the base implementation.

See also open() and aboutToClose().

void QIODevice::commitTransaction()

Completes a read transaction. The data read since startTransaction() is consumed. Prints a warning if no transaction is in progress.

This function was introduced in 5.7.

See also startTransaction() and rollbackTransaction().

int QIODevice::currentReadChannel() const

Returns the index of the current read channel, the one that read(), readLine(), peek() and bytesAvailable() work on.

This function was introduced in 5.7.

See also setCurrentReadChannel() and readChannelCount().

int QIODevice::currentWriteChannel() const

Returns the index of the current write channel, the one that write() sends to.

This function was introduced in 5.7.

See also setCurrentWriteChannel() and writeChannelCount().

QString QIODevice::errorString() const

Returns a human-readable description of the last device error, or "Unknown error" if no error string has been set.

See also setErrorString().

bool QIODevice::getChar(char *c)

Reads one character from the device and stores it in c, unless c is nullptr. Returns true on success; otherwise returns false.

See also putChar(), ungetChar() and read().

bool QIODevice::isOpen() const

Returns true if the device is open; otherwise returns false. A device is open if its open mode is not NotOpen.

See also openMode(), open() and close().

bool QIODevice::isReadable() const

Returns true if data can be read from the device; otherwise returns false.

See also isWritable() and openMode().

[virtual] bool QIODevice::isSequential() const

Returns true if the device is a sequential device, which has no notion of position and cannot seek; otherwise returns false. The base implementation returns false.

See also seek() and pos().

bool QIODevice::isTextModeEnabled() const

Returns true if the Text flag is set on the open mode; otherwise returns false.

See also setTextModeEnabled().

bool QIODevice::isTransactionStarted() const

Returns true if a transaction is in progress on the device; otherwise returns false.

This function was introduced in 5.7.

See also startTransaction().

bool QIODevice::isWritable() const

Returns true if data can be written to the device; otherwise returns false.

See also isReadable() and openMode().

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

Opens the device and sets its open mode to mode. Returns true if successful; otherwise returns false.

The base implementation stores mode, discards any buffered data and clears the error string, and always succeeds. Subclasses reimplement this function, call it once the device is open and return true.

See also close(), openMode() and isOpen().

OpenMode QIODevice::openMode() const

Returns the mode in which the device has been opened, or NotOpen.

See also open() and setOpenMode().

QByteArray QIODevice::peek(qint64 maxSize)

This is an overloaded function.

Reads at most maxSize bytes from the device without consuming them, and returns them as a byte array.

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

Reads at most maxSize bytes from the device into data, without consuming them, and returns the number of bytes read. Returns -1 if the device is not open for reading.

Random-access devices read and then seek back; sequential devices keep the bytes in a look-ahead buffer.

See also read() and ungetChar().

[virtual] qint64 QIODevice::pos() const

Returns the current read/write position of the device. The base implementation returns 0.

See also seek() and size().

bool QIODevice::putChar(char c)

Writes the character c to the device. Returns true on success; otherwise returns false.

See also getChar() and write().

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

Reads at most maxSize bytes from the device into data, and returns the number of bytes read. Returns -1 if the device is not open for reading or if an error occurs before any byte is read, and 0 if maxSize is not positive or no data could be read.

Look-ahead data buffered by peek() or ungetChar() is returned first.

See also readData(), readLine() and write().

QByteArray QIODevice::read(qint64 maxSize)

This is an overloaded function.

Reads at most maxSize bytes from the device and returns them as a QByteArray. Returns an empty byte array if maxSize is not positive or if nothing could be read.

QByteArray QIODevice::readAll()

Reads all remaining data from the device and returns it as a byte array.

The data is read in chunks until read() returns no more data, so this function does not wait for more data on a sequential device.

See also read() and readLine().

int QIODevice::readChannelCount() const

Returns the number of read channels if the device is open for reading; otherwise returns 0. A device has one read channel, except QProcess, which has one for the standard output of the process and one for its standard error.

This function was introduced in 5.7.

See also writeChannelCount() and setCurrentReadChannel().

[signal] void QIODevice::readChannelFinished()

This signal is emitted when the input (reading) stream is closed in this device. It is only emitted by subclasses that support it.

See also atEnd().

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

Reads up to maxSize bytes from the device into data, and returns the number of bytes read, or -1 if an error occurred. Subclasses must implement this function.

See also read() and writeData().

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

Reads a line of at most maxSize - 1 bytes into data, terminates it with a '\0' byte, and returns the number of bytes read, not counting the terminator. The newline, if found, is included.

Returns -1 if the device is not open for reading, and 0 if maxSize is less than 2 or nothing could be read.

See also readData(), canReadLine() and readAll().

QByteArray QIODevice::readLine(qint64 maxSize = 0)

This is an overloaded function.

Reads a line from the device, but no more than maxSize bytes, and returns the result as a byte array. If maxSize is 0, the line length is not limited. The newline, if found, is included.

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

Reads up to maxSize bytes from the device into data, stopping after the first newline, and returns the number of bytes read.

The base implementation calls readData() for one byte at a time. Subclasses reimplement it when they can find the line end more efficiently. Look-ahead data is handled by readLine() before this function is called.

See also readLine() and readData().

bool QIODevice::readLineInto(QByteArray *line, qint64 maxSize = 0)

Reads a line from the device into line, replacing its contents, but no more than maxSize bytes; a maxSize of 0 does not limit the line length. The newline, if found, is included. If line is nullptr, the line is read and discarded.

Returns true if any data was read; otherwise returns false and leaves line empty.

This function was introduced in 6.9.

See also readLine() and canReadLine().

[signal] void QIODevice::readyRead()

This signal is emitted once every time new data is available for reading from the device. It is only emitted by subclasses that receive data asynchronously.

See also bytesWritten() and bytesAvailable().

[virtual] bool QIODevice::reset()

Seeks to the start of the device. Returns true on success; otherwise returns false.

See also seek().

void QIODevice::rollbackTransaction()

Rolls back a read transaction, restoring the read position to where startTransaction() was called, so that the same data is read again. Prints a warning if no transaction is in progress.

This function was introduced in 5.7.

See also startTransaction() and commitTransaction().

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

Seeks to position pos in the device. Returns true on success; otherwise returns false.

The base implementation only discards the look-ahead buffer and always returns true. Subclasses that support random access reimplement this function and call it first.

See also pos(), reset() and isSequential().

void QIODevice::setCurrentReadChannel(int channel)

Sets the current read channel to channel, the index of one of the readChannelCount() channels. read(), readLine(), peek(), bytesAvailable() and readyRead() then refer to that channel. Data that peek() or ungetChar() left in the buffer of the previous channel stays with that channel.

The channel can be chosen before the device is open. This function prints a warning and does nothing while a transaction is in progress.

process.setCurrentReadChannel(QProcess::StandardError);
const QByteArray errors = process.readAll();

This function was introduced in 5.7.

See also currentReadChannel() and channelReadyRead().

void QIODevice::setCurrentWriteChannel(int channel)

Sets the current write channel to channel, the index of one of the writeChannelCount() channels. Does nothing if channel is negative.

This function was introduced in 5.7.

See also currentWriteChannel() and channelBytesWritten().

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

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

See also errorString().

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

Sets the open mode of the device to mode without any other effect. Subclasses call this from their open() reimplementations.

See also openMode() and open().

void QIODevice::setTextModeEnabled(bool enabled)

If enabled is true, sets the Text flag on the device's open mode; otherwise clears it.

See also isTextModeEnabled() and openMode().

[virtual] qint64 QIODevice::size() const

Returns the size of the device. For a sequential device this is bytesAvailable(); otherwise the base implementation returns 0.

See also pos() and bytesAvailable().

qint64 QIODevice::skip(qint64 maxSize)

Skips up to maxSize bytes of data and returns the number of bytes actually skipped, or -1 if the device is not open for reading or an error occurred. Look-ahead data is skipped first; the rest is passed to skipData().

This function was introduced in 5.10.

See also read(), peek() and skipData().

[virtual, protected] qint64 QIODevice::skipData(qint64 maxSize)

Skips up to maxSize bytes and returns the number of bytes skipped, or -1 on error. skip() calls this function after it has skipped buffered look-ahead data.

The base implementation seeks forward on a random-access device, without moving past size(), and reads and discards the data on a sequential device. Subclasses reimplement it when they can skip data more cheaply.

This function was introduced in 6.0.

See also skip().

void QIODevice::startTransaction()

Starts a read transaction on the device.

Inside a transaction, data read from the device is kept so that rollbackTransaction() can restore the read position to where the transaction started. Call commitTransaction() to accept the data that was read. This is useful for parsing a message that may not have arrived completely:

socket->startTransaction();
QByteArray header = socket->read(8);
if (header.size() < 8) {
    socket->rollbackTransaction(); // wait for more data
    return;
}
socket->commitTransaction();

Starting a transaction while one is in progress prints a warning and does nothing. Writing is not affected by transactions.

This function was introduced in 5.7.

See also commitTransaction(), rollbackTransaction() and isTransactionStarted().

void QIODevice::ungetChar(char c)

Puts the character c back into the device, so that the next read returns it. Does nothing if the device is not open for reading.

On a random-access device this seeks back one byte and does not modify the stored data, so c should be the byte that was just read.

See also getChar() and peek().

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

Waits until buffered data has been written to the device and bytesWritten() has been emitted, or until msecs milliseconds have passed. The base implementation does nothing and returns false.

See also waitForReadyRead().

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

Waits until data is available for reading and readyRead() has been emitted, or until msecs milliseconds have passed. The base implementation does nothing and returns false.

See also waitForBytesWritten().

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

Writes at most maxSize bytes of data from data to the device, and returns the number of bytes written. Returns -1 if the device is not open for writing or if an error occurs, and 0 if maxSize is not positive.

See also read(), writeData() and putChar().

qint64 QIODevice::write(const char *data)

This is an overloaded function.

Writes the zero-terminated string data to the device, not including the terminating null byte, and returns the number of bytes written.

qint64 QIODevice::write(const QByteArray &data)

This is an overloaded function.

Writes the contents of data to the device and returns the number of bytes written.

int QIODevice::writeChannelCount() const

Returns the number of write channels if the device is open for writing; otherwise returns 0.

This function was introduced in 5.7.

See also readChannelCount() and setCurrentWriteChannel().

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

Writes up to maxSize bytes from data to the device. Returns the number of bytes written, or -1 if an error occurred. Subclasses must implement this function.

See also write() and readData().