Функция BackupWrite (winbase.h)

Статья
08/27/2023

Функцию BackupWrite можно использовать для восстановления файла или каталога, резервное копирование в который было выполнено с помощью BackupRead. Используйте функцию ReadFile , чтобы получить поток данных из среды резервного копирования, а затем используйте BackupWrite для записи данных в указанный файл или каталог.

Синтаксис

BOOL BackupWrite(
  [in]  HANDLE  hFile,
  [in]  LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToWrite,
  [out] LPDWORD lpNumberOfBytesWritten,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Параметры

[in] hFile

Дескриптор в восстанавливаемом файле или каталоге. Чтобы получить дескриптор, вызовите функцию CreateFile . Списки SACCL не восстанавливаются, если дескриптор файла не был создан с правом доступа ACCESS_SYSTEM_SECURITY . Чтобы обеспечить правильное восстановление ACE целостности, необходимо также создать дескриптор файла с правом доступа WRITE_OWNER . Дополнительные сведения см. в разделе Безопасность файлов и права доступа.

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

Функция BackupWrite может завершиться ошибкой, если метод CreateFile был вызван с флагом FILE_FLAG_NO_BUFFERING. В этом случае функция GetLastError возвращает значение ERROR_INVALID_PARAMETER.

[in] lpBuffer

Указатель на буфер, из который функция записывает данные.

[in] nNumberOfBytesToWrite

Размер буфера в байтах. Размер буфера должен быть больше размера WIN32_STREAM_ID структуры.

[out] lpNumberOfBytesWritten

Указатель на переменную, получающую число записанных байтов.

[in] bAbort

Указывает, завершено ли использование BackupWrite для дескриптора. При восстановлении файла укажите для этого параметра значение FALSE. После завершения работы с BackupWrite необходимо еще раз вызвать BackupWrite , указав значение TRUE для этого параметра и передав соответствующий lpContext. lpContext должен передаваться, если bAbort имеет значение TRUE; все остальные параметры игнорируются.

[in] bProcessSecurity

Указывает, будет ли функция восстанавливать данные списка управления доступом (ACL) для файла или каталога.

Если параметр bProcessSecurity имеет значение TRUE, необходимо указать WRITE_OWNER и WRITE_DAC доступа при открытии файла или дескриптора каталога. Если дескриптор не имеет этих прав доступа, операционная система запрещает доступ к данным ACL, и восстановление данных ACL не выполняется.

[out] lpContext

Указатель на переменную, которая получает указатель на внутреннюю структуру данных, используемую BackupWrite для хранения контекстных сведений во время операции восстановления.

Перед первым вызовом BackupWrite для указанного файла или каталога переменной, на которую указывает lpContext, необходимо задать значение NULL. Функция выделяет память для структуры данных, а затем задает переменную, указывающую на нее. Не следует изменять lpContext или переменную, на которую он указывает между вызовами BackupWrite.

Чтобы освободить память, используемую структурой данных, вызовите BackupWrite с параметром bAbort , равным TRUE , после завершения операции восстановления.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция завершается сбоем, возвращаемое значение равно нулю, что указывает на ошибку ввода-вывода. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

WriteEncryptedFileRaw