En esta página

QIODevice Class

La clase `QIODevice` es la clase de interfaz base de todos los dispositivos de E/S en Qt. Más información...

Encabezado: #include <QIODevice>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredado de:QObject y QIODeviceBase
Heredado por:

QAbstractSocket, QBluetoothSocket, QBuffer, QCoapReply, QFileDevice, QLocalSocket, QNetworkReply, QProcess y QSerialPort

Nota: Todas las funciones de esta clase son reentrantes.

Funciones públicas

QIODevice()
QIODevice(QObject *parent)
virtual ~QIODevice()
virtual bool atEnd() const
virtual qint64 bytesAvailable() const
virtual qint64 bytesToWrite() const
virtual bool canReadLine() const
virtual void close()
void commitTransaction()
int currentReadChannel() const
int currentWriteChannel() const
QString errorString() const
bool getChar(char *c)
bool isOpen() const
bool isReadable() const
virtual bool isSequential() const
bool isTextModeEnabled() const
bool isTransactionStarted() const
bool isWritable() const
virtual bool open(QIODeviceBase::OpenMode mode)
QIODeviceBase::OpenMode openMode() const
qint64 peek(char *data, qint64 maxSize)
QByteArray peek(qint64 maxSize)
virtual qint64 pos() const
bool putChar(char c)
qint64 read(char *data, qint64 maxSize)
QByteArray read(qint64 maxSize)
QByteArray readAll()
int readChannelCount() const
qint64 readLine(char *data, qint64 maxSize)
QByteArray readLine(qint64 maxSize = 0)
(since 6.9) QByteArrayView readLineInto(QSpan<char> buffer)
(since 6.9) QByteArrayView readLineInto(QSpan<std::byte> buffer)
(since 6.9) QByteArrayView readLineInto(QSpan<uchar> buffer)
(since 6.9) bool readLineInto(QByteArray *line, qint64 maxSize = 0)
virtual bool reset()
void rollbackTransaction()
virtual bool seek(qint64 pos)
void setCurrentReadChannel(int channel)
void setCurrentWriteChannel(int channel)
void setTextModeEnabled(bool enabled)
virtual qint64 size() const
qint64 skip(qint64 maxSize)
void startTransaction()
void ungetChar(char c)
virtual bool waitForBytesWritten(int msecs)
virtual bool waitForReadyRead(int msecs)
qint64 write(const char *data, qint64 maxSize)
qint64 write(const QByteArray &data)
qint64 write(const char *data)
int writeChannelCount() const

Señales

void aboutToClose()
void bytesWritten(qint64 bytes)
void channelBytesWritten(int channel, qint64 bytes)
void channelReadyRead(int channel)
void readChannelFinished()
void readyRead()

Funciones protegidas

virtual qint64 readData(char *data, qint64 maxSize) = 0
virtual qint64 readLineData(char *data, qint64 maxSize)
void setErrorString(const QString &str)
void setOpenMode(QIODeviceBase::OpenMode openMode)
(since 6.0) virtual qint64 skipData(qint64 maxSize)
virtual qint64 writeData(const char *data, qint64 maxSize) = 0

Descripción detallada

QIODevice proporciona tanto una implementación común como una interfaz abstracta para dispositivos que admiten la lectura y escritura de bloques de datos, como QFile, QBuffer y QTcpSocket. QIODevice es abstracta y no se puede instanciar, pero es habitual utilizar la interfaz que define para proporcionar funciones de E/S independientes del dispositivo. Por ejemplo, las clases Qt XML operan sobre un puntero a QIODevice, lo que permite utilizarlas con diversos dispositivos (como archivos y búferes).

Antes de acceder al dispositivo, se debe llamar a ` open()` para establecer el modo de apertura correcto (como `ReadOnly` o `ReadWrite`). A continuación, se puede escribir en el dispositivo con ` write()` o ` putChar()`, y leer llamando a ` read()`, ` readLine()` o ` readAll()`. Llame a ` close()` cuando haya terminado de utilizar el dispositivo.

QIODevice distingue entre dos tipos de dispositivos: dispositivos de acceso aleatorio y dispositivos secuenciales.

  • Los dispositivos de acceso aleatorio permiten desplazarse a posiciones arbitrarias mediante seek(). La posición actual en el archivo se puede consultar llamando a pos(). QFile y QBuffer son ejemplos de dispositivos de acceso aleatorio.
  • Los dispositivos secuenciales no admiten el desplazamiento a posiciones arbitrarias. Los datos deben leerse de una sola vez. Las funciones pos() y size() no funcionan con dispositivos secuenciales. QTcpSocket y QProcess son ejemplos de dispositivos secuenciales.

Se puede utilizar isSequential() para determinar el tipo de dispositivo.

