En esta página

QDataStream Class

La clase QDataStream permite la serialización de datos binarios en un « QIODevice ». Más información...

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

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum ByteOrder { BigEndian, LittleEndian }
enum FloatingPointPrecision { SinglePrecision, DoublePrecision }
enum Status { Ok, ReadPastEnd, ReadCorruptData, WriteFailed, SizeLimitExceeded }
enum Version { Qt_1_0, Qt_2_0, Qt_2_1, Qt_3_0, Qt_3_1, …, Qt_6_12 }

Funciones públicas

QDataStream()
QDataStream(QIODevice *d)
QDataStream(const QByteArray &a)
QDataStream(QByteArray *a, QIODeviceBase::OpenMode mode)
~QDataStream()
void abortTransaction()
bool atEnd() const
QDataStream::ByteOrder byteOrder() const
bool commitTransaction()
QIODevice *device() const
QDataStream::FloatingPointPrecision floatingPointPrecision() const
(since 6.7) QDataStream &readBytes(char *&s, qint64 &l)
qint64 readRawData(char *s, qint64 len)
void resetStatus()
void rollbackTransaction()
void setByteOrder(QDataStream::ByteOrder bo)
void setDevice(QIODevice *d)
void setFloatingPointPrecision(QDataStream::FloatingPointPrecision precision)
void setStatus(QDataStream::Status status)
void setVersion(int v)
qint64 skipRawData(qint64 len)
void startTransaction()
QDataStream::Status status() const
int version() const
QDataStream &writeBytes(const char *s, qint64 len)
qint64 writeRawData(const char *s, qint64 len)
(since 6.10) operator bool() const
QDataStream &operator<<(qint8 i)
QDataStream &operator<<(bool i)
(since 6.0) QDataStream &operator<<(char16_t c)
(since 6.0) QDataStream &operator<<(char32_t c)
QDataStream &operator<<(const char *s)
QDataStream &operator<<(double f)
QDataStream &operator<<(float f)
QDataStream &operator<<(qint16 i)
QDataStream &operator<<(qint32 i)
QDataStream &operator<<(qint64 i)
QDataStream &operator<<(quint16 i)
QDataStream &operator<<(quint32 i)
QDataStream &operator<<(quint64 i)
QDataStream &operator<<(quint8 i)
QDataStream &operator<<(std::nullptr_t ptr)
QDataStream &operator>>(bool &i)
QDataStream &operator>>(qint8 &i)
QDataStream &operator>>(char *&s)
(since 6.0) QDataStream &operator>>(char16_t &c)
(since 6.0) QDataStream &operator>>(char32_t &c)
QDataStream &operator>>(double &f)
QDataStream &operator>>(float &f)
QDataStream &operator>>(qint16 &i)
QDataStream &operator>>(qint32 &i)
QDataStream &operator>>(qint64 &i)
QDataStream &operator>>(quint16 &i)
QDataStream &operator>>(quint32 &i)
QDataStream &operator>>(quint64 &i)
QDataStream &operator>>(quint8 &i)
QDataStream &operator>>(std::nullptr_t &ptr)
(since 6.0) QDataStream &operator<<(QDataStream &out, const std::pair<T1, T2> &pair)
QDataStream &operator<<(QDataStream &ds, qfloat16 f)
QDataStream &operator>>(QDataStream &ds, qfloat16 &f)
(since 6.0) QDataStream &operator>>(QDataStream &in, std::pair<T1, T2> &pair)

Descripción detallada

Un flujo de datos es un flujo binario de información codificada que es 100 % independiente del sistema operativo, la CPU o el orden de los bytes del ordenador anfitrión. Por ejemplo, un flujo de datos escrito por un PC con Windows puede ser leído por un Sun SPARC que ejecute Solaris.

También puedes utilizar un flujo de datos para leer o escribir en raw unencoded binary data. Si deseas un flujo de entrada «de análisis sintáctico», consulta QTextStream.

La clase QDataStream implementa la serialización de los tipos de datos básicos de C++, como char, short, int, char *, etc. La serialización de datos más complejos se lleva a cabo dividiendo los datos en unidades primitivas.

Un flujo de datos colabora estrechamente con un QIODevice. Un QIODevice representa un medio de entrada/salida del que se pueden leer y al que se pueden escribir datos. La clase QFile es un ejemplo de dispositivo de E/S.

Ejemplo (escribir datos binarios en un flujo):

