(winioctl.h) USN_RECORD_V3 结构

项目
03/04/2024

包含更新序列号 (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) );

若要保持更改日志软件的版本更改之间的兼容性，请使用运行时计算来确定 USN_RECORD_V3 结构的大小。有关版本更改之间的兼容性的详细信息，请参阅本主题中的“备注”部分。

MajorVersion

此记录的更改日记软件的主版本号。

例如，如果更改日志软件版本为 3.0，则主版本号为 3。

值	含义
2	结构是 USN_RECORD_V2 结构，结构的其余部分应使用该布局进行分析。
3	结构是 USN_RECORD_V3 结构，应使用该布局分析结构的其余部分。
4	结构是 [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 记录，一条记录项的旧父目录，一条记录新的父目录。

下表标识了可能的标志。

注意保留未使用的位。

值	含义
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	用户更改了文件或目录的扩展属性。
USN_REASON_ENCRYPTION_CHANGE 0x00040000	文件或目录已加密或解密。
USN_REASON_FILE_CREATE 0x00000100	首次创建文件或目录。
USN_REASON_FILE_DELETE 0x00000200	文件或目录已删除。
USN_REASON_HARD_LINK_CHANGE 0x00010000	在文件或目录中添加或删除 NTFS 文件系统硬链接。类似于 POSIX 硬链接的 NTFS 文件系统硬链接是查看同一文件或目录的多个目录条目之一。
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_V3结构中的文件名是新名称。
USN_REASON_RENAME_OLD_NAME 0x00001000	文件或目录已重命名， USN_RECORD_V3 结构中的文件名是以前的名称。
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	该操作正在修改客户端系统上的文件，以匹配云中存在的同一文件的内容。

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)