|  | Home · Overviews · Examples

# QIODevice Class Reference
[com.trolltech.qt.core module]

The `QIODevice` class is the base interface class of all I/O devices in Qt. More...

Inherits `QObject`.

Inherited by `QAbstractSocket`, `QBuffer`, `QFile`, and `QProcess`.

## Detailed Description

The `QIODevice` class is the base interface class of all I/O devices in Qt.

`QIODevice` provides both a common implementation and an abstract interface for devices that support reading and writing of blocks of data, such as `QFile`, `QBuffer` and `QTcpSocket`. `QIODevice` is abstract and can not be instantiated, but it is common to use the interface it defines to provide device-independent I/O features. For example, Qt's XML classes operate on a `QIODevice` pointer, allowing them to be used with various devices (such as files and buffers).

Before accessing the device, `open` must be called to set the correct OpenMode (such as `ReadOnly` or `ReadWrite`). You can then write to the device with `write` or putChar(), and read by calling either `read`, `readLine`, or `readAll`. Call `close` when you are done with the device.

`QIODevice` distinguishes between two types of devices: random-access devices and sequential devices.

- Random-access devices support seeking to arbitrary positions using `seek`. The current position in the file is available by calling `pos`. `QFile` and `QBuffer` are examples of random-access devices.
- Sequential devices don't support seeking to arbitrary positions. The data must be read in one pass. The functions `pos` and `size` don't work for sequential devices. `QTcpSocket` and `QProcess` are examples of sequential devices.

You can use `isSequential` to determine the type of device.

`QIODevice` emits `readyRead` when new data is available for reading; for example, if new data has arrived on the network or if additional data is appended to a file that you are reading from. You can call `bytesAvailable` to determine the number of bytes that currently available for reading. It's common to use `bytesAvailable` together with the `readyRead` signal when programming with asynchronous devices such as `QTcpSocket`, where fragments of data can arrive at arbitrary points in time. `QIODevice` emits the `bytesWritten` signal every time a payload of data has been written to the device. Use `bytesToWrite` to determine the current amount of data waiting to be written.

Certain subclasses of `QIODevice`, such as `QTcpSocket` and `QProcess`, are asynchronous. This means that I/O functions such as `write` or `read` always return immediately, while communication with the device itself may happen when control goes back to the event loop. `QIODevice` provides functions that allow you to force these operations to be performed immediately, while blocking the calling thread and without entering the event loop. This allows `QIODevice` subclasses to be used without an event loop, or in a separate thread:

- `waitForReadyRead` - This function suspends operation in the calling thread until new data is available for reading.
- `waitForBytesWritten` - This function suspends operation in the calling thread until one payload of data has been written to the device.
- waitFor....() - Subclasses of `QIODevice` implement blocking functions for device-specific operations. For example, `QProcess` has a function called waitForStarted() which suspends operation in the calling thread until the process has started.

Calling these functions from the main, GUI thread, may cause your user interface to freeze. Example:

        QProcess gzip;
        gzip.start("gzip", QStringList() << "-c");
        if (!gzip.waitForStarted())
            return false;

        gzip.write("uncompressed data");

        QByteArray compressed;
        while (gzip.waitForReadyRead())
            compressed += gzip.readAll();

By subclassing `QIODevice`, you can provide the same interface to your own I/O devices. Subclasses of `QIODevice` are only required to implement the protected `readData` and `writeData` functions. `QIODevice` uses these functions to implement all its convenience functions, such as getChar(), `readLine` and `write`. `QIODevice` also handles access control for you, so you can safely assume that the device is opened in write mode if `writeData` is called.

Some subclasses, such as `QFile` and `QTcpSocket`, are implemented using a memory buffer for intermediate storing of data. This reduces the number of required device accessing calls, which are often very slow. Buffering makes functions like getChar() and putChar() fast, as they can operate on the memory buffer instead of directly on the device itself. Certain I/O operations, however, don't work well with a buffer. For example, if several users open the same device and read it character by character, they may end up reading the same data when they meant to read a separate chunk each. For this reason, `QIODevice` allows you to bypass any buffering by passing the Unbuffered flag to `open`. When subclassing `QIODevice`, remember to bypass any buffer you may use when the device is open in Unbuffered mode.

See also `QBuffer`, `QFile`, and `QTcpSocket`.