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

Статья
08/27/2023

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

Синтаксис

BOOL BackupRead(
  [in]  HANDLE  hFile,
  [out] LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToRead,
  [out] LPDWORD lpNumberOfBytesRead,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Параметры

[in] hFile

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

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

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

[out] lpBuffer

Указатель на буфер, который получает данные.

[in] nNumberOfBytesToRead

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

[out] lpNumberOfBytesRead

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

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

[in] bAbort

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

[in] bProcessSecurity

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

Если параметр bProcessSecurity имеет значение TRUE, будет создана резервная копия данных ACL.

[out] lpContext

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

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

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

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

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

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

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

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

Файл или каталог должны быть восстановлены с помощью функции BackupWrite .

Требования


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

См. также

BackupSeek

BackupWrite

Создание приложения резервного копирования

ReadEncryptedFileRaw

WIN32_STREAM_ID