QIODevice emite readyRead() cuando hay nuevos datos disponibles para su lectura; por ejemplo, si han llegado nuevos datos a la red o si se han añadido datos adicionales a un archivo del que se está leyendo. Se puede llamar a ` bytesAvailable()` para determinar el número de bytes disponibles actualmente para la lectura. Es habitual utilizar ` bytesAvailable()` junto con la señal ` readyRead()` al programar con dispositivos asíncronos como ` QTcpSocket`, en los que pueden llegar fragmentos de datos en momentos arbitrarios. QIODevice emite la señal bytesWritten() cada vez que se ha escrito una carga útil de datos en el dispositivo. Utiliza bytesToWrite() para determinar la cantidad actual de datos que están a la espera de ser escritos.

Ciertas subclases de QIODevice, como QTcpSocket y QProcess, son asíncronas. Esto significa que las funciones de E/S, como write() o read(), siempre devuelven un resultado de forma inmediata, mientras que la comunicación con el propio dispositivo puede tener lugar cuando el control vuelve al bucle de eventos. QIODevice proporciona funciones que permiten forzar la ejecución inmediata de estas operaciones, bloqueando al mismo tiempo el hilo de llamada y sin entrar en el bucle de eventos. Esto permite utilizar las subclases de QIODevice sin un bucle de eventos o en un hilo independiente:

  • waitForReadyRead() - Esta función suspende la operación en el hilo de llamada hasta que haya nuevos datos disponibles para su lectura.
  • waitForBytesWritten() - Esta función suspende el funcionamiento del hilo de llamada hasta que se haya escrito una carga útil de datos en el dispositivo.
  • waitFor....() - Las subclases de QIODevice implementan funciones de bloqueo para operaciones específicas del dispositivo. Por ejemplo, QProcess tiene una función llamada waitForStarted() que suspende la operación en el hilo de llamada hasta que se haya iniciado el proceso.

Llamar a estas funciones desde el hilo principal de la interfaz gráfica de usuario (GUI) puede provocar que la interfaz de usuario se cuelgue. Ejemplo:

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

gzip.write("uncompressed data");

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

Al crear una subclase de QIODevice, puede proporcionar la misma interfaz a sus propios dispositivos de E/S. Las subclases de QIODevice solo deben implementar las funciones protegidas readData() y writeData(). QIODevice utiliza estas funciones para implementar todas sus funciones de conveniencia, como getChar(), readLine() y write(). QIODevice también se encarga del control de acceso por ti, por lo que puedes dar por hecho que el dispositivo se abre en modo de escritura si se llama a writeData().

Algunas subclases, como QFile y QTcpSocket, se implementan utilizando un búfer de memoria para el almacenamiento intermedio de datos. Esto reduce el número de llamadas necesarias para acceder al dispositivo, que a menudo son muy lentas. El uso de búferes agiliza funciones como getChar() y putChar(), ya que pueden operar sobre el búfer de memoria en lugar de hacerlo directamente sobre el propio dispositivo. Sin embargo, ciertas operaciones de E/S no funcionan bien con un búfer. Por ejemplo, si varios usuarios abren el mismo dispositivo y lo leen carácter por carácter, pueden acabar leyendo los mismos datos cuando su intención era leer un fragmento distinto cada uno. Por este motivo, QIODevice permite omitir cualquier almacenamiento en búfer pasando el indicador Unbuffered a open(). Al crear subclases de QIODevice, recuerda omitir cualquier búfer que puedas utilizar cuando el dispositivo esté abierto en modo Unbuffered.

Por lo general, el flujo de datos entrante procedente de un dispositivo asíncrono está fragmentado, y los fragmentos de datos pueden llegar en momentos arbitrarios. Para gestionar lecturas incompletas de estructuras de datos, utiliza el mecanismo de transacciones implementado por QIODevice. Consulta ` startTransaction()` y las funciones relacionadas para obtener más detalles.

Algunos dispositivos secuenciales admiten la comunicación a través de múltiples canales. Estos canales representan flujos de datos independientes que tienen la propiedad de entregarse de forma secuencial e independiente. Una vez abierto el dispositivo, puede determinar el número de canales llamando a las funciones ` readChannelCount()` y ` writeChannelCount()`. Para cambiar de canal, llame a ` setCurrentReadChannel()` y ` setCurrentWriteChannel()`, respectivamente. QIODevice también proporciona señales adicionales para gestionar la comunicación asíncrona por cada canal.

Consideraciones de seguridad

QIODevice dispone de un conjunto de métodos que permiten la lectura sin límite. En el momento de redactar este documento, estos métodos incluyen readAll(), readLine(0) y readLineInto(buffer, 0); los dos últimos tienen un significado especial para el valor 0, al que tratan como ilimitado.

En el caso de dispositivos secuenciales, o de aquellos que devuelven un valor de size() igual a cero (p. ej., /dev/urandom), estos métodos leerán los datos en bloques y los añadirán a un búfer interno o proporcionado por el usuario, siempre que haya nuevos datos disponibles. Esto puede dar lugar a situaciones de falta de memoria. Por lo tanto, se recomienda evitar estos métodos con entradas no fiables o de tamaño desconocido, y proporcionar siempre límites máximos razonables para la lectura.

