READ_USN_JOURNAL_DATA_V0 構造体 (winioctl.h)

呼び出し元プロセスに戻る更新シーケンス番号 (USN) 変更ジャーナル・レコードのセットを定義する情報が含まれます。 これは、 FSCTL_QUERY_USN_JOURNAL および FSCTL_READ_USN_JOURNAL コントロール コードによって使用されます。 この構造体は、Windows 8およびWindows Server 2012より前は、READ_USN_JOURNAL_DATAという名前でした。 古い SDK とコンパイラでコンパイルするには、その名前を使用します。 Windows Server 2012、ReFS で使用される 128 ビットのファイル識別子をサポートするREAD_USN_JOURNAL_DATA_V1が導入されました。

構文

typedef struct {
  USN       StartUsn;
  DWORD     ReasonMask;
  DWORD     ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;

メンバー

StartUsn

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

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

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

変更ジャーナルの最初の USN より小さい 0 以外の USN が指定されている場合は、エラーが発生し、 ERROR_JOURNAL_ENTRY_DELETED エラー コードが返されます。 このコードは、指定された USN が一度に有効であるが、その後削除されたケースを示している可能性があります。

READ_USN_JOURNAL_DATA_V0で返される変更ジャーナル バッファー内を移動する方法の詳細については、「変更履歴レコードのバッファーの移動」を参照してください。

ReasonMask

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

有効なフラグの一覧は次のとおりです。 未使用のビットは予約されています。

ReturnOnlyOnClose

変更履歴レコードを返すタイミングを示す 値です。

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

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

各変更が初めてログに記録されるだけでなく、クリーンアップ時にも通知を受け取る場合は、 ReturnOnlyOnClose を 0 に設定します。

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

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

Timeout

FSCTL_READ_USN_JOURNAL操作が変更ジャーナルに存在するデータよりも多くのデータを要求した場合の対処方法をオペレーティング システムに指示するために BytesToWaitFor メンバーと共に使用されるタイムアウト値 (秒単位)。

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 秒を待機し、指定されたレコードを返そうとします。 タイムアウト秒数が経過すると、FSCTL_READ_USN_JOURNALは、指定された範囲内で使用可能なすべてのレコードを取得します。

いずれの場合も、タイムアウト期間の後に、変更履歴に追加された新しいデータが処理されます。 指定したセットから返すレコードがまだない場合は、タイムアウト期間が繰り返されます。 このモードでは、 少 なくとも 1 つのレコードが返されるか、I/O が取り消されるまで、FSCTL_READ_USN_JOURNALは未処理のままになります。

BytesToWaitFor が 0 の場合、Timeout は無視されます。 非同期に開かれたハンドルの場合も、タイムアウトは無視されます。

BytesToWaitFor

変更ジャーナルに追加されたフィルター処理されていないデータのバイト数。 この値を 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 をもう一度呼び出します。

UsnJournalID

ボリュームの現在のジャーナルのインスタンスの識別子。

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

要件

こちらもご覧ください

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD