Fungsi BackupWrite (winbase.h)

Artikel
03/08/2023

Fungsi BackupWrite dapat digunakan untuk memulihkan file atau direktori yang dicadangkan menggunakan BackupRead. Gunakan fungsi ReadFile untuk mendapatkan aliran data dari media cadangan, lalu gunakan BackupWrite untuk menulis data ke file atau direktori yang ditentukan.

Sintaks

BOOL BackupWrite(
  [in]  HANDLE  hFile,
  [in]  LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToWrite,
  [out] LPDWORD lpNumberOfBytesWritten,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Parameter

[in] hFile

Tangani ke file atau direktori yang akan dipulihkan. Untuk mendapatkan handel, panggil fungsi CreateFile . SACL tidak dipulihkan kecuali handel file dibuat dengan hak akses ACCESS_SYSTEM_SECURITY . Untuk memastikan bahwa ACE integritas dipulihkan dengan benar, handel file juga harus dibuat dengan hak akses WRITE_OWNER . 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 BackupWrite mungkin gagal jika CreateFile dipanggil dengan bendera FILE_FLAG_NO_BUFFERING. Dalam hal ini, fungsi GetLastError mengembalikan nilai ERROR_INVALID_PARAMETER.

[in] lpBuffer

Penunjuk ke buffer tempat fungsi menulis data.

[in] nNumberOfBytesToWrite

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

[out] lpNumberOfBytesWritten

Penunjuk ke variabel yang menerima jumlah byte yang ditulis.

[in] bAbort

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

[in] bProcessSecurity

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

Jika bProcessSecurityTRUE, Anda perlu menentukan akses WRITE_OWNER dan WRITE_DAC saat membuka handel file atau direktori. Jika handel tidak memiliki hak akses tersebut, sistem operasi menolak akses ke data ACL, dan pemulihan data ACL tidak akan terjadi.

[out] lpContext

Penunjuk ke variabel yang menerima penunjuk ke struktur data internal yang digunakan oleh BackupWrite untuk mempertahankan informasi konteks selama operasi pemulihan.

Anda harus mengatur variabel yang diarahkan ke oleh lpContext ke NULL sebelum panggilan pertama ke BackupWrite 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 BackupWrite.

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

Nilai kembali

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 memulihkan file yang dienkripsi di bawah Sistem File Terenkripsi. Gunakan WriteEncryptedFileRaw untuk tujuan tersebut.

Data yang dibaca dari media cadangan harus berupa sub-aliran yang dipisahkan oleh struktur WIN32_STREAM_ID .

Jenis aliran BACKUP_LINK memungkinkan Anda memulihkan file dengan tautan keras.

Persyaratan

Persyaratan	Nilai
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