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旗標。 此函式不會驗證收到的句柄是否為同步處理，因此不會傳回同步句柄的錯誤碼，但以異步 (重疊) 句柄呼叫它，可能會導致非常難以偵錯的細微錯誤。

如果使用旗標呼叫CreateFileFILE_FLAG_NO_BUFFERING，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 用來在還原作業期間維護內容資訊的內部數據結構的指標。

您必須先將 lpContext 指向的變數設定為 NULL ，才能針對指定的檔案或目錄第一次呼叫 BackupWrite 。 函式會配置數據結構的記憶體，然後將變數設定為指向該結構。 您不得變更 lpContext 或它指向 BackupWrite 呼叫之間的變數。

若要釋放數據結構所使用的記憶體，請在還原作業完成時呼叫 bAbort 參數設為 TRUE 的 BackupWrite。

傳回值

如果函式成功，則傳回非零的值。

如果函式失敗，傳回值為零，表示發生 I/O 錯誤。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

此函式不適用於還原加密檔案系統下加密 的檔案。 針對該目的，請使用 WriteEncryptedFileRaw 。

從備份媒體讀取的數據必須是 以WIN32_STREAM_ID 結構分隔的子數據流。

BACKUP_LINK數據流類型可讓您還原具有硬式連結的檔案。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll

另請參閱

BackupRead

BackupSeek

CreateFile

WIN32_STREAM_ID

WriteEncryptedFileRaw