BackupRead

セキュリティ情報を含むファイルまたはディレクトリをバックアップする。

BackupRead hFile, lpBuffer, nNumberOfBytesToRead, lpNumberOfBytesRead, bAbort, bProcessSecurity, lpContext

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

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

解説

セキュリティ情報を含むファイルまたはディレクトリをバックアップする。

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

[備考]
この関数は Encrypted File System で暗号化されたファイルのバックアップには使用しない。その用途には
ReadEncryptedFileRaw を使う。BackupRead がデータを読んでいる間にエラーが発生した場合、呼び出し側プロセスは
BackupSeek 関数を呼んで不良データをスキップできる。ファイルまたはディレクトリは BackupWrite
関数を使ってリストアする。

情報