QFile file("file.dat");
file.open(QIODevice::WriteOnly);
QDataStream out(&file);   // we will serialize the data into the file
out << QString("the answer is");   // serialize a string
out << (qint32)42;        // serialize an integer

Ejemplo (lectura de datos binarios de un flujo):

QFile file("file.dat");
file.open(QIODevice::ReadOnly);
QDataStream in(&file);    // read the data serialized from the file
QString str;
qint32 a;
in >> str >> a;           // extract "the answer is" and 42

Cada elemento escrito en el flujo se guarda en un formato binario predefinido que varía en función del tipo del elemento. Los tipos de Qt compatibles incluyen QBrush, QColor, QDateTime, QFont, QPixmap, QString, QVariant y muchos otros. Para consultar la lista completa de todos los tipos de Qt compatibles con la transmisión de datos, véase «Serialización de tipos de datos de Qt».

En el caso de los enteros, lo mejor es realizar siempre un casting a un tipo entero de Qt para la escritura y volver a leerlos en el mismo tipo entero de Qt. Esto garantiza que se obtengan enteros del tamaño deseado y protege frente a las diferencias entre compiladores y plataformas.

Las enumeraciones se pueden serializar mediante QDataStream sin necesidad de definir manualmente operadores de transmisión. Las clases de enumeración se serializan utilizando el tamaño declarado.

El dispositivo de E/S inicial suele configurarse en el constructor, pero puede modificarse con ` setDevice()`. Si has llegado al final de los datos (o si no hay ningún dispositivo de E/S configurado), ` atEnd()` devolverá «true».

Serialización de contenedores y cadenas

El formato de serialización consiste primero en un especificador de longitud, seguido de l bytes de datos. El especificador de longitud es un quint32 si la versión es inferior a 6.7 o si el número de elementos es inferior a 0xfffffffe (2^32 - 2). En caso contrario, hay un valor de extensión 0xfffffffe seguido de un quint64 con el valor real. Además, en el caso de los contenedores que admiten isNull(), se codifica como un único quint32 con todos los bits a uno y sin datos.

Por poner un ejemplo, si el tamaño de la cadena cabe en 32 bits, una cadena « char * » se escribe como un entero de 32 bits igual a la longitud de la cadena, incluyendo el byte «\0 », seguido de todos los caracteres de la cadena, incluyendo el byte «\0 ». Si el tamaño de la cadena es mayor, se escribe el valor 0xffffffffe como marcador de un tamaño ampliado, seguido de 64 bits que indican el tamaño real. Al leer una cadena « char * », primero se leen 4 bytes. Si el valor no es igual a 0xffffffffe (el marcador de tamaño ampliado), estos 4 bytes se tratan como el tamaño de 32 bits de la cadena. De lo contrario, se leen los siguientes 8 bytes y se tratan como el tamaño de 64 bits de la cadena. A continuación, se leen todos los caracteres de la cadena « char * », incluido el terminador «'\0'».

Control de versiones

El formato binario de QDataStream ha evolucionado desde Qt 1.0, y es probable que siga evolucionando para reflejar los cambios introducidos en Qt. Al leer o escribir tipos complejos, es muy importante asegurarse de que se utilice la misma versión del flujo (version()) tanto para la lectura como para la escritura. Si necesitas compatibilidad tanto hacia adelante como hacia atrás, puedes codificar el número de versión de forma fija en la aplicación:

stream.setVersion(QDataStream::Qt_4_0);

Si estás creando un nuevo formato de datos binarios, como un formato de archivo para documentos generados por tu aplicación, podrías utilizar un QDataStream para escribir los datos en un formato portátil. Normalmente, escribirías un breve encabezado que contuviera una cadena mágica y un número de versión para dejarte margen para futuras ampliaciones. Por ejemplo:

QFile file("file.xxx");
file.open(QIODevice::WriteOnly);
QDataStream out(&file);

// Write a header with a "magic number" and a version
out << (quint32)0xA0B0C0D0;
out << (qint32)123;

out.setVersion(QDataStream::Qt_4_0);

// Write the data
out << lots_of_interesting_data;

A continuación, léelo con:

QFile file("file.xxx");
file.open(QIODevice::ReadOnly);
QDataStream in(&file);

// Read and check the header
quint32 magic;
in >> magic;
if (magic != 0xA0B0C0D0)
    return XXX_BAD_FILE_FORMAT;

// Read the version
qint32 version;
in >> version;
if (version < 100)
    return XXX_BAD_FILE_TOO_OLD;