Véase también QBuffer, QFile y QTcpSocket.

Documentación de las funciones miembro

QIODevice::QIODevice()

Crea un objeto QIODevice.

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

Crea un objeto `QIODevice` con el ` parent` indicado.

[virtual noexcept] QIODevice::~QIODevice()

El destructor es virtual, y ` QIODevice ` es una clase base abstracta. Este destructor no llama a ` close()`, pero es posible que el destructor de la subclase sí lo haga. En caso de duda, llama a ` close()` antes de destruir ` QIODevice`.

[signal] void QIODevice::aboutToClose()

Esta señal se emite cuando el dispositivo está a punto de cerrarse. Conecta esta señal si tienes operaciones que deban realizarse antes de que el dispositivo se cierre (por ejemplo, si tienes datos en un búfer independiente que deban escribirse en el dispositivo).

[virtual] bool QIODevice::atEnd() const

Devuelve « true » si la posición actual de lectura y escritura se encuentra al final del dispositivo (es decir, no hay más datos disponibles para leer en el dispositivo); en caso contrario, devuelve « false ».

En algunos dispositivos, atEnd() puede devolver «true» aunque queden más datos por leer. Este caso especial solo se aplica a los dispositivos que generan datos como respuesta directa a la llamada a read() (por ejemplo, los archivos /dev o /proc en Unix y macOS, o la entrada de consola / stdin en todas las plataformas).

Véase también bytesAvailable(), read() y isSequential().

[virtual] qint64 QIODevice::bytesAvailable() const

Devuelve el número de bytes disponibles para la lectura. Esta función se utiliza habitualmente con dispositivos secuenciales para determinar el número de bytes que hay que asignar en un búfer antes de la lectura.

Las subclases que reimplementen esta función deben llamar a la implementación base para incluir el tamaño del búfer de QIODevice. Ejemplo:

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

Véase también bytesToWrite(), readyRead() y isSequential().

[virtual] qint64 QIODevice::bytesToWrite() const

En el caso de los dispositivos con búfer, esta función devuelve el número de bytes que están a la espera de ser escritos. En el caso de los dispositivos sin búfer, esta función devuelve 0.

Las subclases que reimplementen esta función deben llamar a la implementación base para incluir el tamaño del búfer de QIODevice.

Véanse también bytesAvailable(), bytesWritten() y isSequential().

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

Esta señal se emite cada vez que se ha escrito una carga útil de datos en el canal de escritura actual del dispositivo. El argumento « bytes » se establece en el número de bytes que se han escrito en esta carga útil.

bytesWritten() no se emite de forma recursiva; si vuelves a entrar en el bucle de eventos o llamas a waitForBytesWritten() dentro de una ranura conectada a la señal bytesWritten(), la señal no se volverá a emitir (aunque waitForBytesWritten() pueda seguir devolviendo true).

Véase también ` readyRead()`.

[virtual] bool QIODevice::canReadLine() const

Devuelve ` true ` si se puede leer una línea completa de datos del dispositivo; en caso contrario, devuelve ` false`.

Tenga en cuenta que los dispositivos sin búfer, que no tienen forma de determinar qué se puede leer, siempre devuelven «false».

Esta función suele invocarse junto con la señal ` readyRead()`.

Las subclases que reimplementen esta función deben llamar a la implementación base para incluir el contenido del búfer de ` QIODevice`. Ejemplo:

bool CustomDevice::canReadLine() const
{
    return buffer.contains('\n') || QIODevice::canReadLine();
}

Véase también ` readyRead()` y ` readLine()`.

[signal] void QIODevice::channelBytesWritten(int channel, qint64 bytes)

Esta señal se emite cada vez que se ha escrito una carga útil de datos en el dispositivo. El argumento ` bytes ` se establece en el número de bytes que se han escrito en esta carga útil, mientras que ` channel ` es el canal en el que se han escrito. A diferencia de ` bytesWritten()`, se emite independientemente de ` current write channel`.

channelBytesWritten() puede emitirse de forma recursiva, incluso para el mismo canal.

Véanse también « bytesWritten()» y « channelReadyRead()».

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

Esta señal se emite cuando hay nuevos datos disponibles para su lectura desde el dispositivo. El argumento ` channel ` se establece en el índice del canal de lectura al que han llegado los datos. A diferencia de ` readyRead()`, se emite independientemente del valor de ` current read channel`.

channelReadyRead() puede emitirse de forma recursiva, incluso para el mismo canal.

Véanse también readyRead() y channelBytesWritten().

[virtual] void QIODevice::close()

Primero emite un « aboutToClose » (), después cierra el dispositivo y establece su OpenMode en «NotOpen». La cadena de error también se restablece.

Véase también « setOpenMode()» y « QIODeviceBase::OpenMode ».

void QIODevice::commitTransaction()

Finaliza una transacción de lectura.

En el caso de los dispositivos secuenciales, se descartarán todos los datos registrados en el búfer interno durante la transacción.

Véase también startTransaction() y rollbackTransaction().

int QIODevice::currentReadChannel() const

Devuelve el índice del canal de lectura actual.

Véase también setCurrentReadChannel(), readChannelCount() y QProcess.

int QIODevice::currentWriteChannel() const

Devuelve el índice del canal de escritura actual.

Véanse también setCurrentWriteChannel() y writeChannelCount().

QString QIODevice::errorString() const

Devuelve una descripción comprensible para el usuario del último error del dispositivo que se ha producido.

Véase también setErrorString().

bool QIODevice::getChar(char *c)

Lee un carácter del dispositivo y lo almacena en ` c`. Si ` c ` es ` nullptr`, el carácter se descarta. Devuelve ` true ` si la operación se realiza correctamente; en caso contrario, devuelve ` false`.

Véase también read(), putChar() y ungetChar().

bool QIODevice::isOpen() const

Devuelve « true » si el dispositivo está abierto; en caso contrario, devuelve « false ». Un dispositivo está abierto si se puede leer y/o escribir en él. Por defecto, esta función devuelve « false » si « openMode()» devuelve « NotOpen ».

Véase también openMode() y QIODeviceBase::OpenMode.

bool QIODevice::isReadable() const

Devuelve « true » si se pueden leer datos del dispositivo; en caso contrario, devuelve «false». Utiliza « bytesAvailable()» para determinar cuántos bytes se pueden leer.

Esta es una función de conveniencia que comprueba si el OpenMode del dispositivo contiene el indicador ReadOnly.

Véase también openMode() y OpenMode.

[virtual] bool QIODevice::isSequential() const

Devuelve « true » si este dispositivo es secuencial; en caso contrario, devuelve «false».

Los dispositivos secuenciales, a diferencia de los de acceso aleatorio, carecen de los conceptos de inicio, fin, tamaño o posición actual, y no admiten la búsqueda. Solo se puede leer del dispositivo cuando este indica que hay datos disponibles. El ejemplo más común de dispositivo secuencial es un socket de red. En Unix, los archivos especiales como /dev/zero y las tuberías FIFO son secuenciales.

Los archivos normales, por su parte, sí admiten el acceso aleatorio. Tienen tanto un tamaño como una posición actual, y también admiten el desplazamiento hacia atrás y hacia adelante en el flujo de datos. Los archivos normales son no secuenciales.

Véase también bytesAvailable().

bool QIODevice::isTextModeEnabled() const

Devuelve « true » si está activada la bandera « Text »; en caso contrario, devuelve « false ».

Véase también setTextModeEnabled().

bool QIODevice::isTransactionStarted() const

Devuelve « true » si hay una transacción en curso en el dispositivo; en caso contrario, devuelve « false ».

Véase también startTransaction().

bool QIODevice::isWritable() const

Devuelve « true » si se pueden escribir datos en el dispositivo; en caso contrario, devuelve «false».

Se trata de una función de conveniencia que comprueba si el OpenMode del dispositivo contiene el indicador WriteOnly.

Véase también openMode() y OpenMode.

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

Abre el dispositivo y establece su OpenMode en « mode ». Devuelve « true » si se realiza correctamente; en caso contrario, devuelve « false ». Esta función debe llamarse desde cualquier reimplementación de open() u otras funciones que abran el dispositivo.

Véase también openMode() y QIODeviceBase::OpenMode.

QIODeviceBase::OpenMode QIODevice::openMode() const

Devuelve el modo en el que se ha abierto el dispositivo; es decir, «ReadOnly» o «WriteOnly».

Véase también setOpenMode() y OpenMode.

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

Lee como máximo maxSize bytes del dispositivo y los almacena en data, sin efectos secundarios (es decir, si se llama a read() después de peek(), se obtendrán los mismos datos). Devuelve el número de bytes leídos. Si se produce un error, como al intentar leer un dispositivo abierto en modo WriteOnly, esta función devuelve -1.

Se devuelve 0 cuando ya no hay más datos disponibles para leer.

Ejemplo:

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

Véase también read().

QByteArray QIODevice::peek(qint64 maxSize)

Obtiene un máximo de maxSize bytes del dispositivo y devuelve los datos obtenidos como un objeto de tipo QByteArray.

Ejemplo:

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

Esta función no tiene forma de notificar errores; devolver un objeto ` QByteArray ` vacío puede significar que no había datos disponibles en ese momento para su lectura, o que se ha producido un error.

Esta es una función sobrecargada.

Véase también read().

[virtual] qint64 QIODevice::pos() const

En el caso de los dispositivos de acceso aleatorio, esta función devuelve la posición en la que se escriben o se leen los datos. En el caso de los dispositivos secuenciales o cerrados, en los que no existe el concepto de «posición actual», se devuelve 0.

