Класс QSaveFile

Класс QSaveFile предоставляет интерфейс для безопасного записи в файлы. Подробнее...

Этот класс был представлен в Qt 5.1.

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

Примечание: Все функции в этом классе являются реентерабельными.

Открытые функции

Переопределённые открытые функции

Переопределённые защищённые функции

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

QSaveFile — это устройство ввода-вывода для записи текстовых и двоичных файлов без потери существующих данных в случае сбоя операции записи.

Во время записи содержимое записывается во временный файл, и если ошибок не произошло, commit() переместит его в конечный файл. Это гарантирует, что данные в конечном файле не будут потеряны в случае ошибки во время записи, и никогда не будет присутствовать частично записанный файл в конечном расположении. Всегда используйте QSaveFile при сохранении полных документов на диск.

QSaveFile автоматически обнаруживает ошибки при записи, такие как ситуация заполнения раздела, когда write() не может записать все байты. Он запомнит, что произошла ошибка, и удалит временный файл в commit().

Подобно QFile, файл открывается с помощью open(). Данные обычно читаются и записываются с помощью QDataStream или QTextStream, но вы также можете вызвать унаследованные от QIODevice функции read(), readLine(), readAll(), write().

В отличие от QFile, вызов close() запрещён. commit() заменяет его. Если commit() не был вызван, а экземпляр QSaveFile уничтожен, временный файл удаляется.

Чтобы прервать сохранение из-за ошибки приложения, вызовите cancelWriting(), чтобы даже последующий вызов commit() не сохранил файл.

См. также QTextStream, QDataStream, QFileInfo, QDir, QFile и QTemporaryFile.

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

QSaveFile::QSaveFile(const QString &name, QObject *parent)

Создаёт новый объект файла с заданным parent для представления файла с указанным name.

QSaveFile::QSaveFile(QObject *parent = nullptr)

Создаёт новый объект файла с заданным parent.

QSaveFile::QSaveFile(const QString &name)

Создаёт новый объект файла для представления файла с заданным name.

[virtual] QSaveFile::~QSaveFile()

Уничтожает объект файла, удаляя сохранённое содержимое, если commit() не был вызван.

void QSaveFile::cancelWriting()

Отменяет запись нового файла.

Если приложение меняет решение во время сохранения, оно может вызвать cancelWriting(), что устанавливает код ошибки, так что commit() удалит временный файл.

В качестве альтернативы, оно может просто убедиться, что не вызывается commit().

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

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

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

bool QSaveFile::commit()

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

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

Если во время записи произошла ошибка, удаляет временный файл и возвращает false. В противном случае переименовывает его в конечный fileName и возвращает true при успешном завершении. Наконец, закрывает устройство.

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

bool QSaveFile::directWriteFallback() const

Возвращает true если откат записи файлов в каталоги только для чтения включён.

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

[override virtual] QString QSaveFile::fileName() const

Реализует: QFileDevice::fileName() const.

Возвращает имя, заданное setFileName() или конструктором QSaveFile.

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

[override virtual] bool QSaveFile::open(QIODevice::OpenMode mode)

Реализует: QIODevice::open(QIODevice::OpenMode mode).

Открывает файл с помощью режима mode, возвращая true, если успешно; в противном случае false.

Важно: mode должен включать QIODevice::WriteOnly. Он также может иметь дополнительные флаги, такие как QIODevice::Text и QIODevice::Unbuffered.

QIODevice::ReadWrite, QIODevice::Append, QIODevice::NewOnly и QIODevice::ExistingOnly в данный момент не поддерживаются.

См. также QIODevice::OpenMode и setFileName().

void QSaveFile::setDirectWriteFallback(bool enabled)

Позволяет перезаписать существующий файл при необходимости.

QSaveFile создаёт временный файл в том же каталоге, что и конечный файл, и атомарно переименовывает его. Однако это невозможно, если разрешения каталога не позволяют создавать новые файлы. Для сохранения гарантий атомарности open() завершается неудачей, если не может создать временный файл.

Для того чтобы пользователи могли редактировать файлы с разрешениями на запись в каталоге с ограниченными разрешениями, вызовите setDirectWriteFallback() со значением enabled, установленным в true, и последующие вызовы open() будут использовать откат к открытию существующего файла напрямую и записи в него без использования временного файла. Это не гарантирует атомарность, то есть сбой приложения или, например, отключение электропитания могут привести к частично записанному файлу на диске. Это также означает, что cancelWriting() не оказывает никакого влияния в таком случае.

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

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

void QSaveFile::setFileName(const QString &name)

Устанавливает имя файла. Имя может не содержать пути, содержать относительный путь или абсолютный путь.

См. также QFile::setFileName() и fileName().

[override virtual protected] qint64 QSaveFile::writeData(const char *data, qint64 len)

Переопределяет: QFileDevice::writeData(const char *data, qint64 len).