次の方法で共有


USN_RECORD_V3 構造体 (winioctl.h)

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

構文

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

メンバー

RecordLength

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

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

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

C++
  MaximumChangeJournalRecordSize = 
      QuadAlign( (MaximumComponentLength - 1) * sizeof(WCHAR) 
       + sizeof(USN_RECORD_V3) );
変更ジャーナル ソフトウェアのバージョン変更間の互換性を維持するには、実行時計算を使用して 、USN_RECORD_V3 構造のサイズを決定します。 バージョン変更間の互換性の詳細については、このトピックの「解説」セクションを参照してください。

MajorVersion

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

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

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

MinorVersion

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

FileReferenceNumber

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

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

ParentFileReferenceNumber

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

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

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
ユーザーは、ファイルまたはディレクトリの拡張属性を変更しました。
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_V3 構造体のファイル名が新しい名前になります。
USN_REASON_RENAME_OLD_NAME
0x00001000
ファイルまたはディレクトリの名前が変更され、 USN_RECORD_V3 構造体のファイル名が前の名前になります。
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_V3とコードの互換性を高めるの 役立ちます。

注釈

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

範囲追跡を有効にすると、NTFS は 出力としてUSN_RECORD_V3 レコードのみを生成するように切り替えます。

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

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

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

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

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

要件

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

こちらもご覧ください

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V2

USN_RECORD_V4構造体

ボリューム管理の構造体