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 函数。除非文件句柄是使用 ACCESS_SYSTEM_SECURITY 访问权限创建的，否则不会读取 SCL。有关详细信息，请参阅文件安全性和访问权限。

句柄必须是同步的， (非重叠) 。这意味着在调用 CreateFile 时，不得设置FILE_FLAG_OVERLAPPED标志。此函数不会验证它收到的句柄是否同步，因此它不会返回同步句柄的错误代码，但使用异步 (重叠) 句柄调用它可能会导致非常难以调试的细微错误。

如果使用标志FILE_FLAG_NO_BUFFERING调用 CreateFile，则 BackupRead 函数可能会失败。在这种情况下，GetLastError 函数ERROR_INVALID_PARAMETER返回值。

[out] lpBuffer

指向接收数据的缓冲区的指针。

[in] nNumberOfBytesToRead

缓冲区的长度（以字节为单位）。缓冲区大小必须大于 WIN32_STREAM_ID 结构的大小。

[out] lpNumberOfBytesRead

指向接收读取字节数的变量的指针。

如果函数返回非零值，并且 lpNumberOfBytesRead 指向的变量为零，则表示已读取与文件句柄关联的所有数据。

[in] bAbort

指示是否已完成对句柄使用 BackupRead 。备份文件时，请将此参数指定为 FALSE。使用 BackupRead 后，必须再次调用 BackupRead ，为此参数指定 TRUE 并传递相应的 lpContext。当 bAbort 为 TRUE 时，必须传递 lpContext;将忽略所有其他参数。

[in] bProcessSecurity

指示函数是否还原访问控制列表 (ACL) 文件或目录的数据。

如果 bProcessSecurity 为 TRUE，则会备份 ACL 数据。

[out] lpContext

指向变量的指针，该变量接收 指向 BackupRead 用于在备份操作期间维护上下文信息的内部数据结构的指针。

在为指定的文件或目录首次调用 BackupRead 之前，必须将 lpContext 指向的变量设置为 NULL。函数为数据结构分配内存，然后将变量设置为指向该结构。在调用 BackupRead 之间，不得更改 lpContext 或它指向的变量。

若要释放数据结构使用的内存，请在备份操作完成时调用 BackupRead ，并将 bAbort 参数设置为 TRUE 。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零，表示发生了 I/O 错误。要获得更多的错误信息，请调用 GetLastError。

注解

此函数不适用于备份在加密文件系统下加密的文件。为此，请使用 ReadEncryptedFileRaw 。

如果在 BackupRead 读取数据时出错，调用过程可以通过调用 BackupSeek 函数跳过错误数据。

应使用 BackupWrite 函数还原文件或目录。

要求


最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	winbase.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

另请参阅

BackupRead 函数 (winbase.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

反馈

其他资源