if (version > 123)
    return XXX_BAD_FILE_TOO_NEW;

if (version <= 110)
    in.setVersion(QDataStream::Qt_3_1);
else
    in.setVersion(QDataStream::Qt_4_0);

// Read the data
in >> lots_of_interesting_data;
if (version >= 120)
    in >> data_new_in_XXX_version_1_2;
in >> other_interesting_data;

Puedes seleccionar qué orden de bytes utilizar al serializar datos. La configuración predeterminada es «big-endian» (MSB primero). Cambiarla a «little-endian» afecta a la portabilidad (a menos que el lector también cambie a «little-endian»). Recomendamos mantener esta configuración a menos que tengas requisitos especiales.

Lectura y escritura de datos binarios sin procesar

Es posible que desee leer o escribir sus propios datos binarios sin procesar directamente en el flujo de datos. Los datos se pueden leer del flujo y almacenarlos en un « char * » preasignado mediante ` readRawData()`. Del mismo modo, los datos se pueden escribir en el flujo mediante ` writeRawData()`. Tenga en cuenta que cualquier codificación o decodificación de los datos debe realizarla usted mismo.

Un par de funciones similares son readBytes() y writeBytes(). Estas difieren de sus homólogas «en bruto» de la siguiente manera: readBytes() lee un valor «quint32» que se toma como la longitud de los datos que se van a leer; a continuación, se lee ese número de bytes en el char * preasignado; writeBytes() escribe un valor «quint32» que contiene la longitud de los datos, seguido de los datos. Ten en cuenta que cualquier codificación o decodificación de los datos (aparte del valor «quint32» de la longitud) debe realizarla tú mismo.

Lectura y escritura en clases de colección de Qt

Las clases contenedoras de Qt también pueden serializarse en un QDataStream. Entre ellas se incluyen QList, QSet, QHash y QMap. Los operadores de flujo se declaran como no miembros de las clases.

Lectura y escritura de otras clases de Qt

Además de los operadores de flujo sobrecargados que se documentan aquí, cualquier clase de Qt que se desee serializar a un QDataStream tendrá los operadores de flujo adecuados declarados como no miembros de la clase:

QDataStream &operator<<(QDataStream &, const QXxx &);
QDataStream &operator>>(QDataStream &, QXxx &);

Por ejemplo, estos son los operadores de flujo declarados como no miembros de la clase ` QImage `:

QDataStream &operator<<(QDataStream &stream, const QImage &image);
QDataStream &operator>>(QDataStream &stream, QImage &image);

Para comprobar si tu clase favorita de Qt tiene definidos operadores de flujo similares, consulta la sección «Elementos no miembros relacionados» de la página de documentación de la clase.

Uso de transacciones de lectura

Cuando un flujo de datos opera en un dispositivo asíncrono, los bloques de datos pueden llegar en momentos arbitrarios. La clase `QDataStream` implementa un mecanismo de transacciones que permite leer los datos de forma atómica mediante una serie de operadores de flujo. A modo de ejemplo, puedes gestionar lecturas incompletas desde un socket utilizando una transacción en una ranura conectada a la señal `readyRead()`:

in.startTransaction();
QString str;
qint32 a;
in >> str >> a; // try to read packet atomically

if (!in.commitTransaction())
    return;     // wait for more data

Si no se recibe ningún paquete completo, este código restablece el flujo a la posición inicial, tras lo cual hay que esperar a que lleguen más datos.

Datos dañados y seguridad

QDataStream no es resistente a entradas de datos dañadas y, por lo tanto, no debe utilizarse en situaciones en las que la seguridad sea un factor crítico, ni siquiera cuando se utilicen transacciones. Las transacciones ayudarán a determinar si una entrada válida puede decodificarse en ese momento con los datos disponibles en un dispositivo asíncrono, pero darán por sentado que los datos disponibles están correctamente formados.

Además, muchos operadores de desmarcado de QDataStream asignarán memoria basándose en la información que se encuentre en el flujo. Dichos operadores no verifican si la cantidad de memoria solicitada es razonable ni si es compatible con la cantidad de datos disponibles en el flujo (por ejemplo: al desmarcar un ` QByteArray ` o un ` QString `, puede solicitarse la asignación de varios gigabytes de datos).

QDataStream no debe utilizarse con contenidos cuya procedencia no sea fiable. Las aplicaciones deben diseñarse para intentar descodificar únicamente flujos cuya procedencia sea, como mínimo, tan fiable como la de la propia aplicación o sus complementos.