QIODevice gestiona internamente la posición actual de lectura/escritura del dispositivo, por lo que no es necesario reimplementar esta función. Al crear una subclase de QIODevice, utiliza QIODevice::seek() para notificar a QIODevice los cambios en la posición del dispositivo.

Véanse también isSequential() y seek().

bool QIODevice::putChar(char c)

Escribe el carácter c en el dispositivo. Devuelve true si la operación se realiza correctamente; en caso contrario, devuelve false.

Véase también write(), getChar() y ungetChar().

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

Lee como máximo maxSize bytes del dispositivo en data y devuelve el número de bytes leídos. Si se produce un error, como por ejemplo al intentar leer de un dispositivo abierto en modo «WriteOnly», esta función devuelve -1.

Se devuelve 0 cuando no hay más datos disponibles para leer. Sin embargo, leer más allá del final del flujo se considera un error, por lo que esta función devuelve -1 en esos casos (es decir, al leer en un socket cerrado o después de que un proceso haya finalizado).

Véase también readData(), readLine() y write().

QByteArray QIODevice::read(qint64 maxSize)

Lee como máximo maxSize bytes del dispositivo y devuelve los datos leídos como un objeto ` QByteArray`.

Esta función no tiene forma de informar de errores; devolver un ` QByteArray ` vacío puede significar que no había datos disponibles para su lectura en ese momento o que se ha producido un error.

Se trata de una función sobrecargada.

QByteArray QIODevice::readAll()

Lee todos los datos restantes del dispositivo y los devuelve como una matriz de bytes.

Esta función no dispone de ningún mecanismo para notificar errores; si devuelve un ` QByteArray ` vacío, puede significar que no había datos disponibles para su lectura en ese momento o que se ha producido un error. Esta función tampoco dispone de ningún mecanismo para indicar que podría haber habido más datos disponibles que no se hayan podido leer.

int QIODevice::readChannelCount() const

Devuelve el número de canales de lectura disponibles si el dispositivo está abierto; en caso contrario, devuelve 0.

Véase también writeChannelCount() y QProcess.

[signal] void QIODevice::readChannelFinished()

Esta señal se emite cuando se cierra el flujo de entrada (lectura) en este dispositivo. Se emite tan pronto como se detecta el cierre, lo que significa que aún podría haber datos disponibles para su lectura mediante read().

Véanse también atEnd() y read().

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

Lee hasta maxSize bytes del dispositivo en data y devuelve el número de bytes leídos o -1 si se ha producido un error.

Si no hay bytes que leer y nunca va a haber más bytes disponibles (por ejemplo, si el socket está cerrado, la tubería está cerrada o el subproceso ha finalizado), esta función devuelve -1.

Esta función es llamada por ` QIODevice`. Reimplementa esta función al crear una subclase de ` QIODevice`.

Al reimplementar esta función, es importante que lea todos los datos necesarios antes de devolver un resultado. Esto es necesario para que QDataStream pueda operar sobre la clase. QDataStream asume que se ha leído toda la información solicitada y, por lo tanto, no vuelve a intentar la lectura si se ha producido un problema.

Esta función puede invocarse con un valor de maxSize igual a 0, lo que permite realizar operaciones posteriores a la lectura.

Véanse también read(), readLine() y writeData().

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

Esta función lee una línea de caracteres ASCII del dispositivo, hasta un máximo de maxSize - 1 bytes, almacena los caracteres en data y devuelve el número de bytes leídos. Si no se ha podido leer una línea pero no se ha producido ningún error, esta función devuelve 0. Si se produce un error, esta función devuelve la longitud de lo que se ha podido leer, o -1 si no se ha leído nada.

Siempre se añade un byte de terminación «\0 » a data, por lo que maxSize debe ser mayor que 1.

Los datos se leen hasta que se cumpla una de las siguientes condiciones:

  • Se lee el primer carácter «\n ».
  • maxSize - Se leen 1 byte.
  • Se detecta el final de los datos del dispositivo.

Por ejemplo, el siguiente código lee una línea de caracteres de un archivo:

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

El carácter de salto de línea («\n ») se incluye en el búfer. Si no se encuentra un salto de línea antes de que se lean maxSize - 1 bytes, no se insertará ningún salto de línea en el búfer.

Nota: La conversiónde saltos de línea (por ejemplo, convertir « \r » en « \n ») solo se realiza cuando el dispositivo se abre para lectura con el indicador QIODevice::Text.

Ten en cuenta que, en dispositivos secuenciales, es posible que los datos no estén disponibles de inmediato, lo que puede dar lugar a que se devuelva una línea parcial. Al llamar a la función canReadLine() antes de leer, puedes comprobar si se puede leer una línea completa (incluido el carácter de salto de línea).

Esta función llama a ` readLineData()`, que se implementa mediante llamadas repetidas a ` getChar()`. Se puede proporcionar una implementación más eficiente reimplementando ` readLineData()` en una subclase propia.

