BackupRead

Declare Function Api_BackupRead& Lib "kernel32" Alias "BackupRead" (ByVal hFile&, lpBuffer As Byte, ByVal nNumberOfBytesToRead&, lpNumberOfBytesRead&, ByVal bAbort&, ByVal bProcessSecurity&, lpContext As Any)

Declare Function BackupRead Lib "kernel32" (ByVal hFile As Long, lpBuffer As Byte, ByVal nNumberOfBytesToRead As Long, lpNumberOfBytesRead As Long, ByVal bAbort As Long, ByVal bProcessSecurity As Long, lpContext As Any) As Long

指定されたファイルやディレクトリに関連付けられたデータをバッファに読み込む。この関数を使って、ファイルやディレクトリのバックアップをとる。

パラメータ
hFile
    バックアップするファイル、またはディレクトリのハンドルを指定する。関数は、このファイルやディレクトリに関連付けられたデータを読み取る。

    ハンドルを取得するには、CreateFile 関数を使う。
    FILE_FLAG_NO_BUFFERING フラグを指定して、CreateFile 関数を呼び出すと、BackupRead 関数は失敗する。この場合、 関数

    は、ERROR_INVALID_PARAMETER を返す。
lpBuffer
    関数がデータを書き込むバッファへのポインタを指定する。
nNumberOfBytesToRead
    バッファの長さを指定する。 構造体のサイズより大きい値を指定すること。
lpNumberOfBytesRead
    関数が制御を返すときに、読み取ったバイト数を入れる変数へのポインタを指定する。
    関数が 0 以外の値を返し、lpNumberOfBytesRead パラメータが示す変数が 0 の場合は、このファイルハンドルと関連付けられたデータが

    すべて読み取られている。
bAbort
    BackupRead 関数が異常終了していないかどうかを示す。この値が TRUE の場合、操作は異常終了しており、バッファの割り当てがすべ

    て解除される。
bProcessSecurity
    関数が、ファイルまたはディレクトリのアクセス制御リスト（ACL）データを復元するかどうかを指定する。
    TRUE を指定すると、ACL データがバックアップされる。
lpContext
    内部データ構造体へのポインタを受け取って保持する変数へのポインタを指定する。BackupRead 関数は、バックアップ操作中にこの内部

    データ構造体を使ってコンテキスト情報を維持する。
    指定したファイルやディレクトリに対して最初に BackupRead 関数を呼び出す前に、lpContext パラメータで示される変数を NULL に設定す

    る。関数はデータ構造体にメモリを割り当て、変数にこのデータ構造体を示す値を設定する。複数の BackupRead 関数の呼び出しの間

    に、lpContext パラメータ、またはこのパラメータが示す変数を変更しないこと。
    データ構造体が使っているメモリを解放するには、バックアップ操作の完了時に bAbort パラメータを TRUE に設定して、BackupRead 関数

    を呼び出す。

戻り値
    関数が成功すると、0 以外の値が返る。
    関数が失敗すると、0 が返る。

解説
    BackupRead 関数は、開いたオブジェクトに関するデータをすべて個別のバイトストリームとして処理する。各ストリームの前には 32 ビットで

    区切られた WIN32_STREAM_ID 構造体が追加される。
    ストリームは、テープに書き込まれた順序で処理する必要がある。このように順序を統一しておくと、アプリケーションでバックアップデータとコ

    ピー元のデバイスデータを比較することができる。BackupRead 関数から返されたデータは、BackupWrite 関数への入力にだけ使う。この

    データは、サブストリームに分割された 1 つの大きなストリームとして返る。サブストリームは、WIN32_STREAM_ID ヘッダーによって区切

    られている。
    BackupRead 関数がデータを読み取っている間にエラーが発生すると、呼び出し側プロセスが BackupSeek 関数を呼び出してエラーデータを

    スキップする。