Véase también QTextStream y QVariant.

Documentación sobre los tipos de miembro

enum QDataStream::ByteOrder

El orden de los bytes utilizado para leer y escribir los datos.

ConstanteValorDescripción
QDataStream::BigEndianQSysInfo::BigEndianPrimero el byte más significativo (valor por defecto)
QDataStream::LittleEndianQSysInfo::LittleEndianPrimero el byte menos significativo

enum QDataStream::FloatingPointPrecision

La precisión de los números de coma flotante utilizados para leer y escribir los datos. Esto solo tendrá efecto si la versión del flujo de datos es Qt_4_6 o superior.

Advertencia: La precisión de coma flotante debe establecerse en el mismo valor tanto en el objeto que escribe como en el que lee el flujo de datos.

ConstanteValorDescripción
QDataStream::SinglePrecision0Todos los números de coma flotante del flujo de datos tienen una precisión de 32 bits.
QDataStream::DoublePrecision1Todos los números de coma flotante del flujo de datos tienen una precisión de 64 bits.

Véase también setFloatingPointPrecision() y floatingPointPrecision().

enum QDataStream::Status

Esta enumeración describe el estado actual del flujo de datos.

ConstanteValorDescripción
QDataStream::Ok0El flujo de datos funciona con normalidad.
QDataStream::ReadPastEnd1El flujo de datos ha leído más allá del final de los datos del dispositivo subyacente.
QDataStream::ReadCorruptData2El flujo de datos ha leído datos dañados.
QDataStream::WriteFailed3El flujo de datos no puede escribir en el dispositivo subyacente.
QDataStream::SizeLimitExceeded (since Qt 6.7)4El flujo de datos no puede leer ni escribir los datos porque su tamaño supera el admitido por la plataforma actual. Esto puede ocurrir, por ejemplo, al intentar leer más de 2 GiB de datos en una plataforma de 32 bits.

enum QDataStream::Version

Esta enumeración proporciona sinónimos simbólicos para los números de versión del formato de serialización de datos.

ConstanteValor
QDataStream::Qt_1_01
QDataStream::Qt_2_02
QDataStream::Qt_2_13
QDataStream::Qt_3_04
QDataStream::Qt_3_15
QDataStream::Qt_3_36
QDataStream::Qt_4_07
QDataStream::Qt_4_1Qt_4_0
QDataStream::Qt_4_28
QDataStream::Qt_4_39
QDataStream::Qt_4_410
QDataStream::Qt_4_511
QDataStream::Qt_4_612
QDataStream::Qt_4_7Qt_4_6
QDataStream::Qt_4_8Qt_4_7
QDataStream::Qt_4_9Qt_4_8
QDataStream::Qt_5_013
QDataStream::Qt_5_114
QDataStream::Qt_5_215
QDataStream::Qt_5_3Qt_5_2
QDataStream::Qt_5_416
QDataStream::Qt_5_5Qt_5_4
QDataStream::Qt_5_617
QDataStream::Qt_5_7Qt_5_6
QDataStream::Qt_5_8Qt_5_7
QDataStream::Qt_5_9Qt_5_8
QDataStream::Qt_5_10Qt_5_9
QDataStream::Qt_5_11Qt_5_10
QDataStream::Qt_5_1218
QDataStream::Qt_5_1319
QDataStream::Qt_5_14Qt_5_13
QDataStream::Qt_5_15Qt_5_14
QDataStream::Qt_6_020
QDataStream::Qt_6_1Qt_6_0
QDataStream::Qt_6_2Qt_6_0
QDataStream::Qt_6_3Qt_6_0
QDataStream::Qt_6_4Qt_6_0
QDataStream::Qt_6_5Qt_6_0
QDataStream::Qt_6_621
QDataStream::Qt_6_722
QDataStream::Qt_6_8Qt_6_7
QDataStream::Qt_6_9Qt_6_7
QDataStream::Qt_6_1023
QDataStream::Qt_6_1124
QDataStream::Qt_6_12Qt_6_11

Véase también setVersion() y version().

Documentación de las funciones de miembro

QDataStream::QDataStream()

Crea un flujo de datos que no tiene ningún dispositivo de E/S.

Véase también setDevice().

[explicit] QDataStream::QDataStream(QIODevice *d)

Crea un flujo de datos que utiliza el dispositivo de E/S d.

Véase también setDevice() y device().

QDataStream::QDataStream(const QByteArray &a)

