BackupWrite

BackupRead でバックアップされたファイルまたはディレクトリをリストアする。

BackupWrite hFile, lpBuffer, nNumberOfBytesToWrite, lpNumberOfBytesWritten, bAbort, bProcessSecurity, lpContext

hFile : [intptr] リストア対象のファイルまたはディレクトリへのハンドル。ハンドルを取得するには CreateFile 関数を呼ぶ。ファイルハンドルが ACCESS_SYSTEM_SECURITY アクセス権付きで作成されていない限り、SACL はリストアされない。整合性 ACE が正しくリストアされるようにするには、ファイルハンドルは WRITE_OWNER アクセス権付きでも作成されている必要がある。詳細は [File security and access rights](/windows/win32/fileio/file-security-and-access-rights) を参照。ハンドルは同期（非オーバーラップ）でなければならない。つまり、CreateFile 呼び出し時に FILE_FLAG_OVERLAPPED フラグを設定してはならない。この関数は受け取ったハンドルが同期か検証しないため、同期ハンドルに対してはエラーコードを返さないが、非同期（オーバーラップ）ハンドルで呼ぶとデバッグが非常に難しい微妙なエラーを引き起こす可能性がある。CreateFile が FILE_FLAG_NO_BUFFERING フラグ付きで呼ばれた場合、BackupWrite 関数は失敗することがある。この場合、GetLastError は ERROR_INVALID_PARAMETER を返す。
lpBuffer : [var] 関数がデータを書き込む元のバッファへのポインタ。
nNumberOfBytesToWrite : [int] バッファのサイズ（バイト単位）。バッファサイズは WIN32_STREAM_ID 構造体のサイズより大きくなければならない。
lpNumberOfBytesWritten : [var] 書き込まれたバイト数を受け取る変数へのポインタ。
bAbort : [int] ハンドルに対する BackupWrite の使用を終えたかどうかを示す。ファイルをリストアしている間はこのパラメータを FALSE で指定する。BackupWrite の使用を終えた後、もう一度 BackupWrite をこのパラメータを TRUE にして適切な lpContext を渡して呼び出す必要がある。bAbort が TRUE のときは lpContext を渡さねばならず、それ以外のパラメータは無視される。
bProcessSecurity : [int] 関数がファイルまたはディレクトリのアクセス制御リスト (ACL) データをリストアするかどうかを指定する。bProcessSecurity が TRUE の場合、ファイルまたはディレクトリのハンドルを開くときに WRITE_OWNER と WRITE_DAC アクセスを指定する必要がある。ハンドルがこれらのアクセス権を持たない場合、OS は ACL データへのアクセスを拒否し、ACL データのリストアは行われない。
lpContext : [var] リストア処理中に BackupWrite がコンテキスト情報を保持するために使う内部データ構造へのポインタを受け取る変数へのポインタ。指定ファイルまたはディレクトリに対する BackupWrite の初回呼び出し前に lpContext が指す変数を NULL に設定しなければならない。関数がデータ構造用のメモリを割り当て、変数をその構造体へのポインタに設定する。BackupWrite の呼び出し間で lpContext または lpContext が指す変数を変更してはならない。データ構造が使用するメモリを解放するには、リストア処理完了後に bAbort を TRUE にして BackupWrite を呼ぶ。

(プラグイン / モジュール : kernel32.dll)

解説

BackupRead でバックアップされたファイルまたはディレクトリをリストアする。

[戻り値]
関数が成功した場合、戻り値はゼロ以外。関数が失敗した場合、戻り値はゼロで、I/O エラーが発生したことを示す。拡張エラー情報を取得するには
GetLastError を呼ぶ。

[備考]
この関数は Encrypted File System で暗号化されたファイルのリストアには使用しない。その用途には
WriteEncryptedFileRaw を使う。バックアップメディアから読まれたデータは、WIN32_STREAM_ID
構造体で区切られたサブストリームである必要がある。BACKUP_LINK
ストリームタイプを使うと、ハードリンク付きのファイルをリストアできる。

情報