USN_RECORD_V4 構造体 (winioctl.h)

[アーティクル]
03/08/2023

更新シーケンス番号 (USN) 変更ジャーナルバージョン 4.0 レコードの情報を格納します。バージョン 2.0 と 3.0 のレコードはそれぞれ、USN_RECORD_V2 (USN_RECORD とも呼ばれる) と USN_RECORD_V3 構造体によって定義されます。

構文

typedef struct {
  USN_RECORD_COMMON_HEADER Header;
  FILE_ID_128              FileReferenceNumber;
  FILE_ID_128              ParentFileReferenceNumber;
  USN                      Usn;
  DWORD                    Reason;
  DWORD                    SourceInfo;
  DWORD                    RemainingExtents;
  WORD                     NumberOfExtents;
  WORD                     ExtentSize;
  USN_RECORD_EXTENT        Extents[1];
} USN_RECORD_V4, *PUSN_RECORD_V4;

メンバー

Header

レコードの長さ、メジャーバージョン、マイナーバージョンを記述する USN_RECORD_COMMON_HEADER 構造体。

FileReferenceNumber

このレコードが変更を記録するファイルまたはディレクトリの 128 ビットの序数。

この値は、ジャーナルレコードをファイルに関連付ける任意に割り当てられた値です。

ParentFileReferenceNumber

このレコードに関連付けられているファイルまたはディレクトリが配置されているディレクトリの 128 ビットの序数。

この値は、ジャーナルレコードを親ディレクトリに関連付ける任意に割り当てられた値です。

Usn

このレコードの USN。

Reason

ファイルまたはディレクトリーがオープンされてから、このファイルまたはディレクトリー・ジャーナル・レコードに累積された変更の理由を識別するフラグ。

ファイルまたはディレクトリが閉じると、 USN_REASON_CLOSE フラグが設定された最終的な USN レコードが生成されます。次の変更 (たとえば、次のオープン操作または削除後) は、新しい理由フラグのセットを含む新しいレコードを開始します。

名前の変更または移動操作では、2 つの USN レコードが生成されます。1 つはアイテムの古い親ディレクトリを記録し、もう 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_INTEGRITY_CHANGE 0x00800000	ユーザーが、指定されたストリームの FILE_ATTRIBUTE_INTEGRITY_STREAM 属性の状態を変更しました。 ReFS ファイルシステムでは、整合性ストリームはそのストリームのすべてのデータのチェックサムを保持するため、読み取り操作または書き込み操作中にファイルの内容を検証できます。
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_V4 構造体のファイル名が新しい名前になります。
USN_REASON_RENAME_OLD_NAME 0x00001000	ファイルまたはディレクトリの名前が変更され、 USN_RECORD_V4 構造体のファイル名が前の名前になります。
USN_REASON_REPARSE_POINT_CHANGE 0x00100000	ファイルまたはディレクトリに含まれる再解析ポイントが変更されるか、再解析ポイントがファイルまたはディレクトリに追加または削除されます。
USN_REASON_SECURITY_CHANGE 0x00000800	ファイルまたはディレクトリへのアクセス権に変更が加えられます。
USN_REASON_STREAM_CHANGE 0x00200000	名前付きストリームがファイルに追加または削除されるか、名前付きストリームの名前が変更されます。
USN_REASON_TRANSACTED_CHANGE 0x00400000	指定されたストリームは、コミットされた TxF トランザクションによって変更されます。

SourceInfo

変更のソースに関する追加情報。DeviceIoControl 操作のFSCTL_MARK_HANDLEによって設定されます。

スレッドが新しい USN レコードを書き込むとき、前のレコードのソース情報フラグは、スレッドもそれらのフラグを設定した場合にのみ存在し続けます。したがって、ソース情報構造を使用すると、アプリケーションは、既知のソース (ウイルス対策フィルターなど) によってのみ設定された USN レコードを除外できます。

次のいずれかの値を設定できます。

