Класс QDataStream

Класс QDataStream предоставляет сериализацию двоичных данных в QIODevice. Подробнее...

• Список всех членов, включая унаследованные
• Устаревшие члены

Примечание: Все функции в этом классе являются повторно входящими.

Публичные типы

Публичные функции

Подробное описание

Класс QDataStream обеспечивает сериализацию двоичных данных в QIODevice.

Поток данных — это двоичный поток закодированной информации, который полностью независим от операционной системы, процессора или порядка байтов хост-компьютера. Например, поток данных, записанный ПК под управлением Windows, может быть прочитан Sun SPARC, работающим под Solaris.

Вы также можете использовать поток данных для чтения/записи сырых не закодированных двоичных данных. Если вам нужен поток входных данных для «парсинга», используйте QTextStream.

Класс QDataStream реализует сериализацию основных типов данных C++, таких как char, short, int, char *, и т.д. Сериализация более сложных данных достигается путем разбивки данных на элементарные единицы.

Поток данных тесно взаимодействует с QIODevice. QIODevice представляет собой среду ввода/вывода, из которой можно читать данные и в которую можно записывать данные. Примером устройства ввода/вывода является класс QFile.

Пример (запись двоичных данных в поток):

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

Пример (чтение двоичных данных из потока):

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

Каждый элемент, записанный в поток, записывается в предопределённом двоичном формате, который зависит от типа элемента. Поддерживаемые типы Qt включают QBrush, QColor, QDateTime, QFont, QPixmap, QString, QVariant и многие другие. Полный список всех типов Qt, поддерживающих передачу данных, см. в Сериализация типов данных Qt.

Для целых чисел лучше всегда преобразовывать их в тип Qt целых чисел при записи и считывать обратно в тот же тип Qt целых чисел. Это гарантирует, что вы получите целые числа нужного размера и защитит вас от различий в компиляторах и платформах.

Например, строка char * записывается как 32-битное целое число, равное длине строки, включая байт '\0', за которым следуют все символы строки, включая байт '\0'. При чтении строки char *, сначала считываются 4 байта для создания 32-битного значения длины, а затем столько символов для строки char * , включая завершающий символ '\0'.

Начальное устройство ввода-вывода обычно задаётся в конструкторе, но его можно изменить с помощью setDevice(). Если вы достигли конца данных (или если устройство ввода-вывода не установлено), atEnd() вернёт true.

Версионирование

QDataStream's двоичный формат эволюционировал с Qt 1.0 и, вероятно, будет продолжать эволюционировать, отражая изменения, внесённые в Qt. При вводе или выводе сложных типов очень важно убедиться, что используется та же версия потока (version()), что и при чтении, и при записи. Если вам нужна как вперёд, так и назад совместимость, вы можете жёстко запрограммировать номер версии в приложении:

stream.setVersion(QDataStream::Qt_4_0);

Если вы создаёте новый двоичный формат данных, например, формат файла для документов, созданных вашим приложением, вы можете использовать QDataStream для записи данных в переносимый формат. Обычно вы пишете краткий заголовок, содержащий магическую строку и номер версии, чтобы оставить место для будущих расширений. Например:

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;

Затем прочитайте его с помощью:

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_2);
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;

Вы можете выбрать порядок байтов для сериализации данных. По умолчанию используется порядок big endian (MSB первым). Изменение его на little endian нарушает переносимость (если читатель также не изменит порядок на little endian). Мы рекомендуем сохранить это значение, если у вас нет особых требований.

Чтение и запись сырых двоичных данных

Возможно, вам захочется напрямую читать/записывать свои собственные сырые двоичные данные в/из потока данных. Данные могут быть прочитаны из потока в предварительно выделенный char * с помощью readRawData(). Аналогичным образом данные могут быть записаны в поток с помощью writeRawData(). Обратите внимание, что любое кодирование/декодирование данных должно выполняться вами.

Аналогичная пара функций — readBytes() и writeBytes(). Эти функции отличаются от своих сырых аналогов следующим образом: readBytes() считывает quint32, который принимается за длину считываемых данных, затем столько байтов считываются в предварительно выделенный char *; writeBytes() записывает quint32, содержащий длину данных, за которой следуют данные. Обратите внимание, что любое кодирование/декодирование данных (кроме quint32 длины) должно выполняться вами.

Чтение и запись классов коллекций Qt

Классы контейнеров Qt также могут быть сериализованы в QDataStream. К ним относятся QList, QLinkedList, QVector, QSet, QHash и QMap. Операторы потоков объявлены как внеклассовые для этих классов.

Чтение и запись других классов Qt

