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) );
|
MajorVersion
このレコードの変更ジャーナル・ソフトウェアのメジャー・バージョン番号。
たとえば、変更ジャーナル ソフトウェアがバージョン 3.0 の場合、メジャー バージョン番号は 3 です。
| 値 | 意味 |
|---|---|
|
構造体は USN_RECORD_V2 構造体であり、構造体の残りの部分はそのレイアウトを使用して解析する必要があります。 |
|
構造体は USN_RECORD_V3 構造体であり、構造体の残りの部分はそのレイアウトを使用して解析する必要があります。 |
|
構造体は [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 つは新しい親を記録します。
次の表は、使用可能なフラグを示しています。
SourceInfo
変更のソースに関する追加情報。DeviceIoControl 操作のFSCTL_MARK_HANDLEによって設定されます。
スレッドが新しい USN レコードを書き込むとき、前のレコードのソース情報フラグは、スレッドがそれらのフラグも設定している場合にのみ存在し続けます。 したがって、ソース情報構造を使用すると、アプリケーションは、既知のソース (ウイルス対策フィルターなど) によってのみ設定された USN レコードを除外できます。
次の 2 つの値のいずれかを設定できます。
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 を含む) |