Класс 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().

QDataStream::ByteOrder QDataStream::byteOrder() const

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

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

bool QDataStream::commitTransaction()

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

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

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

Функция была введена в Qt 5.7.

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

QIODevice *QDataStream::device() const

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

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

QDataStream::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(QDataStream::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(QDataStream::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(QDataStream::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().

QDataStream::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 ptr)

Это перегруженный функцию.

Имитирует запись std::nullptr_t, ptr, в поток и возвращает ссылку на поток. Эта функция фактически ничего не записывает в поток, так как значения std::nullptr_t хранятся как байты 0.

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

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)

Это перегруженный функцию.

Записывает строку 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)

Это перегруженный функцию.

Имитирует считывание std::nullptr_t из потока в ptr и возвращает ссылку на поток. Эта функция фактически ничего не считывает из потока, так как значения std::nullptr_t хранятся как 0 байт.

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

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)

Это перегруженный функцию.

Считывает строку s с завершающим нулём из потока и возвращает ссылку на поток.

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

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

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