backupWrite 函数 (winbase.h)

  • 项目

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 函数。 除非使用 ACCESS_SYSTEM_SECURITY 访问权限创建了文件句柄，否则不会还原 SCL。 为了确保正确还原完整性 ACE，还必须创建具有 WRITE_OWNER 访问权限的文件句柄。 有关详细信息，请参阅 文件安全性和访问权限。

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

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

[in] lpBuffer

指向函数从中写入数据的缓冲区的指针。

[in] nNumberOfBytesToWrite

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

[out] lpNumberOfBytesWritten

指向接收写入的字节数的变量的指针。

[in] bAbort

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

[in] bProcessSecurity

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

如果 bProcessSecurity 为 TRUE，则需要在打开文件或目录句柄时指定 WRITE_OWNER 并 WRITE_DAC 访问权限。 如果句柄没有这些访问权限，操作系统将拒绝访问 ACL 数据，并且不会进行 ACL 数据还原。

[out] lpContext

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

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

若要释放数据结构使用的内存，请在还原操作完成时调用 bAbort 参数设置为 TRUE 的 BackupWrite。

返回值

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

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

注解

此函数不适用于还原在 加密文件系统下加密的文件。 为此，请使用 WriteEncryptedFileRaw 。

从备份介质中读取的数据必须是由WIN32_STREAM_ID结构分隔 的 子流。

BACKUP_LINK流类型允许使用硬链接还原文件。

要求

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

另请参阅

BackupRead

BackupSeek

CreateFile

WIN32_STREAM_ID

WriteEncryptedFileRaw