В дополнение к перегруженным операторам потоков, документированным здесь, для любых классов Qt, которые вы хотите сериализовать в QDataStream, будут объявлены соответствующие операторы потоков как внеклассовые:

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

Например, вот операторы потоков, объявленные как внеклассовые для класса QImage:

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

Чтобы узнать, определены ли аналогичные операторы потоков для вашего любимого класса Qt, проверьте раздел Связанные внеклассовые члены на странице документации класса.

Использование транзакций чтения

Когда поток данных работает с асинхронным устройством, фрагменты данных могут поступать в произвольные моменты времени. Класс QDataStream реализует механизм транзакций, который позволяет читать данные атомарно с помощью ряда операторов потока. Например, вы можете обрабатывать неполные чтения из сокета, используя транзакцию в слоте, подключенном к сигналу readyRead():

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

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

Если не получен полный пакет, этот код восстанавливает поток в начальную позицию, после чего вам нужно дождаться прибытия дополнительных данных.

См. также QTextStream и QVariant.

Документация по членам типа

enum QDataStream::ByteOrder

Порядок байтов, используемый для чтения/записи данных.

enum QDataStream::FloatingPointPrecision

Точность чисел с плавающей точкой, используемых для чтения/записи данных. Это повлияет только в том случае, если версия потока данных Qt_4_6 или выше.

Предупреждение: Точность чисел с плавающей точкой должна быть установлена в одном и том же значении для объекта, который записывает, и для объекта, который считывает поток данных.

См. также setFloatingPointPrecision() и floatingPointPrecision().

enum QDataStream::Status

Этот перечисление описывает текущее состояние потока данных.

enum QDataStream::Version

Это перечисление предоставляет символические синонимы для номеров версии формата сериализации данных.

См. также setVersion() и version().

Документация по функциям-членам

QDataStream::QDataStream()

Создаёт поток данных без устройства ввода-вывода.

См. также setDevice().

QDataStream::QDataStream(QIODevice *d)

Создаёт поток данных, использующий устройство ввода-вывода d.

См. также setDevice() и device().

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

Создаёт поток данных, работающий с массивом байтов a. Параметр mode определяет способ использования устройства.

В качестве альтернативы можно использовать QDataStream(const QByteArray &) для чтения из массива байтов.

Поскольку QByteArray не является подклассом QIODevice, внутри создаётся объект QBuffer для обертывания массива байтов.

QDataStream::QDataStream(const QByteArray &a)

Создаёт поток данных только для чтения, работающий с массивом байтов a. Используйте QDataStream(QByteArray*, int), если хотите записывать в массив байтов.

Поскольку QByteArray не является подклассом QIODevice, внутри создаётся объект QBuffer для обертывания массива байтов.

QDataStream::~QDataStream()

Уничтожает поток данных.

Деструктор не повлияет на текущее устройство ввода-вывода, за исключением случаев, когда это внутреннее устройство ввода-вывода (например, QBuffer), обрабатывающее QByteArray, переданный в конструктор; в этом случае внутреннее устройство ввода-вывода уничтожается.

void QDataStream::abortTransaction()

Прерывает транзакцию чтения.

Эта функция обычно используется для отбрасывания транзакции после ошибок протокола высокого уровня или потери синхронизации потока.

Если вызывается на внутренней транзакции, прерывание делегируется внешней транзакции, и все последующие начатые внутренние транзакции принудительно завершаются ошибкой.

Для внешней транзакции, отбрасывает точку восстановления и все внутренние дублированные данные потока. Не повлияет на текущую позицию чтения в потоке.

Устанавливает состояние потока данных в

Эта функция была добавлена в Qt 5.7.

См. также startTransaction(), commitTransaction() и rollbackTransaction().

bool QDataStream::atEnd() const

Возвращает true , если устройство ввода-вывода достигло конечной позиции (конец потока или файла) или если устройство ввода-вывода не задано; в противном случае возвращает false.

См. также QIODevice::atEnd().

ByteOrder QDataStream::byteOrder() const

Возвращает текущую установку порядка байтов — либо BigEndian, либо LittleEndian.

См. также setByteOrder().

bool QDataStream::commitTransaction()

Завершает транзакцию чтения. Возвращает true , если ошибок чтения во время транзакции не произошло; в противном случае возвращает false.

Если вызывается на внутренней транзакции, подтверждение будет отложено до вызова commitTransaction(), rollbackTransaction() или abortTransaction().

В противном случае, если состояние потока указывает на чтение за пределами данных, эта функция восстанавливает данные потока до момента вызова startTransaction(). В этой ситуации необходимо дождаться получения дополнительных данных, после чего начать новую транзакцию. Если поток данных прочитал повреждённые данные или любая из внутренних транзакций была прервана, эта функция прерывает транзакцию.