値	意味
USN_SOURCE_AUXILIARY_DATA 0x00000002	この操作により、プライベートデータストリームがファイルまたはディレクトリに追加されます。 1 つの例として、チェックサム情報を追加するウイルス検出機能があります。ウイルス検出機能が項目を変更すると、システムによって USN レコードが生成されます。 USN_SOURCE_AUXILIARY_DATA は、変更によってアプリケーションデータが変更されなかったことを示します。
USN_SOURCE_DATA_MANAGEMENT 0x00000001	この操作は、オペレーティングシステムによって行われたファイルまたはディレクトリの変更に関する情報を提供します。一般的な用途は、リモートストレージシステムが外部ストレージからローカルストレージにデータを移動する場合です。リモートストレージは、階層型ストレージ管理ソフトウェアです。通常、このような移動では、USN レコードに USN_REASON_DATA_OVERWRITE フラグが追加されます。ただし、データはユーザーの観点から変更されていません。 SourceInfo メンバーにUSN_SOURCE_DATA_MANAGEMENTを書き込むことで、アイテムに対して書き込み操作が実行されますが、データは変更されていないことを確認できます。
USN_SOURCE_REPLICATION_MANAGEMENT 0x00000004	この操作では、レプリカセットの別のメンバーに存在する同じファイルの内容と一致するようにファイルを変更しています。
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT 0x00000008	この操作では、クラウドに存在するのと同じファイルの内容と一致するように、クライアントシステム上のファイルを変更しています。

RemainingExtents

現在のUSN_RECORD_V4 レコードの後に残るエクステントの数。特定のファイルのすべての変更されたエクステントを記述するには、複数のバージョン 4.0 レコードが必要になる場合があります。 RemainingExtents メンバーが 0 の場合、現在のUSN_RECORD_V4 レコードはファイルの最後のUSN_RECORD_V4 レコードです。特定 のファイルの最後のUSN_RECORD_V4 エントリの後に、少なくとも USN_REASON_CLOSE フラグが設定された USN_RECORD_V3 レコードが常に続きます。

NumberOfExtents

現在の USN_RECORD_V4 エントリ内のエクステントの数。

ExtentSize

Extents メンバー内の各USN_RECORD_EXTENT構造体のサイズ (バイト単位)。

Extents[1]

USN_RECORD_V4エントリ内のエクステントを表すUSN_RECORD_EXTENT構造体の配列。

注釈

USN_RECORD_V4 レコードは、範囲の追跡が有効になっていて、ファイルサイズが RangeTrackFileSizeThreshold メンバーの値以上である場合にのみ出力されます。ユーザーは常に、1 つ以上のUSN_RECORD_V4 レコードの後に 1 つの USN_RECORD_V3 レコードを受け取ります。

変更ジャーナルクライアントのパスフォワード互換性を提供するために、Microsoft は、変更ジャーナルソフトウェアのメジャーバージョン番号とマイナーバージョン番号を USN_RECORD_V4 構造で提供します。コードでは、これらの値を調べ、変更ジャーナルソフトウェアとの独自の互換性を調べ、必要に応じて非互換性を適切に処理する必要があります。

マイナーバージョン番号の変更は、既存の USN_RECORD_V4 構造体メンバーがまだ有効であることを示しますが、最後のメンバー (可変長文字列) の間に新しいメンバーが追加されている可能性があります。

このような変更を適切に処理するには、最後のメンバーの場所に依存するコンパイル時ポインターの算術演算をコードで実行しないでください。たとえば、マイナーバージョン番号を変更すると、呼び出しが sizeof(USN_RECORD) 信頼できなくなります。代わりに、 RecordLength メンバーを使用する実行時の計算に依存します。

変更ジャーナル・ソフトウェアのメジャー・バージョン番号の増加は、 USN_RECORD_V4 構造に大きな変更が加えられた可能性があり、現在の定義が信頼できない可能性があることを示しています。コードが変更ジャーナル・ソフトウェアのメジャー・バージョン番号の変更を検出した場合、コードは変更ジャーナルで機能しません。

詳細については、「変更ジャーナルの作成、変更、および削除」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows 8.1 [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2012 R2 [デスクトップアプリのみ]
Header	winioctl.h (Windows.h を含む)