Crea un flujo de datos de solo lectura que opera sobre una matriz de bytes a. Utiliza QDataStream(QByteArray*, int) si deseas escribir en una matriz de bytes.

Dado que QByteArray no es una subclase de QIODevice, internamente se crea un QBuffer para envolver la matriz de bytes.

QDataStream::QDataStream(QByteArray *a, QIODeviceBase::OpenMode mode)

Crea un flujo de datos que opera sobre una matriz de bytes, a. El documento « mode » describe cómo se debe utilizar el dispositivo.

Como alternativa, puedes utilizar QDataStream(const QByteArray &) si solo deseas leer desde una matriz de bytes.

Dado que ` QByteArray ` no es una subclase de ` QIODevice `, internamente se crea un ` QBuffer ` para envolver la matriz de bytes.

[noexcept] QDataStream::~QDataStream()

Destruye el flujo de datos.

El destructor no afectará al dispositivo de E/S actual, a menos que se trate de un dispositivo de E/S interno (por ejemplo, un ` QBuffer`) que esté procesando un ` QByteArray ` pasado en el constructor, en cuyo caso se destruye el dispositivo de E/S interno.

void QDataStream::abortTransaction()

Cancela una transacción de lectura.

Esta función se utiliza habitualmente para descartar la transacción tras errores de protocolo de nivel superior o la pérdida de sincronización del flujo.

Si se invoca en una transacción interna, el aborto se delega a la transacción más externa, y las transacciones internas iniciadas posteriormente se ven obligadas a fallar.

En el caso de la transacción más externa, descarta el punto de restauración y cualquier dato duplicado internamente del flujo. No afectará a la posición de lectura actual del flujo.

Establece el estado del flujo de datos en

ConstanteDescripción
ReadCorruptData.

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

bool QDataStream::atEnd() const

Devuelve « true » si el dispositivo de E/S ha llegado al final (final del flujo o del archivo) o si no hay ningún dispositivo de E/S configurado; en caso contrario, devuelve « false ».

Véase también QIODevice::atEnd().

QDataStream::ByteOrder QDataStream::byteOrder() const

Devuelve la configuración actual del orden de bytes: « BigEndian » o « LittleEndian ».

Véase también setByteOrder().

bool QDataStream::commitTransaction()

Finaliza una transacción de lectura. Devuelve ` true ` si no se han producido errores de lectura durante la transacción; en caso contrario, devuelve ` false`.

Si se invoca en una transacción interna, la confirmación se pospondrá hasta que se produzca la llamada más externa a `commitTransaction()`, ` rollbackTransaction()` o ` abortTransaction()`.

De lo contrario, si el estado del flujo indica que se ha leído más allá del final de los datos, esta función restaura los datos del flujo hasta el punto de la llamada a ` startTransaction()`. Cuando se produce esta situación, es necesario esperar a que lleguen más datos, tras lo cual se inicia una nueva transacción. Si el flujo de datos ha leído datos corruptos o si alguna de las transacciones internas se ha abortado, esta función aborta la transacción.

Véanse también startTransaction(), rollbackTransaction() y abortTransaction().

QIODevice *QDataStream::device() const

Devuelve el dispositivo de E/S configurado actualmente, o « nullptr » si no hay ningún dispositivo configurado.

Véase también setDevice().

QDataStream::FloatingPointPrecision QDataStream::floatingPointPrecision() const

Devuelve la precisión en coma flotante del flujo de datos.

Véase también FloatingPointPrecision y setFloatingPointPrecision().

[since 6.7] QDataStream &QDataStream::readBytes(char *&s, qint64 &l)

Lee el búfer s del flujo y devuelve una referencia al flujo.

El búfer s se asigna mediante new []. Destrúyelo con el operador delete [].

El parámetro ` l ` se establece en la longitud del búfer. Si la cadena leída está vacía, ` l ` se establece en 0 y ` s ` se establece en ` nullptr`.

El formato de serialización consiste primero en un especificador de longitud y, a continuación, en l bytes de datos. El especificador de longitud es un quint32 si la versión es inferior a 6.7 o si el número de elementos es inferior a 0xfffffffe (2^32 - 2); en caso contrario, hay un valor de extensión 0xfffffffe seguido de un quint64 con el valor real. Además, en el caso de los contenedores que admiten isNull(), se codifica como un único quint32 con todos los bits activados y sin datos.

Esta función se introdujo en Qt 6.7.

Véase también readRawData() y writeBytes().

