USN_RECORD_V2構造体 (winioctl.h)

更新シーケンス番号 (USN) 変更ジャーナル バージョン 2.0 レコードの情報を格納します。 アプリケーションは、2.0 より前の変更ジャーナル・バージョンの操作を試みてはなりません。 Windows 8より前に、この構造体Windows Server 2012 USN_RECORDという名前が付けられました。 その名前を使用して、古い SDK とコンパイラでコンパイルします。

構文

typedef struct {
  DWORD         RecordLength;
  WORD          MajorVersion;
  WORD          MinorVersion;
  DWORDLONG     FileReferenceNumber;
  DWORDLONG     ParentFileReferenceNumber;
  USN           Usn;
  LARGE_INTEGER TimeStamp;
  DWORD         Reason;
  DWORD         SourceInfo;
  DWORD         SecurityId;
  DWORD         FileAttributes;
  WORD          FileNameLength;
  WORD          FileNameOffset;
  WCHAR         FileName[1];
} USN_RECORD_V2, *PUSN_RECORD_V2;

メンバー

RecordLength

レコードの合計長 (バイト単位)。

USN_RECORD_V2は可変サイズであるため、RecordLength メンバーは、出力バッファー内の次のレコードのアドレス (たとえば、USN_RECORD_V2を操作する DeviceIoControl 関数の操作から返されるバッファー) を計算するときに使用する必要があります。

変更ジャーナル・レコードの最大サイズ (バイト単位) は、 USN_RECORD_V2 構造体のサイズに加え、 MaximumComponentLength 文字から 1 を引いた値 (構造体で宣言された文字の場合) は、ワイド文字のサイズの倍になります。 MaximumComponentLength の値は、
GetVolumeInformation 関数。 C では、次のコード例を使用してレコード サイズを決定できます。

C++
MaximumChangeJournalRecordSize = ( MaximumComponentLength * sizeof(WCHAR) + sizeof(USN_RECORD) + sizeof(WCHAR) );

変更履歴ソフトウェアのバージョン変更間の互換性を維持するには、実行時計算を使用して 、USN_RECORD_V2 構造のサイズを決定します。 バージョン変更間の互換性の詳細については、このトピックの「備考」セクションを参照してください。

MajorVersion

このレコードの変更ジャーナル・ソフトウェアのメジャー・バージョン番号。

たとえば、変更ジャーナル ソフトウェアがバージョン 2.0 の場合、メジャー バージョン番号は 2 です。

値	意味
2	構造体は USN_RECORD_V2 構造であり、構造体の残りの部分は、そのレイアウトを使用して解析する必要があります。
3	構造体は USN_RECORD_V3 構造であり、構造体の残りの部分は、そのレイアウトを使用して解析する必要があります。
4	構造体は [USN_RECORD_V4 構造体](ns-winioctl-usn_record_v4.md) であり、構造体の残りの部分は、そのレイアウトを使用して解析する必要があります。

MinorVersion

このレコードの変更ジャーナル・ソフトウェアのマイナー・バージョン番号。 たとえば、変更ジャーナル ソフトウェアがバージョン 2.0 の場合、マイナー バージョン番号は 0 になります。

FileReferenceNumber

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

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

ParentFileReferenceNumber

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

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

Usn

このレコードの USN。

TimeStamp

このレコードの標準 UTC タイム スタンプ (FILETIME) (64 ビット形式)。

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 ファイル システムのハード リンクは、ファイルまたはディレクトリに追加または削除されます。 NTFS ファイル システムのハード リンクは、POSIX ハード リンクと同様に、同じファイルまたはディレクトリを参照する複数のディレクトリ エントリの 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_V2 構造体のファイル名が新しい名前になります。
USN_REASON_RENAME_OLD_NAME 0x00001000	ファイルまたはディレクトリの名前が変更され、 USN_RECORD_V2 構造体のファイル名が前の名前になります。
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 レコードを除外できます。

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

値	意味
USN_SOURCE_AUXILIARY_DATA 0x00000002	この操作により、プライベート データ ストリームがファイルまたはディレクトリに追加されます。 たとえば、チェックサム情報を追加するウイルス検出機能があります。 ウイルス検出機能が項目を変更すると、システムは 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	この操作では、クラウドに存在するのと同じファイルの内容と一致するように、クライアント システム上のファイルを変更しています。

SecurityId

このレコードに関連付けられているファイルまたはディレクトリに割り当てられた一意のセキュリティ識別子。

FileAttributes

GetFileAttributes 関数によって返される、このレコードに関連付けられているファイルまたはディレクトリの属性。 ファイルまたはディレクトリに関連付けられているストリームの属性は除外されます。

FileNameLength

このレコードに関連付けられているファイルまたはディレクトリの名前の長さ (バイト単位)。 FileName メンバーには、この名前が含まれています。 FileName でファイル名を区切る末尾の '\0' に応じてではなく、このメンバーを使用してファイル名の長さを確認 します。

FileNameOffset

構造体の先頭からの FileName メンバーのオフセット。

FileName[1]

Unicode 形式でこのレコードに関連付けられているファイルまたはディレクトリの名前。 このファイル名またはディレクトリ名は可変長です。

FileName を使用する場合は、末尾の '\0' 区切り記号を含むファイル名をカウントするのではなく、FileNameLength を使用してファイル名の長さを決定します。

FileName を使用してコンパイル時ポインターの算術演算を実行しないでください。 代わりに、 FileNameOffset メンバーの値を使用して、実行時に必要な計算を行います。 これを行うと、将来のバージョンのUSN_RECORD_V2とコードの互換性を高めるの に役立ちます。

注釈

USN_RECORD_V2で動作する DeviceIoControl 操作から返される出力バッファーでは、すべてのレコードがバッファーの先頭から 64 ビット境界に配置されます。

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

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

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

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

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

要件

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

こちらもご覧ください

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V3

USN_RECORD_V4構造体