READ_USN_JOURNAL_DATA_V0

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

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

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

変更ジャーナル内の最初の 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 操作を繰り返す際に 0 以外の BytesToWaitFor 値を指定します。その後、新しいレコードを待機するために 0 を指定します。

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

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

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