USN_RECORD_V2
構造体サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。
フィールド
| フィールド | 型 | サイズ | x64 | x86 | 説明 | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| RecordLength | DWORD | 4 | +0 | +0 | レコードの全長 (バイト単位) です。 USN_RECORD_V2 は可変サイズであるため、出力バッファー内の次のレコードのアドレスを計算する際には RecordLength メンバーを使用してください。たとえば、 DeviceIoControl 関数の操作のうち USN_RECORD_V2 を扱うものから返されるバッファーが該当します。 変更ジャーナルレコードのサイズ (バイト単位) は、最大でも USN_RECORD_V2 構造体のサイズに、MaximumComponentLength 文字から 1 を引いた数 (構造体内で宣言されている文字の分) にワイド文字のサイズを掛けた値を加えたものです。 MaximumComponentLength の値は、 GetVolumeInformation 関数を呼び出して取得できます。C 言語では、 次のコード例のようにしてレコードサイズを求められます。
| ||||||||||||||||||||||||||||||||||||||||||||||||
| MajorVersion | WORD | 2 | +4 | +4 | このレコードに対応する変更ジャーナルソフトウェアのメジャーバージョン番号です。 たとえば、変更ジャーナルソフトウェアがバージョン 2.0 の場合、メジャーバージョン番号は 2 です。
| ||||||||||||||||||||||||||||||||||||||||||||||||
| MinorVersion | WORD | 2 | +6 | +6 | このレコードに対応する変更ジャーナルソフトウェアのマイナーバージョン番号です。たとえば、 変更ジャーナルソフトウェアがバージョン 2.0 の場合、マイナーバージョン番号は 0 です。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| FileReferenceNumber | ULONGLONG | 8 | +8 | +8 | このレコードが変更を記録しているファイルまたはディレクトリの序数です。 これは、ジャーナルレコードとファイルを関連付けるために任意に割り当てられる値です。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| ParentFileReferenceNumber | ULONGLONG | 8 | +16 | +16 | このレコードに関連付けられたファイルまたはディレクトリが存在する ディレクトリの序数です。 これは、ジャーナルレコードと親ディレクトリを関連付けるために任意に割り当てられる値です。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| Usn | LONGLONG | 8 | +24 | +24 | このレコードの USN です。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| TimeStamp | LONGLONG | 8 | +32 | +32 | このレコードの標準的な UTC タイムスタンプ (FILETIME) を 64 ビット形式で表したものです。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| Reason | DWORD | 4 | +40 | +40 | ファイルまたはディレクトリが開かれてから、このファイルまたはディレクトリのジャーナルレコードに 蓄積された変更の理由を示すフラグです。 ファイルまたはディレクトリが閉じられると、 USN_REASON_CLOSE フラグが設定された最後の USN レコードが生成されます。次の変更 (たとえば次回のオープン操作や 削除の後) では、新しい理由フラグのセットを持つ新しいレコードが開始されます。 名前の変更または移動の操作では、2 つの USN レコードが生成されます。1 つは対象項目の以前の親ディレクトリを記録し、 もう 1 つは新しい親を記録します。 設定される可能性のあるフラグを次の表に示します。 注 未使用のビットは予約済みです。
| ||||||||||||||||||||||||||||||||||||||||||||||||
| SourceInfo | DWORD | 4 | +44 | +44 | 変更元に関する追加情報で、 FSCTL_MARK_HANDLE の DeviceIoControl 操作によって設定されます。 スレッドが新しい USN レコードを書き込むとき、直前のレコードのソース情報フラグは、 そのスレッドが同じフラグも設定した場合にのみ引き続き設定されます。そのため、ソース情報の仕組みにより、 アプリケーションは既知のソース (たとえばウイルス対策フィルター) のみが設定した USN レコードを除外できます。 次の値のいずれかを設定できます。
| ||||||||||||||||||||||||||||||||||||||||||||||||
| SecurityId | DWORD | 4 | +48 | +48 | このレコードに関連付けられたファイルまたはディレクトリに割り当てられた一意のセキュリティ識別子です。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| FileAttributes | DWORD | 4 | +52 | +52 | このレコードに関連付けられたファイルまたはディレクトリの属性で、 GetFileAttributes 関数が返す値と同じものです。ファイルまたはディレクトリに 関連付けられたストリームの属性は含まれません。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| FileNameLength | WORD | 2 | +56 | +56 | このレコードに関連付けられたファイルまたはディレクトリの名前の長さ (バイト単位) です。この名前は FileName メンバーに格納されます。ファイル名の長さを求めるには、 ファイル名を区切る終端の '\0' に依存せず、FileName ではなくこのメンバーを使用してください。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| FileNameOffset | WORD | 2 | +58 | +58 | 構造体の先頭から FileName メンバーまでのオフセットです。 | ||||||||||||||||||||||||||||||||||||||||||||||||
| FileName | WCHAR | 2 | +60 | +60 | このレコードに関連付けられたファイルまたはディレクトリの名前を Unicode 形式で表したものです。 このファイル名またはディレクトリ名は可変長です。 FileName を扱う際は、ファイル名に終端の '\0' 区切り文字が含まれることを前提にせず、 FileNameLength を使用してファイル名の長さを判断してください。 FileName を使ったコンパイル時のポインター演算は行わないでください。代わりに、 FileNameOffset メンバーの値を使用して必要な計算を実行時に行ってください。 そうすることで、将来のバージョンの USN_RECORD_V2 ともコードの互換性を保ちやすくなります。 |
公式ドキュメント
更新シーケンス番号 (USN) 変更ジャーナルのバージョン 2.0 レコードの情報を格納します。 アプリケーションは 2.0 より前のバージョンの変更ジャーナルを扱おうとしてはなりません。Windows 8 および Windows Server 2012 より前は、この構造体の名前は USN_RECORD でした。古い SDK やコンパイラーでコンパイルする場合は、その名前を使用してください。
解説(Remarks)
DeviceIoControl の操作のうち USN_RECORD_V2 を扱うものが返す出力バッファーでは、すべてのレコードが バッファーの先頭から 64 ビット境界に配置されます。
変更ジャーナルのクライアントで上位互換性を確保できるように、Microsoft は変更ジャーナルソフトウェアの メジャーバージョン番号とマイナーバージョン番号を USN_RECORD_V2 構造体で提供しています。コードではこれらの値を調べ、 変更ジャーナルソフトウェアとの互換性を判断し、必要に応じて非互換性を適切に処理してください。
マイナーバージョン番号の変更は、既存の USN_RECORD_V2 構造体のメンバーが引き続き有効である一方で、 最後から 2 番目のメンバーと、可変長文字列である最後のメンバーとの間に新しいメンバーが追加された可能性があることを示します。
このような変更に適切に対応するため、コードでは最後のメンバーの位置に依存する
コンパイル時のポインター演算を行わないでください。たとえば、そのため C コードの
sizeof(USN_RECORD) は信頼できなくなります。代わりに、
RecordLength メンバーを使用した実行時の計算を利用してください。
変更ジャーナルソフトウェアのメジャーバージョン番号の増加は、 USN_RECORD_V2 構造体に大きな変更が加えられ、 現在の定義が信頼できなくなっている可能性を示します。コードが変更ジャーナルソフトウェアの メジャーバージョン番号の変更を検出した場合は、その変更ジャーナルを扱わないでください。
詳細については、 変更ジャーナルの作成、変更、削除を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
各言語での定義
#include <windows.h>
// USN_RECORD_V2 (x64 64 / x86 64 バイト)
typedef struct USN_RECORD_V2 {
DWORD RecordLength;
WORD MajorVersion;
WORD MinorVersion;
ULONGLONG FileReferenceNumber;
ULONGLONG ParentFileReferenceNumber;
LONGLONG Usn;
LONGLONG TimeStamp;
DWORD Reason;
DWORD SourceInfo;
DWORD SecurityId;
DWORD FileAttributes;
WORD FileNameLength;
WORD FileNameOffset;
WCHAR FileName[1];
} USN_RECORD_V2;using System;
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct USN_RECORD_V2
{
public uint RecordLength;
public ushort MajorVersion;
public ushort MinorVersion;
public ulong FileReferenceNumber;
public ulong ParentFileReferenceNumber;
public long Usn;
public long TimeStamp;
public uint Reason;
public uint SourceInfo;
public uint SecurityId;
public uint FileAttributes;
public ushort FileNameLength;
public ushort FileNameOffset;
[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 1)] public string FileName;
}Imports System.Runtime.InteropServices
<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure USN_RECORD_V2
Public RecordLength As UInteger
Public MajorVersion As UShort
Public MinorVersion As UShort
Public FileReferenceNumber As ULong
Public ParentFileReferenceNumber As ULong
Public Usn As Long
Public TimeStamp As Long
Public Reason As UInteger
Public SourceInfo As UInteger
Public SecurityId As UInteger
Public FileAttributes As UInteger
Public FileNameLength As UShort
Public FileNameOffset As UShort
<MarshalAs(UnmanagedType.ByValTStr, SizeConst:=1)> Public FileName As String
End Structureimport ctypes
from ctypes import wintypes
class USN_RECORD_V2(ctypes.Structure):
_fields_ = [
("RecordLength", wintypes.DWORD),
("MajorVersion", ctypes.c_ushort),
("MinorVersion", ctypes.c_ushort),
("FileReferenceNumber", ctypes.c_ulonglong),
("ParentFileReferenceNumber", ctypes.c_ulonglong),
("Usn", ctypes.c_longlong),
("TimeStamp", ctypes.c_longlong),
("Reason", wintypes.DWORD),
("SourceInfo", wintypes.DWORD),
("SecurityId", wintypes.DWORD),
("FileAttributes", wintypes.DWORD),
("FileNameLength", ctypes.c_ushort),
("FileNameOffset", ctypes.c_ushort),
("FileName", ctypes.c_wchar * 1),
]#[repr(C)]
pub struct USN_RECORD_V2 {
pub RecordLength: u32,
pub MajorVersion: u16,
pub MinorVersion: u16,
pub FileReferenceNumber: u64,
pub ParentFileReferenceNumber: u64,
pub Usn: i64,
pub TimeStamp: i64,
pub Reason: u32,
pub SourceInfo: u32,
pub SecurityId: u32,
pub FileAttributes: u32,
pub FileNameLength: u16,
pub FileNameOffset: u16,
pub FileName: [u16; 1],
}import "golang.org/x/sys/windows"
type USN_RECORD_V2 struct {
RecordLength uint32
MajorVersion uint16
MinorVersion uint16
FileReferenceNumber uint64
ParentFileReferenceNumber uint64
Usn int64
TimeStamp int64
Reason uint32
SourceInfo uint32
SecurityId uint32
FileAttributes uint32
FileNameLength uint16
FileNameOffset uint16
FileName [1]uint16
}type
USN_RECORD_V2 = record
RecordLength: DWORD;
MajorVersion: Word;
MinorVersion: Word;
FileReferenceNumber: UInt64;
ParentFileReferenceNumber: UInt64;
Usn: Int64;
TimeStamp: Int64;
Reason: DWORD;
SourceInfo: DWORD;
SecurityId: DWORD;
FileAttributes: DWORD;
FileNameLength: Word;
FileNameOffset: Word;
FileName: array[0..0] of WideChar;
end;const USN_RECORD_V2 = extern struct {
RecordLength: u32,
MajorVersion: u16,
MinorVersion: u16,
FileReferenceNumber: u64,
ParentFileReferenceNumber: u64,
Usn: i64,
TimeStamp: i64,
Reason: u32,
SourceInfo: u32,
SecurityId: u32,
FileAttributes: u32,
FileNameLength: u16,
FileNameOffset: u16,
FileName: [1]u16,
};type
USN_RECORD_V2 {.bycopy.} = object
RecordLength: uint32
MajorVersion: uint16
MinorVersion: uint16
FileReferenceNumber: uint64
ParentFileReferenceNumber: uint64
Usn: int64
TimeStamp: int64
Reason: uint32
SourceInfo: uint32
SecurityId: uint32
FileAttributes: uint32
FileNameLength: uint16
FileNameOffset: uint16
FileName: array[1, uint16]struct USN_RECORD_V2
{
uint RecordLength;
ushort MajorVersion;
ushort MinorVersion;
ulong FileReferenceNumber;
ulong ParentFileReferenceNumber;
long Usn;
long TimeStamp;
uint Reason;
uint SourceInfo;
uint SecurityId;
uint FileAttributes;
ushort FileNameLength;
ushort FileNameOffset;
wchar[1] FileName;
}HSP用 定義
HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; USN_RECORD_V2 サイズ: 64 バイト(x64)
dim st, 16 ; 4byte整数×16(構造体サイズ 64 / 4 切り上げ)
; RecordLength : DWORD (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; MajorVersion : WORD (+4, 2byte) wpoke st,4,値 / 値 = wpeek(st,4)
; MinorVersion : WORD (+6, 2byte) wpoke st,6,値 / 値 = wpeek(st,6)
; FileReferenceNumber : ULONGLONG (+8, 8byte) qpoke st,8,値 / qpeek(st,8) ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; ParentFileReferenceNumber : ULONGLONG (+16, 8byte) qpoke st,16,値 / qpeek(st,16) ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; Usn : LONGLONG (+24, 8byte) qpoke st,24,値 / qpeek(st,24) ※IronHSPのみ。3.7/3.8は lpoke st,24,下位 : lpoke st,28,上位
; TimeStamp : LONGLONG (+32, 8byte) qpoke st,32,値 / qpeek(st,32) ※IronHSPのみ。3.7/3.8は lpoke st,32,下位 : lpoke st,36,上位
; Reason : DWORD (+40, 4byte) st.10 = 値 / 値 = st.10 (lpoke/lpeek も可)
; SourceInfo : DWORD (+44, 4byte) st.11 = 値 / 値 = st.11 (lpoke/lpeek も可)
; SecurityId : DWORD (+48, 4byte) st.12 = 値 / 値 = st.12 (lpoke/lpeek も可)
; FileAttributes : DWORD (+52, 4byte) st.13 = 値 / 値 = st.13 (lpoke/lpeek も可)
; FileNameLength : WORD (+56, 2byte) wpoke st,56,値 / 値 = wpeek(st,56)
; FileNameOffset : WORD (+58, 2byte) wpoke st,58,値 / 値 = wpeek(st,58)
; FileName : WCHAR (+60, 2byte) varptr(st)+60 を基点に操作(2byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global USN_RECORD_V2
#field int RecordLength
#field short MajorVersion
#field short MinorVersion
#field int64 FileReferenceNumber
#field int64 ParentFileReferenceNumber
#field int64 Usn
#field int64 TimeStamp
#field int Reason
#field int SourceInfo
#field int SecurityId
#field int FileAttributes
#field short FileNameLength
#field short FileNameOffset
#field wchar FileName 1
#endstruct
stdim st, USN_RECORD_V2 ; NSTRUCT 変数を確保
st->RecordLength = 100
mes "RecordLength=" + st->RecordLength