Эта функция была добавлена в Qt 5.7.

См. также startTransaction(), rollbackTransaction() и abortTransaction().

QIODevice *QDataStream::device() const

Возвращает установленное в данный момент устройство ввода-вывода или 0, если устройство не установлено.

См. также setDevice().

FloatingPointPrecision QDataStream::floatingPointPrecision() const

Возвращает точность плавающей точки потока данных.

Эта функция была добавлена в Qt 4.6.

См. также FloatingPointPrecision и setFloatingPointPrecision().

QDataStream &QDataStream::readBytes(char *&s, uint &l)

Считывает буфер s из потока и возвращает ссылку на поток.

Буфер s выделяется с помощью new []. Уничтожьте его с помощью оператора delete [].

Параметр l устанавливается в длину буфера. Если считанная строка пустая, l устанавливается в 0, а s — в нулевой указатель.

Формат сериализации — это сначала спецификатор длины quint32, затем l байтов данных.

См. также readRawData() и writeBytes().

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

Читает не более len байтов из потока в s и возвращает количество прочитанных байтов. Если произошла ошибка, функция возвращает -1.

Буфер s должен быть предварительно выделен. Данные не закодированы.

См. также readBytes(), QIODevice::read() и writeRawData().

void QDataStream::resetStatus()

Сбрасывает состояние потока данных.

См. также Status, status() и setStatus().

void QDataStream::rollbackTransaction()

Откатывает транзакцию чтения.

Эта функция обычно используется для отката транзакции, когда перед подтверждением транзакции было обнаружено неполное чтение.

Если вызвана для внутренней транзакции, откат делегируется самой внешней транзакции, а запущенные внутренние транзакции принудительно завершаются неудачей.

Для самой внешней транзакции восстанавливает данные потока до момента вызова startTransaction(). Если поток данных прочитал повреждённые данные или любая из внутренних транзакций была прервана, эта функция прерывает транзакцию.

Если предыдущие операции потока были успешными, устанавливает состояние потока данных в

Эта функция была добавлена в Qt 5.7.

См. также startTransaction(), commitTransaction() и abortTransaction().

void QDataStream::setByteOrder(ByteOrder bo)

Устанавливает порядок байтов сериализации на bo.

Параметр bo может быть QDataStream::BigEndian или QDataStream::LittleEndian.

По умолчанию используется порядок big endian. Рекомендуется не менять этот параметр, если у вас нет особых требований.

См. также byteOrder().

void QDataStream::setDevice(QIODevice *d)

void QDataStream::setDevice(QIODevice *d)

Устанавливает устройство ввода-вывода на d. Может быть 0, чтобы сбросить текущее устройство ввода-вывода.

См. также device().

void QDataStream::setFloatingPointPrecision(FloatingPointPrecision precision)

Устанавливает точность чисел с плавающей точкой потока данных на precision. Если точность чисел с плавающей точкой равна DoublePrecision, а версия потока данных равна Qt_4_6 или выше, все числа с плавающей точкой будут записываться и считываться с точностью 64 бита. Если точность чисел с плавающей точкой равна SinglePrecision, а версия равна Qt_4_6 или выше, все числа с плавающей точкой будут записываться и считываться с точностью 32 бита.

Для версий до Qt_4_6 точность чисел с плавающей точкой в потоке данных зависит от оператора потока, который используется.

По умолчанию используется DoublePrecision.

Обратите внимание, что этот параметр не влияет на сериализацию или десериализацию qfloat16 экземпляров.

Предупреждение: Этот параметр должен иметь одинаковое значение в объекте, который записывает, и объекте, который считывает поток данных.

Эта функция была добавлена в Qt 4.6.

См. также floatingPointPrecision().

void QDataStream::setStatus(Status status)

Устанавливает состояние потока данных на заданное значение status.

Последующие вызовы setStatus() игнорируются до тех пор, пока не будет вызван resetStatus().

См. также Status, status() и resetStatus().

void QDataStream::setVersion(int v)

Устанавливает номер версии формата сериализации данных на v, значение перечисления Version.

Вам не обязательно устанавливать версию, если вы используете текущую версию Qt, но для собственных пользовательских двоичных форматов рекомендуется это сделать; см. Versioning в подробном описании.

Для поддержки новых возможностей формат сериализации потока данных некоторых классов Qt изменился в некоторых версиях Qt. Если вы хотите прочитать данные, созданные более ранней версией Qt, или записать данные, которые может прочитать программа, скомпилированная с более ранней версией Qt, используйте эту функцию для изменения формата сериализации, используемого QDataStream.

Перечисление Version предоставляет символические константы для различных версий Qt. Например:

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

См. также version() и Version.

