Fungsi BackupRead (winbase.h)

Artikel
08/27/2023

Fungsi BackupRead dapat digunakan untuk mencadangkan file atau direktori, termasuk informasi keamanan. Fungsi ini membaca data yang terkait dengan file atau direktori tertentu ke dalam buffer, yang kemudian dapat ditulis ke media cadangan menggunakan fungsi WriteFile .

Sintaks

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

Parameter

[in] hFile

Tangani ke file atau direktori yang akan dicadangkan. Untuk mendapatkan handel, panggil fungsi CreateFile . SACL tidak dibaca kecuali handel file dibuat dengan hak akses ACCESS_SYSTEM_SECURITY . Untuk informasi selengkapnya, lihat Keamanan file dan hak akses.

Handel harus sinkron (tidak tumpang tindih). Ini berarti bahwa bendera FILE_FLAG_OVERLAPPED tidak boleh diatur saat CreateFile dipanggil. Fungsi ini tidak memvalidasi bahwa handel yang diterimanya sinkron, sehingga tidak mengembalikan kode kesalahan untuk handel sinkron, tetapi memanggilnya dengan handel asinkron (tumpang tindih) dapat mengakibatkan kesalahan halus yang sangat sulit untuk di-debug.

Fungsi BackupRead mungkin gagal jika CreateFile dipanggil dengan bendera FILE_FLAG_NO_BUFFERING. Dalam hal ini, fungsi GetLastError mengembalikan nilai ERROR_INVALID_PARAMETER.

[out] lpBuffer

Penunjuk ke buffer yang menerima data.

[in] nNumberOfBytesToRead

Panjang buffer, dalam byte. Ukuran buffer harus lebih besar dari ukuran struktur WIN32_STREAM_ID .

[out] lpNumberOfBytesRead

Penunjuk ke variabel yang menerima jumlah byte yang dibaca.

Jika fungsi mengembalikan nilai bukan nol, dan variabel yang diacu oleh lpNumberOfBytesRead adalah nol, maka semua data yang terkait dengan handel file telah dibaca.

[in] bAbort

Menunjukkan apakah Anda telah selesai menggunakan BackupRead pada handel. Saat Anda mencadangkan file, tentukan parameter ini sebagai FALSE. Setelah selesai menggunakan BackupRead, Anda harus memanggil BackupRead sekali lagi menentukan TRUE untuk parameter ini dan melewati lpContext yang sesuai. lpContext harus diteruskan ketika bAbortTRUE; semua parameter lainnya diabaikan.

[in] bProcessSecurity

Menunjukkan apakah fungsi akan memulihkan data daftar kontrol akses (ACL) untuk file atau direktori.

Jika bProcessSecurityTRUE, data ACL akan dicadangkan.

[out] lpContext

Arahkan ke variabel yang menerima penunjuk ke struktur data internal yang digunakan oleh BackupRead untuk mempertahankan informasi konteks selama operasi pencadangan.

Anda harus mengatur variabel yang diarahkan ke oleh lpContext ke NULL sebelum panggilan pertama ke BackupRead untuk file atau direktori yang ditentukan. Fungsi ini mengalokasikan memori untuk struktur data, lalu mengatur variabel untuk menunjuk ke struktur tersebut. Anda tidak boleh mengubah lpContext atau variabel yang menunjuk ke antara panggilan ke BackupRead.

Untuk merilis memori yang digunakan oleh struktur data, panggil BackupRead dengan parameter bAbort diatur ke TRUE saat operasi pencadangan selesai.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol.

Jika fungsi gagal, nilai yang dikembalikan adalah nol, menunjukkan bahwa terjadi kesalahan I/O. Untuk mendapatkan informasi kesalahan yang diperluas, hubungi GetLastError.

Keterangan

Fungsi ini tidak dimaksudkan untuk digunakan dalam mencadangkan file yang dienkripsi di bawah Sistem File Terenkripsi. Gunakan ReadEncryptedFileRaw untuk tujuan tersebut.

Jika terjadi kesalahan saat BackupRead membaca data, proses panggilan dapat melewati data yang buruk dengan memanggil fungsi BackupSeek .

File atau direktori harus dipulihkan menggunakan fungsi BackupWrite .

Persyaratan


Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll