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 版,則次要版本號碼為零。
FileReferenceNumber
此記錄所記下之檔案或目錄的128位序號。
這是任意指派的值,可將日誌記錄與檔案產生關聯。
ParentFileReferenceNumber
與這個記錄相關聯的檔案或目錄所在目錄的128位序號。
這是任意指派的值,可將日誌記錄與父目錄產生關聯。
Usn
此記錄的 USN。
TimeStamp
此記錄的標準 UTC 時間戳 (FILETIME) ,格式為 64 位。
Reason
旗標,可識別自檔案或目錄開啟后累積在此檔案或目錄日誌記錄中變更的原因。
當檔案或目錄關閉時,會產生最後一筆 USN 記錄,並設定 USN_REASON_CLOSE 旗標。 例如,下一個變更 (,在下一個開啟作業或刪除之後,) 以一組新的原因旗標啟動新的記錄。
重新命名或移動作業會產生兩筆 USN 記錄,一筆記錄專案的舊父目錄,另一筆記錄新的父系。
下表識別可能的旗標。
SourceInfo
DeviceIoControl 作業FSCTL_MARK_HANDLE所設定之變更來源的其他資訊。
當線程寫入新的 USN 記錄時,只有在線程也設定這些旗標時,先前記錄中的來源資訊旗標才會繼續存在。 因此,來源信息結構可讓應用程式篩選出僅由已知來源設定的USN記錄,例如防毒篩選器。
可以設定下列兩個值的其中一個。
SecurityId
指派給與此記錄相關聯的檔案或目錄的唯一安全性標識符。
FileAttributes
與這個記錄相關聯的檔案或目錄屬性,如 GetFileAttributes 函式所傳回。 會排除與檔案或目錄相關聯的數據流屬性。
FileNameLength
與此記錄相關聯的檔案或目錄名稱長度,以位元組為單位。 FileName 成員包含此名稱。 使用此成員來判斷檔名長度,而不是根據尾端 『\0』 來分隔 FileName 中的檔名。
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 [僅限傳統型應用程式] |
標頭 | winioctl.h (包含 Windows.h) |