int QDataStream::skipRawData(int len)

Пропускает len байтов из устройства. Возвращает количество фактически пропущенных байтов или -1 при ошибке.

Это эквивалентно вызову readRawData() с буфером длиной len и игнорированию буфера.

Эта функция была добавлена в Qt 4.1.

См. также QIODevice::seek().

void QDataStream::startTransaction()

Начинает новую транзакцию чтения в потоке.

Определяет точку восстановления в последовательности операций чтения. Для последовательных устройств данные чтения будут дублироваться внутри, чтобы обеспечить восстановление в случае неполного чтения. Для устройств с произвольным доступом эта функция сохраняет текущую позицию потока. Вызовите commitTransaction(), rollbackTransaction() или abortTransaction(), чтобы завершить текущую транзакцию.

После начала транзакции последующие вызовы этой функции сделают транзакцию рекурсивной. Внутренние транзакции действуют как агенты самой внешней транзакции (т.е. сообщают о состоянии операций чтения самой внешней транзакции, которая может восстановить позицию потока).

Примечание: Восстановление до точки вложенного вызова startTransaction() не поддерживается.

При возникновении ошибки во время транзакции (включая неудачу внутренней транзакции), чтение из потока данных приостанавливается (все последующие операции чтения возвращают пустые/нулевые значения), и последующие внутренние транзакции принудительно завершаются неудачей. Запуск новой самой внешней транзакции восстанавливает из этого состояния. Такое поведение делает ненужным отдельную проверку ошибок каждой операции чтения.

Эта функция была добавлена в Qt 5.7.

См. также commitTransaction(), rollbackTransaction() и abortTransaction().

Status QDataStream::status() const

Возвращает состояние потока данных.

См. также Status, setStatus() и resetStatus().

int QDataStream::version() const

Возвращает номер версии формата сериализации данных.

См. также setVersion() и Version.

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

Записывает спецификатор длины len и буфер s в поток и возвращает ссылку на поток.

len сериализуется как quint32, за которым следуют len байтов из s. Обратите внимание, что данные не закодированы.

См. также writeRawData() и readBytes().

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

Записывает len байтов из s в поток. Возвращает количество фактически записанных байтов или -1 при ошибке. Данные не закодированы.

См. также writeBytes(), QIODevice::write() и readRawData().

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

Записывает знаковое байтовое значение, i, в поток и возвращает ссылку на поток.

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

Это перегруженная функция.

Записывает беззнаковое байтовое значение, i, в поток и возвращает ссылку на поток.

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

Это перегруженная функция.

Записывает знаковое 16-битное целое число, i, в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает целое беззнаковое 16-битное число, i, в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает целое знаковое 32-битное число, i, в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает целое беззнаковое число, i, в поток в формате 32-битного беззнакового целого числа (quint32). Возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает целое знаковое 64-битное число, i, в поток и возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает целое беззнаковое 64-битное число, i, в поток и возвращает ссылку на поток.

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

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

Записывает булево значение, i, в поток. Возвращает ссылку на поток.

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

Это перегруженный метод.

Записывает число с плавающей точкой, f, в поток в формате IEEE 754. Возвращает ссылку на поток.

Этот метод был добавлен в Qt 5.9.

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

Это перегруженный метод.

Записывает число с плавающей точкой, f, в поток в формате IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Записывает число с плавающей точкой, f, в поток в формате IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Записывает строку с завершением '\0', s, в поток и возвращает ссылку на поток.

Строка сериализуется с использованием writeBytes().

См. также writeBytes() и writeRawData().

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

Читает знаковое байтовое значение из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Читает беззнаковое байтовое значение из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Читает знаковое 16-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Читает беззнаковое 16-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Читает знаковое 32-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Читает беззнаковое 32-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Читает знаковое 64-битное целое число из потока в i и возвращает ссылку на поток.

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

Это перегруженный метод.

Читает беззнаковое 64-битное целое число из потока в i и возвращает ссылку на поток.

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

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

Читает булево значение из потока в i. Возвращает ссылку на поток.

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

Это перегруженный метод.

Читает число с плавающей точкой из потока в f в формате IEEE 754. Возвращает ссылку на поток.

Этот метод был добавлен в Qt 5.9.

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

Это перегруженный метод.

Читает число с плавающей точкой из потока в f в формате IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Читает число с плавающей точкой из потока в f в формате IEEE 754. Возвращает ссылку на поток.

См. также setFloatingPointPrecision().

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

Это перегруженный метод.

Читает строку с завершением '\0', s, из потока и возвращает ссылку на поток.

Память для строки выделяется с помощью new [], — вызывающий метод должен освободить ее с помощью delete [].

См. также readBytes() и readRawData().