USN_RECORD_V4 结构 (winioctl.h)
包含更新序列号 (USN) 变更日志 4.0 版记录的信息。 版本 2.0 和 3.0 记录由 USN_RECORD_V2 定义， (也称为 USN_RECORD) 和 USN_RECORD_V3 结构。
语法
typedef struct {
USN_RECORD_COMMON_HEADER Header;
FILE_ID_128 FileReferenceNumber;
FILE_ID_128 ParentFileReferenceNumber;
USN Usn;
DWORD Reason;
DWORD SourceInfo;
DWORD RemainingExtents;
WORD NumberOfExtents;
WORD ExtentSize;
USN_RECORD_EXTENT Extents[1];
} USN_RECORD_V4, *PUSN_RECORD_V4;
成员
Header
描述记录的记录长度、主版本和次要版本的 USN_RECORD_COMMON_HEADER 结构。
FileReferenceNumber
此记录所记录更改的文件或目录的 128 位序号。
此值是一个任意分配的值，用于将日记记录与文件相关联。
ParentFileReferenceNumber
与此记录关联的文件或目录所在的目录的 128 位序号。
此值是一个任意分配的值，用于将日记记录与父目录相关联。
Usn
此记录的 USN。
Reason
标识自文件或目录打开以来在此文件或目录日志记录中累积的更改的原因的标志。
当文件或目录关闭时，会生成具有 USN_REASON_CLOSE 标志的最终 USN 记录。 例如，下一个更改 (，在下一次打开操作或删除后，) 使用一组新的原因标志启动新记录。
重命名或移动操作将生成两条 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_V4 结构中的文件名是新名称。
|
- USN_REASON_RENAME_OLD_NAME
- 0x00001000
|
重命名了文件或目录， USN_RECORD_V4 结构中的文件名是以前的名称。
|
- 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
|
操作正在修改文件，以匹配同一文件的内容，该文件存在于副本 (replica) 集的另一个成员中。
|
- USN_SOURCE_CLIENT_REPLICATION_MANAGEMENT
- 0x00000008
|
该操作正在修改客户端系统上的文件，以匹配云中存在的同一文件的内容。
|
RemainingExtents
当前 USN_RECORD_V4 记录后保留的盘区数。 可能需要多个版本 4.0 记录来描述给定文件的所有已修改区。 当 RemainingExtents 成员为 0 时，当前 USN_RECORD_V4 记录是该文件的最后 USN_RECORD_V4 记录。 给定文件的最后一个USN_RECORD_V4条目始终后跟至少设置了USN_REASON_CLOSE标志的USN_RECORD_V3记录。
NumberOfExtents
当前 USN_RECORD_V4 条目中的盘区数。
ExtentSize
Extents 成员中每个USN_RECORD_EXTENT结构的大小（以字节为单位）。
Extents[1]
表示USN_RECORD_V4项中的盘区的USN_RECORD_EXTENT结构的数组。
仅当启用范围跟踪且文件大小等于或大于 RangeTrackFileSizeThreshold 成员的值时，才会输出USN_RECORD_V4记录。 用户始终收到一个或多个 USN_RECORD_V4 记录，后跟一 条USN_RECORD_V3 记录。
为了在更改日志客户端中提供路径向前兼容性，Microsoft 在 USN_RECORD_V4 结构中提供了更改日记软件的主要版本号和次要版本号。 代码应检查这些值，检查其自身与更改日记软件的兼容性，并在必要时正常处理任何不兼容情况。
次要版本号的更改表明现有的 USN_RECORD_V4 结构成员仍然有效，但可能已在倒数第二个成员和最后一个成员之间添加了新成员，后者是一个可变长度的字符串。
若要正常处理此类更改，代码不应执行依赖于最后一个成员位置的任何编译时指针算术。 例如，次要版本号的更改会使 sizeof(USN_RECORD) 调用不可靠。 而是依赖于使用 RecordLength 成员的运行时计算。
更改日志软件的主版本号增加表明 USN_RECORD_V4 结构可能已发生重大更改，并且当前定义可能不可靠。 如果代码检测到更改日志软件的主版本号发生更改，则代码不应与更改日志一起使用。
有关详细信息，请参阅创建、修改和删除更改日记。
要求
| 要求 |
值 |
| 最低受支持的客户端 |
Windows 8.1 [仅限桌面应用] |
| 最低受支持的服务器 |
Windows Server 2012 R2 [仅限桌面应用] |
| 标头 |
winioctl.h (包括 Windows.h) |
另请参阅
FSCTL_MARK_HANDLE
FSCTL_READ_USN_JOURNAL
FSCTL_USN_TRACK_MODIFIED_RANGES
GetFileAttributes
GetVolumeInformation
READ_USN_JOURNAL_DATA
USN_RECORD_COMMON_HEADER
USN_RECORD_EXTENT
USN_RECORD_V2
USN_RECORD_V3
卷管理结构