qint64 QDataStream::readRawData(char *s, qint64 len)

Lee como máximo len bytes del flujo en s y devuelve el número de bytes leídos. Si se produce un error, esta función devuelve -1.

El búfer s debe estar preasignado. Los datos no se decodifican.

Véanse también readBytes(), QIODevice::read() y writeRawData().

void QDataStream::resetStatus()

Restablece el estado del flujo de datos.

Véanse también Status, status() y setStatus().

void QDataStream::rollbackTransaction()

Anula una transacción de lectura.

Esta función se utiliza habitualmente para revertir la transacción cuando se detecta una lectura incompleta antes de confirmar la transacción.

Si se invoca en una transacción interna, la reversión se delega a la transacción más externa, y las transacciones internas iniciadas posteriormente se ven obligadas a fallar.

En el caso de la transacción más externa, restaura los datos del flujo hasta el momento de la llamada a ` startTransaction()`. Si el flujo de datos ha leído datos corruptos o si se ha abortado alguna de las transacciones internas, esta función aborta la transacción.

Si las operaciones de flujo anteriores se han realizado con éxito, establece el estado del flujo de datos en

ConstanteDescripción
ReadPastEnd.

Véase también startTransaction(), commitTransaction() y abortTransaction().

void QDataStream::setByteOrder(QDataStream::ByteOrder bo)

Establece el orden de los bytes de serialización en « bo ».

El parámetro « bo » puede ser « QDataStream::BigEndian » o « QDataStream::LittleEndian ».

La configuración predeterminada es «big-endian». Recomendamos mantener esta configuración a menos que tengas requisitos especiales.

Véase también byteOrder().

void QDataStream::setDevice(QIODevice *d)

void QDataStream::setDevice(QIODevice *d)

Establece el dispositivo de E/S en ` d`, que puede ser ` nullptr ` para desactivar el dispositivo de E/S actual.

Véase también device().

void QDataStream::setFloatingPointPrecision(QDataStream::FloatingPointPrecision precision)

Establece la precisión en coma flotante del flujo de datos en precision. Si la precisión en coma flotante es DoublePrecision y la versión del flujo de datos es Qt_4_6 o superior, todos los números en coma flotante se escribirán y leerán con una precisión de 64 bits. Si la precisión en coma flotante es SinglePrecision y la versión es Qt_4_6 o superior, todos los números en coma flotante se escribirán y leerán con una precisión de 32 bits.

Para versiones anteriores a Qt_4_6, la precisión de los números de coma flotante en el flujo de datos depende del operador de flujo invocado.

El valor predeterminado es DoublePrecision.

Tenga en cuenta que esta propiedad no afecta a la serialización ni a la deserialización de las instancias de ` qfloat16 `.

Advertencia: Esta propiedad debe establecerse en el mismo valor tanto en el objeto que escribe como en el que lee el flujo de datos.

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

void QDataStream::setStatus(QDataStream::Status status)

Establece el estado del flujo de datos en el valor « status » indicado.

Las llamadas posteriores a setStatus() se ignoran hasta que se llame a resetStatus().

Véase también Status, status() y resetStatus().

void QDataStream::setVersion(int v)

Establece el número de versión del formato de serialización de datos en « v », un valor de la enumeración « Version ».

No es necesario establecer una versión si se utiliza la versión actual de Qt, pero en el caso de formatos binarios personalizados, se recomienda hacerlo; véase « Versioning » en la «Descripción detallada».

Para dar cabida a nuevas funcionalidades, el formato de serialización de flujos de datos de algunas clases de Qt ha cambiado en algunas versiones de Qt. Si desea leer datos creados por una versión anterior de Qt, o escribir datos que puedan ser leídos por un programa compilado con una versión anterior de Qt, utilice esta función para modificar el formato de serialización utilizado por ` QDataStream`.

La enumeración ` Version ` proporciona constantes simbólicas para las diferentes versiones de Qt. Por ejemplo:

QDataStream out(&file);
out.setVersion(QDataStream::Qt_4_0);

Véase también ` version()` y ` Version`.

qint64 QDataStream::skipRawData(qint64 len)

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

Esto equivale a llamar a readRawData() sobre un búfer de longitud len e ignorar el búfer.

Véase también QIODevice::seek().

void QDataStream::startTransaction()

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

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 del flujo. Llama a commitTransaction(), rollbackTransaction() o abortTransaction() para finalizar la transacción actual.

