BackupRead 函式 (winbase.h)

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

如果使用旗標呼叫CreateFile FILE_FLAG_NO_BUFFERING，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 用來在備份作業期間維護內容資訊的內部資料結構的指標。

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

若要釋放資料結構所使用的記憶體，請在備份作業完成時呼叫bAbort參數設為TRUE的BackupRead。

傳回值

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

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

備註

此函式不適用於備份以加密檔案系統加密的檔案。 針對該目的，請使用 ReadEncryptedFileRaw 。

如果 BackupRead 正在讀取資料時發生錯誤，呼叫進程可以呼叫 BackupSeek 函式來略過不正確的資料。

應該使用 BackupWrite 函式來還原檔案或目錄。

規格需求

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

另請參閱

BackupSeek

BackupWrite

建立備份應用程式

ReadEncryptedFileRaw

WIN32_STREAM_ID