Véanse también getChar(), read(), canReadLine() y write().

QByteArray QIODevice::readLine(qint64 maxSize = 0)

Lee una línea del dispositivo, con un máximo de maxSize caracteres, y devuelve el resultado como una matriz de bytes.

Si maxSize es 0 o no se especifica, la línea puede tener cualquier longitud, lo que permite una lectura ilimitada.

La línea resultante puede contener caracteres de fin de línea al final («\n » o «\r\n »), por lo que puede ser necesario llamar a QByteArray::trimmed().

Esta función no dispone de forma de notificar errores; devolver un QByteArray vacío puede significar que no había datos disponibles para la lectura en ese momento o que se produjo un error.

Se trata de una función sobrecargada.

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

Lee hasta maxSize caracteres en data y devuelve el número de caracteres leídos.

Esta función es llamada por readLine() y proporciona su implementación básica, utilizando getChar(). Los dispositivos con búfer pueden mejorar el rendimiento de readLine() reimplementando esta función.

readLine() añade un byte «\0 » a data; readLineData() no necesita hacerlo.

Si reimplementas esta función, asegúrate de devolver el valor correcto: debe devolver el número de bytes leídos en esta línea, incluido el salto de línea final, o 0 si no hay ninguna línea que leer en este punto. Si se produce un error, debe devolver -1 si y solo si no se ha leído ningún byte. Leer más allá del EOF se considera un error.

[since 6.9] QByteArrayView QIODevice::readLineInto(QSpan<char> buffer)

[since 6.9] QByteArrayView QIODevice::readLineInto(QSpan<std::byte> buffer)

[since 6.9] QByteArrayView QIODevice::readLineInto(QSpan<uchar> buffer)

Lee una línea de este dispositivo en ` buffer` y devuelve el subconjunto de ` buffer ` que contiene los datos leídos.

Si el tamaño de buffer es menor que la longitud de la línea, solo se leen y devuelven los caracteres que caben en buffer. En este caso, al volver a llamar a ` readLineInto()` se recuperará el resto de la línea. Para determinar si se ha leído la línea completa, comprueba primero si el dispositivo está en ` atEnd()`, por si la última línea no terminara con un salto de línea. Si no es ` atEnd()`, verifica si la vista devuelta termina con «\n ». De lo contrario, se requiere otra llamada a ` readLineInto()`.

La línea resultante puede contener caracteres de fin de línea al final («\n » o «\r\n »), por lo que puede ser necesario llamar a QByteArrayView::trimmed().

En caso de que se produzca un error, esta función devuelve un « QByteArrayView » nulo. De lo contrario, es un sub-span de « buffer ». Si no hay datos disponibles para su lectura o el dispositivo está en « atEnd()», esta función devuelve un « QByteArrayView » vacío.

Ten en cuenta que el valor devuelto no termina en `null`. Si deseas que termine en `null`, puedes pasar ` buffer.chopped(1) ` y, a continuación, insertar «`\0`» en ` buffer[result.size()]`.

Estas funciones se introdujeron en Qt 6.9.

Véase también readLine().

[since 6.9] bool QIODevice::readLineInto(QByteArray *line, qint64 maxSize = 0)

Lee una línea del dispositivo, pero no más de maxSize caracteres, y la almacena como una matriz de bytes en line.

Nota: Lee una línea de este dispositivo incluso si line es nullptr.

Si maxSize es 0 o no se especifica, la línea puede tener cualquier longitud, lo que permite una lectura ilimitada.

La línea resultante puede contener caracteres de fin de línea al final («\n » o «\r\n »), por lo que puede ser necesario llamar a QByteArray::trimmed().

Si no hay datos disponibles para su lectura en ese momento, o en caso de que se produzca un error, esta función devuelve « false » y establece « line » en « empty ». En caso contrario, devuelve « true ».

Tenga en cuenta que el contenido de ` line ` antes de la llamada se descarta en cualquier caso, pero su ` capacity()` nunca se reduce.

Esta función se introdujo en Qt 6.9.

Véase también readAll(), readLine() y QTextStream::readLineInto().

[signal] void QIODevice::readyRead()

Esta señal se emite una vez cada vez que hay nuevos datos disponibles para su lectura desde el canal de lectura actual del dispositivo. Solo se volverá a emitir cuando haya nuevos datos disponibles, por ejemplo, cuando haya llegado una nueva carga útil de datos de red a tu socket de red, o cuando se haya añadido un nuevo bloque de datos a tu dispositivo.

readyRead() no se emite de forma recursiva; si vuelves a entrar en el bucle de eventos o llamas a waitForReadyRead() dentro de una ranura conectada a la señal readyRead(), la señal no se volverá a emitir (aunque waitForReadyRead() pueda seguir devolviendo true).

