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 版，次要版本號碼為零。

FileReferenceNumber

此記錄所記下之檔案或目錄的序號會變更。

這是任意指派的值，可將日誌記錄與檔案產生關聯。

ParentFileReferenceNumber

與這個記錄相關聯之檔案或目錄所在的目錄序號。

這是任意指派的值，可將日誌記錄與父目錄產生關聯。

Usn

此記錄的 USN。

TimeStamp

此記錄的標準 UTC 時間戳 (FILETIME) ，格式為 64 位。

Reason

旗標，可識別自檔案或目錄開啟后累積在此檔案或目錄日誌記錄中變更的原因。

當檔案或目錄關閉時，會產生最後一筆 USN 記錄，並設定 USN_REASON_CLOSE 旗標。 例如，下一個變更 (，在下一個開啟作業或刪除之後，) 以一組新的原因旗標啟動新的記錄。

重新命名或移動作業會產生兩筆 USN 記錄，一筆記錄專案的舊父目錄，另一筆記錄新的父系。

下表識別可能的旗標。

注意 未使用的位會保留。

 

值	意義
USN_REASON_BASIC_INFO_CHANGE 0x00008000	例如，用戶已變更一或多個檔案或目錄屬性 (，例如只讀、隱藏、系統、封存或疏鬆屬性) 或一或多個時間戳。
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	用戶變更檔案或目錄的擴充屬性。 Windows 應用程式無法存取這些NTFS檔案系統屬性。
USN_REASON_ENCRYPTION_CHANGE 0x00040000	檔案或目錄已加密或解密。
USN_REASON_FILE_CREATE 0x00000100	檔案或目錄第一次建立。
USN_REASON_FILE_DELETE 0x00000200	檔案或目錄已刪除。
USN_REASON_HARD_LINK_CHANGE 0x00010000	NTFS 檔系統硬式連結會新增至檔案或目錄，或從檔案或目錄移除。 NTFS 檔案系統硬式連結，類似於 POSIX 硬式連結，是看到相同檔案或目錄的數個目錄專案之一。
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	檔案的一或多個具名數據流會擴充 (新增至) 。
USN_REASON_NAMED_DATA_OVERWRITE 0x00000010	檔案的一或多個具名數據流中的數據會遭到覆寫。
USN_REASON_NAMED_DATA_TRUNCATION 0x00000040	檔案的一或多個具名數據流會被截斷。
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記錄，例如防毒篩選器。

可以設定下列兩個值的其中一個。

值	意義
USN_SOURCE_AUXILIARY_DATA 0x00000002	作業會將私人數據流新增至檔案或目錄。 例如，病毒偵測器可能會新增總和檢查碼資訊。 當病毒偵測器修改專案時，系統會產生USN記錄。 USN_SOURCE_AUXILIARY_DATA 表示修改未變更應用程式數據。
USN_SOURCE_DATA_MANAGEMENT 0x00000001	此作業提供作業系統對檔案或目錄所做的變更相關信息。 一般用途是當遠端記憶體系統將數據從外部移至本機記憶體時。 遠端記憶體是階層式記憶體管理軟體。 這類行動通常至少會將 USN_REASON_DATA_OVERWRITE 旗標新增至 USN 記錄。 不過，數據並未從使用者的觀點變更。 藉由在SourceInfo成員中記下USN_SOURCE_DATA_MANAGEMENT，您可以判斷雖然寫入作業是在專案上執行，但數據尚未變更。
USN_SOURCE_REPLICATION_MANAGEMENT 0x00000004	作業正在修改檔案，以符合存在於複本集另一個成員中相同檔案的內容。
USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT 0x00000008	作業正在修改客戶端系統上的檔案，以符合存在於雲端中相同檔案的內容。

SecurityId

指派給與此記錄相關聯的檔案或目錄的唯一安全性標識符。

FileAttributes

與這個記錄相關聯的檔案或目錄屬性，如 GetFileAttributes 函式所傳回。 會排除與檔案或目錄相關聯的數據流屬性。

FileNameLength

與此記錄相關聯的檔案或目錄名稱長度，以位元組為單位。 FileName 成員包含此名稱。 使用此成員來判斷檔名長度，而不是根據尾端 『\0』 來分隔 FileName 中的檔名。

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 [僅限傳統型應用程式]
標頭	winioctl.h (包含 Windows.h)

另請參閱

FSCTL_MARK_HANDLE

FSCTL_READ_USN_JOURNAL

GetFileAttributes

GetVolumeInformation

READ_USN_JOURNAL_DATA

USN_RECORD_V3

USN_RECORD_V4 結構