Una vez iniciada una transacción, las llamadas posteriores a esta función harán que la transacción sea recursiva. Las transacciones internas actúan como agentes de la transacción más externa (es decir, informan del estado de las operaciones de lectura a la transacción más externa, que puede restaurar la posición del flujo).

Nota: No se admitela restauración hasta el punto de la llamada anidada a startTransaction().

Cuando se produce un error durante una transacción (incluido el fallo de una transacción interna), se suspende la lectura del flujo de datos (todas las operaciones de lectura posteriores devuelven valores vacíos o cero) y las transacciones internas posteriores se ven obligadas a fallar. Iniciar una nueva transacción más externa permite recuperarse de este estado. Este comportamiento hace que no sea necesario comprobar por separado si hay errores en cada operación de lectura.

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

QDataStream::Status QDataStream::status() const

Devuelve el estado del flujo de datos.

Véase también Status, setStatus() y resetStatus().

int QDataStream::version() const

Devuelve el número de versión del formato de serialización de datos.

Véase también setVersion() y Version.

QDataStream &QDataStream::writeBytes(const char *s, qint64 len)

Escribe el especificador de longitud len y el búfer s en el flujo y devuelve una referencia al flujo.

El valor len se serializa como un quint32 y un quint64 opcional, seguido de len bytes procedentes de s. Ten en cuenta que los datos no están codificados.

Véase también writeRawData() y readBytes().

qint64 QDataStream::writeRawData(const char *s, qint64 len)

Escribe len bytes desde s en el flujo. Devuelve el número de bytes realmente escritos, o -1 en caso de error. Los datos no están codificados.

Véase también writeBytes(), QIODevice::write() y readRawData().

[explicit noexcept, since 6.10] QDataStream::operator bool() const

Devuelve si este flujo no presenta errores (status() devuelve Ok).

Esta función se introdujo en Qt 6.10.

QDataStream &QDataStream::operator<<(qint8 i)

Escribe un byte con signo, i, en el flujo y devuelve una referencia al mismo.

QDataStream &QDataStream::operator<<(bool i)

Escribe un valor booleano, i, en el flujo. Devuelve una referencia al flujo.

Esta es una función sobrecargada.

[since 6.0] QDataStream &QDataStream::operator<<(char16_t c)

Escribe un carácter, c, en el flujo. Devuelve una referencia al flujo

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.0.

[since 6.0] QDataStream &QDataStream::operator<<(char32_t c)

Escribe un carácter, c, en el flujo. Devuelve una referencia al flujo

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.0.

QDataStream &QDataStream::operator<<(const char *s)

Escribe la cadena « s », terminada con «\0 », en el flujo y devuelve una referencia al mismo.

La cadena se serializa utilizando writeBytes().

Esta es una función sobrecargada.

Véanse también writeBytes() y writeRawData().

QDataStream &QDataStream::operator<<(double f)

Escribe un número de coma flotante, f, en el flujo utilizando el formato estándar IEEE 754. Devuelve una referencia al flujo.

Esta es una función sobrecargada.

Véase también setFloatingPointPrecision().

QDataStream &QDataStream::operator<<(float f)

Escribe un número de coma flotante, f, en el flujo utilizando el formato estándar IEEE 754. Devuelve una referencia al flujo.

Esta es una función sobrecargada.

Véase también setFloatingPointPrecision().

QDataStream &QDataStream::operator<<(qint16 i)

Escribe un entero con signo de 16 bits, i, en el flujo y devuelve una referencia al mismo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator<<(qint32 i)

Escribe un entero con signo de 32 bits, i, en el flujo y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator<<(qint64 i)

Escribe un entero con signo de 64 bits, i, en el flujo y devuelve una referencia al mismo.

Se trata de una función sobrecargada.

QDataStream &QDataStream::operator<<(quint16 i)

Escribe un entero sin signo de 16 bits, ` i`, en el flujo y devuelve una referencia al flujo.

Se trata de una función sobrecargada.

QDataStream &QDataStream::operator<<(quint32 i)

Escribe un entero sin signo, ` i`, en el flujo como un entero sin signo de 32 bits (`quint32`). Devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator<<(quint64 i)

Escribe un entero sin signo de 64 bits, i, en el flujo y devuelve una referencia al mismo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator<<(quint8 i)

Escribe un byte sin signo, i, en el flujo y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator<<(std::nullptr_t ptr)