Nota para los desarrolladores que implementen clases derivadas de ` QIODevice`: siempre debes emitir `readyRead()` cuando hayan llegado nuevos datos (no la emitas solo porque aún queden datos por leer en tus búferes). No emitas `readyRead()` en otras circunstancias.

Véase también bytesWritten().

[virtual] bool QIODevice::reset()

Busca el inicio de la entrada para dispositivos de acceso aleatorio. Devuelve «true» si la operación se realiza correctamente; en caso contrario, devuelve « false » (por ejemplo, si el dispositivo no está abierto).

Ten en cuenta que, al utilizar un ` QTextStream ` en un ` QFile`, llamar a `reset()` en el ` QFile ` no dará el resultado esperado, ya que ` QTextStream ` almacena el archivo en un búfer. Utiliza en su lugar la función ` QTextStream::seek()`.

Véase también seek().

void QIODevice::rollbackTransaction()

Revierte una transacción de lectura.

Restaura el flujo de entrada al punto de la llamada a startTransaction(). Esta función se utiliza habitualmente para revertir la transacción cuando se detecta una lectura incompleta antes de confirmar la transacción.

Véanse también ` startTransaction()` y ` commitTransaction()`.

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

En el caso de los dispositivos de acceso aleatorio, esta función establece la posición actual en ` pos`, devolviendo «true» si se realiza correctamente o «false» si se produce un error. En el caso de los dispositivos secuenciales, el comportamiento predeterminado es generar una advertencia y devolver «false».

Al crear una subclase de ` QIODevice`, debes llamar a `QIODevice::seek()` al inicio de tu función para garantizar la integridad con el búfer integrado de ` QIODevice`.

Véase también ` pos()` y ` isSequential()`.

void QIODevice::setCurrentReadChannel(int channel)

Establece el canal de lectura actual de la función « QIODevice » en el valor indicado « channel ». El canal de entrada actual es el que utilizan las funciones « read()», « readAll()», « readLine()» y « getChar()». También determina qué canal activa la función « QIODevice » para que emita « readyRead()».

Véase también currentReadChannel(), readChannelCount() y QProcess.

void QIODevice::setCurrentWriteChannel(int channel)

Establece el canal de escritura actual del « QIODevice » en el « channel » especificado. El canal de salida actual es el que utilizan las funciones « write()» y « putChar()». También determina qué canal activa « QIODevice » para que emita « bytesWritten()».

Véanse también currentWriteChannel() y writeChannelCount().

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

Establece la descripción legible para el usuario del último error de dispositivo que se ha producido en str.

Véase también errorString().

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

Establece el modo de apertura (OpenMode) del dispositivo en « openMode ». Llama a esta función para establecer el modo de apertura si los indicadores cambian después de que se haya abierto el dispositivo.

Véase también ` openMode()` y ` OpenMode`.

void QIODevice::setTextModeEnabled(bool enabled)

Si ` enabled ` es verdadero, esta función establece el indicador ` Text ` en el dispositivo; en caso contrario, se elimina el indicador ` Text `. Esta característica resulta útil para las clases que proporcionan un manejo personalizado del fin de línea en un ` QIODevice`.

El dispositivo de E/S debe estar abierto antes de llamar a esta función.

Véanse también isTextModeEnabled(), open() y setOpenMode().

[virtual] qint64 QIODevice::size() const

En el caso de los dispositivos abiertos de acceso aleatorio, esta función devuelve el tamaño del dispositivo. En el caso de los dispositivos abiertos secuenciales, se devuelve bytesAvailable().

Si el dispositivo está cerrado, el tamaño devuelto no reflejará el tamaño real del dispositivo.

Véanse también isSequential() y pos().

qint64 QIODevice::skip(qint64 maxSize)

Omite hasta maxSize bytes del dispositivo. Devuelve el número de bytes realmente omitidos, o -1 en caso de error.

Esta función no espera y solo descarta los datos que ya están disponibles para su lectura.

Si el dispositivo está abierto en modo texto, los caracteres de fin de línea se convierten en los símbolos «\n » y cuentan como un solo byte, de forma idéntica al comportamiento de las funciones read() y peek().

Esta función funciona para todos los dispositivos, incluidos los secuenciales que no admiten seek(). Está optimizada para omitir datos no deseados tras una llamada a peek().

En el caso de los dispositivos de acceso aleatorio, se puede utilizar skip() para avanzar desde la posición actual. No se admiten valores negativos de maxSize.

Véanse también skipData(), peek(), seek() y read().

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

Omite hasta maxSize bytes del dispositivo. Devuelve el número de bytes realmente omitidos o -1 en caso de error.

Esta función es llamada por ` QIODevice`. Considera la posibilidad de reimplementarla al crear una subclase de ` QIODevice`.

La implementación base descarta los datos leyéndolos en un búfer ficticio. Esto es lento, pero funciona para todo tipo de dispositivos. Las subclases pueden reimplementar esta función para mejorar este comportamiento.

Esta función se introdujo en Qt 6.0.

