READ_USN_JOURNAL_DATA_V1

変更ジャーナルの読み取りを開始する USN です。

ジャーナルの最初のレコードから読み取り操作を開始するには、StartUsn メンバーに 0 を設定します。すべてのジャーナル レコードには USN が含まれているため、実際にどのレコードから読み取り操作が開始されたかは出力バッファーで確認できます。

特定のレコードから読み取り操作を開始するには、そのレコードの USN を StartUsn に設定します。

変更ジャーナル内の最初の USN よりも小さい 0 以外の USN を指定した場合はエラーが発生し、ERROR_JOURNAL_ENTRY_DELETED エラー コードが返されます。このコードは、指定された USN がかつては有効であったものの、その後削除された場合を示していることがあります。

READ_USN_JOURNAL_DATA_V0 で返される変更ジャーナル バッファーの走査について詳しくは、Walking a Buffer of Change Journal Records を参照してください。

フラグのマスクです。各フラグは、ファイルまたはディレクトリに対する変更ジャーナル レコードが存在する変更内容を示します。FSCTL_READ_USN_JOURNAL 操作で返されるためには、変更ジャーナル レコードにこれらのフラグの少なくとも 1 つが設定されている必要があります。

有効なフラグは次のとおりです。未使用のビットは予約済みです。

変更ジャーナル レコードをいつ返すかを指定する値です。

変更が発生した時点ではなく、変更されたファイルまたはディレクトリの最後のハンドルが閉じられた時点で通知を受け取るには、ReturnOnlyOnClose に 0 以外の任意の値を設定し、ReasonMask メンバーに USN_REASON_CLOSE フラグを指定します。

ReasonMask のフラグが示すすべての変更は、最終的にファイルが閉じられた時点で変更ジャーナル ソフトウェアの呼び出しを生成します。DeviceIoControl の呼び出しがファイルが閉じられるのを待機している場合、その呼び出しによって DeviceIoControl の呼び出しが戻れるようになります。ボリュームの障害、オペレーティング システムの障害、またはシャットダウンの前にファイルまたはディレクトリが閉じられなかった場合は、次にそのボリュームがマウントされたときに変更ジャーナル ソフトウェアへのクリーンアップ呼び出しが発生します。この呼び出しは、途中でシステムが再起動された場合でも発生します。

各変更が最初にログに記録された時点とクリーンアップ時の両方で通知を受け取るには、ReturnOnlyOnClose に 0 を設定します。

ReturnOnlyOnClose が 0 であるか 0 以外であるかにかかわらず、クリーンアップ時に生成されるレコードには、そのファイルまたはディレクトリに発生した USN 変更のすべての理由が変更ジャーナル内に記録されます。項目に対する最後のクローズ操作が行われるたびに、USN クローズ レコードが変更ジャーナルに書き込まれ、その項目の ReasonMask フラグはすべてリセットされます。

ユーザー データが存在しないファイルまたはディレクトリ (マウントされたフォルダーなど) の場合、最後のクローズ操作は、その項目に対する最後のユーザー ハンドルに対して CloseHandle 関数が呼び出されたときに発生します。

BytesToWaitFor メンバーと組み合わせて使用するタイムアウト値 (秒単位) で、FSCTL_READ_USN_JOURNAL 操作が変更ジャーナルに存在する以上のデータを要求した場合の動作をオペレーティング システムに指示します。

Timeout が 0 で BytesToWaitFor が 0 以外の場合に、FSCTL_READ_USN_JOURNAL 操作の呼び出しが返すべきデータを見つけられないまま変更ジャーナルの末尾に達すると、FSCTL_READ_USN_JOURNAL はフィルター処理されていないデータが BytesToWaitFor バイト分だけ変更ジャーナルに追加されるまで待機してから、指定されたレコードを取得します。

Timeout が 0 以外で BytesToWaitFor も 0 以外の場合に、FSCTL_READ_USN_JOURNAL 操作の呼び出しが返すべきデータを見つけられないまま変更ジャーナルの末尾に達すると、FSCTL_READ_USN_JOURNAL は Timeout 秒間待機してから、指定されたレコードを返そうとします。Timeout 秒の経過後、FSCTL_READ_USN_JOURNAL は指定された範囲内で利用可能なレコードを取得します。

いずれの場合も、タイムアウト期間の経過後に変更ジャーナルへ新たに追加されたデータが処理されます。指定されたセットから返すレコードがまだ存在しない場合は、タイムアウト期間が繰り返されます。このモードでは、FSCTL_READ_USN_JOURNAL は、少なくとも 1 つのレコードが返されるか、I/O がキャンセルされるまで未完了のままになります。

BytesToWaitFor が 0 の場合、Timeout は無視されます。また、非同期で開かれたハンドルに対しても Timeout は無視されます。

変更ジャーナルに追加された、フィルター処理されていないデータのバイト数です。この値を Timeout と組み合わせて使用し、FSCTL_READ_USN_JOURNAL 操作が変更ジャーナルに存在する以上のデータを要求した場合の動作をオペレーティング システムに指示します。

BytesToWaitFor が 0 の場合、Timeout は無視されます。この場合、FSCTL_READ_USN_JOURNAL 操作は、変更ジャーナル ファイルの末尾に達したときに常に正常に戻ります。また、次の FSCTL_READ_USN_JOURNAL 操作で使用すべき USN も取得します。返された次の USN が指定した StartUsn と同じ場合、利用可能なレコードはありません。呼び出し元プロセスは、すぐに FSCTL_READ_USN_JOURNAL を再度使用すべきではありません。

BytesToWaitFor が 0 の場合は返されるデータ量を予測できないため、出力バッファーがオーバーフローするおそれがあります。このリスクを減らすには、変更ジャーナル内のすべてのレコードを取り尽くすまで、FSCTL_READ_USN_JOURNAL 操作を繰り返す際に BytesToWaitFor に 0 以外の値を指定します。その後、新しいレコードを待機するために 0 を指定します。

あるいは、FSCTL_READ_USN_JOURNAL 操作の呼び出しにおける DeviceIoControl の lpBytesReturned パラメーターを使用して利用可能なデータ量を判断し、(新しいレコード用の余裕を持たせて) 出力バッファーを再割り当てしてから、DeviceIoControl を再度呼び出します。

そのボリュームで現在有効なジャーナル インスタンスの識別子です。

変更ジャーナルが停止して再開された場合や、削除されて再作成された場合、NTFS ファイル システムは変更ジャーナルへのイベントの記録を取りこぼすことがあります。これらのいずれかが発生すると、NTFS ファイル システムはジャーナルに新しい識別子を割り当てます。ジャーナル識別子が現在のジャーナル識別子と一致しない場合、DeviceIoControl の呼び出しは失敗し、適切なエラー コードを返します。新しいジャーナル識別子を取得するには、FSCTL_QUERY_USN_JOURNAL 操作を指定して DeviceIoControl を呼び出します。