BackupRead 関数 (winbase.h)

BackupRead 関数を使用して、セキュリティ情報を含むファイルまたはディレクトリをバックアップできます。 関数は、指定したファイルまたはディレクトリに関連付けられているデータをバッファーに読み取り、 WriteFile 関数を使用してバックアップ メディアに書き込むことができます。

構文

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

パラメーター

[in] hFile

バックアップするファイルまたはディレクトリを処理します。 ハンドルを取得するには、 CreateFile 関数を呼び出します。 ファイル ハンドルが ACCESS_SYSTEM_SECURITY アクセス権で作成されていない限り、SACL は読み取られません。 詳細については、「 ファイルのセキュリティとアクセス権」を参照してください。

ハンドルは同期 (オーバーラップなし) である必要があります。 つまり、CreateFile の呼び出し時にFILE_FLAG_OVERLAPPED フラグを設定しないでください。 この関数は、受け取ったハンドルが同期であることを検証しないため、同期ハンドルのエラー コードは返されませんが、非同期 (重複) ハンドルで呼び出すと、デバッグが非常に困難な微妙なエラーが発生する可能性があります。

CreateFile がフラグ FILE_FLAG_NO_BUFFERINGで呼び出された場合、BackupRead 関数が失敗する可能性があります。 この場合、 GetLastError 関数は ERROR_INVALID_PARAMETER値を返します。

[out] lpBuffer

データを受信するバッファーへのポインター。

[in] nNumberOfBytesToRead

バッファーの長さ (バイト単位)。 バッファー サイズは、 WIN32_STREAM_ID 構造体のサイズより大きくする必要があります。

[out] lpNumberOfBytesRead

読み取られたバイト数を受け取る変数へのポインター。

関数が 0 以外の値を返し、 lpNumberOfBytesRead が指す変数が 0 の場合、ファイル ハンドルに関連付けられているすべてのデータが読み取られます。

[in] bAbort

ハンドルで BackupRead の使用を完了したかどうかを示します。 ファイルのバックアップ中に、このパラメーターを FALSE として指定 します。 BackupRead の使用が完了したら、このパラメーターに TRUE を指定し、適切な lpContext を渡して BackupRead をもう一度呼び出す必要があります。 bAbort が TRUE の場合は lpContext を渡す必要があります。その他のパラメーターはすべて無視されます。

[in] bProcessSecurity

関数がファイルまたはディレクトリのアクセス制御リスト (ACL) データを復元するかどうかを示します。

bProcessSecurity が TRUE の場合、ACL データがバックアップされます。

[out] lpContext

バックアップ操作中にコンテキスト情報を維持するために BackupRead によって使用される内部データ構造へのポインターを受け取る変数へのポインター。

指定したファイルまたはディレクトリに対して BackupRead を最初に呼び出す前に、lpContext が指す変数を NULL に設定する必要があります。 関数はデータ構造にメモリを割り当て、その構造体を指す変数を設定します。 BackupRead の呼び出しの間に lpContext またはそれが指す変数を変更することはできません。

データ構造で使用されるメモリを解放するには、バックアップ操作が完了したときに bAbort パラメーターを TRUE に設定して BackupRead を呼び出します。

戻り値

関数が成功すると、戻り値は 0 以外になります。

関数が失敗した場合、戻り値は 0 で、I/O エラーが発生したことを示します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

この関数は、暗号化されたファイル システムで暗号化されたファイルをバックアップする際に使用するためのものではありません。 その目的 で ReadEncryptedFileRaw を使用します。

BackupRead がデータを読み取っている間にエラーが発生した場合、呼び出し元のプロセスは BackupSeek 関数を呼び出すことによって、不適切なデータをスキップできます。

BackupWrite 関数を使用して、ファイルまたはディレクトリを復元する必要があります。

要件

関連項目

BackupSeek

BackupWrite

バックアップ アプリケーションの作成

ReadEncryptedFileRaw

WIN32_STREAM_ID