Véase también skip(), peek(), seek() y read().

void QIODevice::startTransaction()

Inicia una nueva transacción de lectura en el dispositivo.

Define un punto de restauración dentro de la secuencia de operaciones de lectura. En el caso de los dispositivos secuenciales, los datos leídos se duplicarán internamente para permitir la recuperación en caso de lecturas incompletas. En el caso de los dispositivos de acceso aleatorio, esta función guarda la posición actual. Llama a commitTransaction() o a rollbackTransaction() para finalizar la transacción.

Nota: No se admiteel anidamiento de transacciones.

Véase también commitTransaction() y rollbackTransaction().

void QIODevice::ungetChar(char c)

Devuelve el carácter c al dispositivo y decrementa la posición actual, salvo que esta sea 0. Esta función suele invocarse para «deshacer» una operación getChar(), por ejemplo, al escribir un analizador sintáctico de retroceso.

Si el carácter c no se ha leído previamente del dispositivo, el comportamiento es indefinido.

Nota: Esta función no está disponible mientras se está llevando a cabo una transacción.

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

En el caso de los dispositivos con búfer, esta función espera hasta que se haya escrito en el dispositivo una carga útil de datos almacenados en el búfer y se haya emitido la señal bytesWritten(), o hasta que hayan transcurrido msecs milisegundos. Si msecs es -1, esta función no agotará el tiempo de espera. En el caso de los dispositivos sin búfer, devuelve el resultado inmediatamente.

Devuelve « true » si se ha escrito una carga útil de datos en el dispositivo; en caso contrario, devuelve « false » (es decir, si la operación ha agotado el tiempo de espera o si se ha producido un error).

Esta función puede funcionar sin un bucle de eventos. Resulta útil al escribir aplicaciones sin interfaz gráfica de usuario y al realizar operaciones de E/S en un hilo sin interfaz gráfica de usuario.

Si se invoca desde una ranura conectada a la señal bytesWritten(), no se volverá a emitir bytesWritten().

Reimplementa esta función para proporcionar una API de bloqueo para un dispositivo personalizado. La implementación predeterminada no hace nada y devuelve ` false`.

Advertencia: Llamar a esta función desde el hilo principal (de la interfaz gráfica de usuario) podría provocar que la interfaz de usuario se cuelgue.

Véase también waitForReadyRead().

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

Queda bloqueada hasta que haya nuevos datos disponibles para su lectura y se haya emitido la señal readyRead(), o hasta que hayan transcurrido msecs milisegundos. Si msecs es -1, esta función no agotará el tiempo de espera.

Devuelve ` true ` si hay nuevos datos disponibles para su lectura; en caso contrario, devuelve `false` (si la operación ha superado el tiempo de espera o si se ha producido un error).

Esta función puede funcionar sin un bucle de eventos. Resulta útil al escribir aplicaciones sin interfaz gráfica de usuario y al realizar operaciones de E/S en un hilo sin interfaz gráfica de usuario.

Si se invoca desde un slot conectado a la señal readyRead(), readyRead() no se volverá a emitir.

Reimplementa esta función para proporcionar una API de bloqueo para un dispositivo personalizado. La implementación predeterminada no hace nada y devuelve ` false`.

Advertencia: Llamar a esta función desde el hilo principal (GUI) podría provocar que la interfaz de usuario se cuelgue.

Véase también waitForBytesWritten().

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

Escribe como máximo maxSize bytes de datos desde data al dispositivo. Devuelve el número de bytes que se han escrito realmente, o -1 si se ha producido un error.

Véase también read() y writeData().

qint64 QIODevice::write(const QByteArray &data)

Escribe el contenido de ` data ` en el dispositivo. Devuelve el número de bytes que se han escrito realmente, o -1 si se ha producido un error.

Esta es una función sobrecargada.

Véanse también read() y writeData().

qint64 QIODevice::write(const char *data)

Escribe datos de una cadena terminada en cero compuesta por caracteres de 8 bits en el dispositivo. Devuelve el número de bytes que se han escrito realmente, o -1 si se ha producido un error. Esto equivale a

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

Esta es una función sobrecargada.

Véase también read() y writeData().

int QIODevice::writeChannelCount() const

Devuelve el número de canales de escritura disponibles si el dispositivo está abierto; en caso contrario, devuelve 0.

Véase también readChannelCount().

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

Escribe hasta maxSize bytes desde data en el dispositivo. Devuelve el número de bytes escritos, o -1 si se ha producido un error.

Esta función es llamada por ` QIODevice`. Reimplementa esta función al crear una subclase de ` QIODevice`.

Al reimplementar esta función, es importante que escriba todos los datos disponibles antes de devolver un valor. Esto es necesario para que QDataStream pueda operar sobre la clase. QDataStream asume que toda la información se ha escrito y, por lo tanto, no vuelve a intentar la escritura si se ha producido un problema.

Véase también read() y write().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.