Simula la escritura de un ` std::nullptr_t`, ` ptr`, en el flujo y devuelve una referencia al mismo. Esta función no escribe realmente nada en el flujo, ya que los valores ` std::nullptr_t ` se almacenan como 0 bytes.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(bool &i)

Lee un valor booleano del flujo y lo asign i. Devuelve una referencia al flujo.

QDataStream &QDataStream::operator>>(qint8 &i)

Lee un byte con signo del flujo y lo asigna a ` i`, y devuelve una referencia al flujo.

QDataStream &QDataStream::operator>>(char *&s)

Lee la cadena « s » del flujo y devuelve una referencia al flujo.

La cadena se deserializa utilizando readBytes(), donde el formato de serialización consiste primero en un especificador de longitud quint32, seguido de ese mismo número de bytes de datos. La cadena resultante siempre termina en «\0 ».

El espacio para la cadena se asigna mediante ` new [] `; el llamante debe destruirlo con ` delete []`.

Esta es una función sobrecargada.

Véanse también readBytes() y readRawData().

[since 6.0] QDataStream &QDataStream::operator>>(char16_t &c)

Lee un carácter de 16 bits del flujo y lo asigna a ` c `, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.0.

[since 6.0] QDataStream &QDataStream::operator>>(char32_t &c)

Lee un carácter de 32 bits del flujo y lo asigna a ` c `, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

Esta función se introdujo en Qt 6.0.

QDataStream &QDataStream::operator>>(double &f)

Lee un número de coma flotante del flujo y lo asigna a ` f`, utilizando el formato estándar IEEE 754. Devuelve una referencia al flujo.

Esta es una función sobrecargada.

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

QDataStream &QDataStream::operator>>(float &f)

Lee un número de coma flotante del flujo y lo asigna a ` f`, utilizando el formato estándar IEEE 754. Devuelve una referencia al flujo.

Esta es una función sobrecargada.

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

QDataStream &QDataStream::operator>>(qint16 &i)

Lee un entero con signo de 16 bits del flujo y lo asigna a ` i`, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(qint32 &i)

Lee un entero con signo de 32 bits del flujo y lo asigna a ` i`, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(qint64 &i)

Lee un entero con signo de 64 bits del flujo y lo asigna a ` i`, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(quint16 &i)

Lee un entero sin signo de 16 bits del flujo y lo asigna a ` i`, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(quint32 &i)

Lee un entero sin signo de 32 bits del flujo y lo asigna a ` i`, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(quint64 &i)

Lee un entero sin signo de 64 bits del flujo, lo asigna a ` i` y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(quint8 &i)

Lee un byte sin signo del flujo y lo asigna a ` i`, y devuelve una referencia al flujo.

Esta es una función sobrecargada.

QDataStream &QDataStream::operator>>(std::nullptr_t &ptr)

Simula la lectura de un ` std::nullptr_t ` del flujo en ` ptr ` y devuelve una referencia al flujo. Esta función no lee realmente nada del flujo, ya que los valores de ` std::nullptr_t ` se almacenan como 0 bytes.

Esta es una función sobrecargada.

Elementos no miembros relacionados

[since 6.0] template <typename T1, typename T2> QDataStream &operator<<(QDataStream &out, const std::pair<T1, T2> &pair)

Escribe el par pair en el flujo out.

Esta función requiere que los tipos T1 y T2 implementen operator<<().

Esta función se introdujo en Qt 6.0.

Véase también «Serialización detipos de datos de Qt».

QDataStream &operator<<(QDataStream &ds, qfloat16 f)

Escribe un número de coma flotante, ` f`, en el flujo ` ds ` utilizando el formato estándar IEEE 754. Devuelve una referencia al flujo.

Nota: En las versiones de Qt anteriores a la 6.3, se trataba de una función miembro de ` QDataStream`.

QDataStream &operator>>(QDataStream &ds, qfloat16 &f)

Lee un número de coma flotante del flujo « ds » y lo asigna a « f », utilizando el formato estándar IEEE 754. Devuelve una referencia al flujo.

Nota: En las versiones de Qt anteriores a la 6.3, se trataba de una función miembro de ` QDataStream`.

[since 6.0] template <typename T1, typename T2> QDataStream &operator>>(QDataStream &in, std::pair<T1, T2> &pair)

Lee un par del flujo « in » y lo guarda en « pair ».

Esta función requiere que los tipos T1 y T2 implementen operator>>().

Esta función se introdujo en Qt 6.0.

Véase también Serialización detipos de datos de Qt.

© 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.