次の方法で共有


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 つのフラグが設定されている必要があります。

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

意味
USN_REASON_BASIC_INFO_CHANGE
0x00008000
ユーザーが 1 つ以上のファイル属性またはディレクトリ属性 (読み取り専用、非表示、システム、アーカイブ、スパース属性など)、または 1 つ以上のタイム スタンプを変更しました。
USN_REASON_CLOSE
0x80000000
ファイルまたはディレクトリが閉じられています。
USN_REASON_COMPRESSION_CHANGE
0x00020000
ファイルまたはディレクトリの圧縮状態は、 または から圧縮に変更されます。
USN_REASON_DATA_EXTEND
0x00000002
ファイルまたはディレクトリが に追加されます。
USN_REASON_DATA_OVERWRITE
0x00000001
ファイルまたはディレクトリ内のデータが上書きされます。
USN_REASON_DATA_TRUNCATION
0x00000004
ファイルまたはディレクトリが切り捨てられます。
USN_REASON_EA_CHANGE
0x00000400
ユーザーは、ファイルまたはディレクトリ拡張属性を変更します。 これらの NTFS ファイル システム属性は、Windows ベースのアプリケーションではアクセスできません。
USN_REASON_ENCRYPTION_CHANGE
0x00040000
ファイルまたはディレクトリは暗号化または暗号化解除されます。
USN_REASON_FILE_CREATE
0x00000100
ファイルまたはディレクトリは初めて作成されます。
USN_REASON_FILE_DELETE
0x00000200
ファイルまたはディレクトリが削除されます。
USN_REASON_HARD_LINK_CHANGE
0x00010000
NTFS ファイル システムのハード リンクは、ファイルまたはディレクトリに追加されるか、ファイルまたはディレクトリから削除されます。 POSIX ハード リンクと同様に、NTFS ファイル システムのハード リンクは、同じファイルまたはディレクトリを参照する複数のディレクトリ エントリの 1 つです。
USN_REASON_INDEXABLE_CHANGE
0x00004000
ユーザーが FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 属性を変更しました。 つまり、ユーザーは、コンテンツインデックスを作成できるファイルまたはディレクトリから、インデックスを作成できないファイルまたはディレクトリに変更しました。その逆も可能です。 (コンテンツ インデックス作成を使用すると、選択したコンテンツのデータベースを作成して、データを迅速に検索できます。
USN_REASON_NAMED_DATA_EXTEND
0x00000020
ファイルの名前付きデータ ストリームが 1 つ以上追加されました。
USN_REASON_NAMED_DATA_OVERWRITE
0x00000010
ファイルの 1 つ以上の名前付きデータ ストリーム内のデータが上書きされます。
USN_REASON_NAMED_DATA_TRUNCATION
0x00000040
ファイルの 1 つ以上の名前付きデータ ストリームが切り捨てられます。
USN_REASON_OBJECT_ID_CHANGE
0x00080000
ファイルまたはディレクトリのオブジェクト識別子が変更されます。
USN_REASON_RENAME_NEW_NAME
0x00002000
ファイルまたはディレクトリーの名前が変更され、このジャーナル・レコードを保持 するUSN_RECORD_V2 または USN_RECORD_V3 構造内のファイル名が新しい名前になります。
USN_REASON_RENAME_OLD_NAME
0x00001000
ファイルまたはディレクトリーの名前が変更され、このジャーナル・レコードを保持 するUSN_RECORD_V2 または USN_RECORD_V3 構造内のファイル名が前の名前になります。
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
ファイルまたはディレクトリに含まれる再解析ポイントが変更されるか、ファイルまたはディレクトリに再解析ポイントが追加または削除されます。
USN_REASON_SECURITY_CHANGE
0x00000800
ファイルまたはディレクトリへのアクセス許可に変更が加えられます。
USN_REASON_STREAM_CHANGE
0x00200000
名前付きストリームがファイルまたはディレクトリに追加または削除されるか、名前付きストリームの名前が変更されます。

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_JOURNALTimeout 秒を待機し、指定されたレコードを返そうとします。 タイムアウト秒数が経過すると、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操作呼び出しで DeviceIoControllpBytesReturned パラメーターを使用して、使用可能なデータの量を確認し、出力バッファーを再割り当てして (新しいレコードに余裕を持って)、DeviceIoControl をもう一度呼び出します。

UsnJournalID

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

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

要件

   
サポートされている最小のクライアント Windows XP [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ]
ヘッダー winioctl.h (Windows.h を含む)

こちらもご覧ください

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD