Share via

winioctl.h) (READ_USN_JOURNAL_DATA_V1 结构

  • 项目

包含定义一组要返回到调用进程的更新序列号 (USN) 变更日志记录的信息。 它由 FSCTL_QUERY_USN_JOURNAL 和 FSCTL_READ_USN_JOURNAL 控制代码使用。 在Windows 8之前，Windows Server 2012此结构命名为READ_USN_JOURNAL_DATA。 使用该名称使用较旧的 SDK 和编译器进行编译。 Windows Server 2012引入了READ_USN_JOURNAL_DATA_V1以支持 ReFS 使用的 128 位文件标识符。

语法

typedef struct {
  USN       StartUsn;
  DWORD     ReasonMask;
  DWORD     ReturnOnlyOnClose;
  DWORDLONG Timeout;
  DWORDLONG BytesToWaitFor;
  DWORDLONG UsnJournalID;
  WORD      MinMajorVersion;
  WORD      MaxMajorVersion;
} READ_USN_JOURNAL_DATA_V1, *PREAD_USN_JOURNAL_DATA_V1;

成员

StartUsn

开始读取更改日记帐的 USN。

若要在日记中的第一条记录处启动读取操作，请将 StartUsn 成员设置为零。 由于 USN 包含在每个日记记录中，因此输出缓冲区会告知读取操作实际开始的记录。

若要在特定记录处启动读取操作，请将 StartUsn 设置为该记录 USN。

如果指定的非零 USN 小于更改日志中的第一个 USN，则会发生错误并返回 ERROR_JOURNAL_ENTRY_DELETED 错误代码。 此代码可能指示指定的 USN 一次有效，但此后已被删除。

有关导航READ_USN_JOURNAL_DATA_V0中返回的更改日志缓冲区的详细信息，请参阅遍历更改缓冲区日记记录。

ReasonMask

标志掩码，每个标志都表示更改，文件或目录在更改日志中具有记录。 若要在 FSCTL_READ_USN_JOURNAL 操作中返回，更改日记记录必须至少设置其中一个标志。

有效标志的列表如下所示。 保留未使用的位。

值 含义
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 文件系统硬链接。 类似于 POSIX 硬链接的 NTFS 文件系统硬链接是查看同一文件或目录的多个目录条目之一。
USN_REASON_INDEXABLE_CHANGE
0x00004000
 用户更改了 FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 属性。 也就是说，用户将文件或目录从可编制内容索引的文件或目录更改为不能编制索引的文件或目录，反之亦然。 (内容索引允许通过构建所选 content 的数据库来快速搜索数据。)
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_RECORD_V3 结构中的文件名为新名称。
USN_REASON_RENAME_OLD_NAME
0x00001000
 文件或目录已重命名，并且包含此日记记录 的USN_RECORD_V2 或 USN_RECORD_V3 结构中的文件名是以前的名称。
USN_REASON_REPARSE_POINT_CHANGE
0x00100000
 文件或目录中包含的重新分析点已更改，或者将重分析点添加到文件或目录中，或者从文件或目录中删除重分析点。
USN_REASON_SECURITY_CHANGE
0x00000800
 对文件或目录的访问权限进行了更改。
USN_REASON_STREAM_CHANGE
0x00200000
 在文件或目录中添加或删除命名流，或者重命名命名流。

ReturnOnlyOnClose

一个 值，该值指定何时返回更改日记记录。

若要在已更改文件或目录的最终句柄关闭时接收通知，而不是在发生更改时接收通知，请将 ReturnOnlyOnClose 设置为任何非零值，并在 ReasonMask 成员中指定USN_REASON_CLOSE标志。

ReasonMask 标志指示的所有更改最终会在文件关闭时生成对更改日记软件的调用。 如果 DeviceIoControl 调用正在等待文件关闭，该调用反过来将允许 DeviceIoControl 调用返回。 如果文件或目录在卷故障、操作系统故障或关闭之前未关闭，则下次装载卷时将执行对更改日记软件的清理调用。 即使有中间的系统重启，也会发生调用。

若要在首次记录每项更改时以及在清理时接收通知，请将 ReturnOnlyOnClose 设置为零。

无论 ReturnOnlyOnClose 是零还是非零，更改日志中清理日志中生成的记录都是对文件或目录发生 USN 更改的所有原因。 每次对项目执行最终关闭操作时，都会将 USN 关闭记录写入更改日记帐，并且该项目的 ReasonMask 标志全部重置。

对于不存在用户数据的文件或目录 (例如装载的文件夹) ，当对项目的最后一个用户句柄调用 CloseHandle 函数时，将执行最终关闭操作。

Timeout

与 BytesToWaitFor 成员一起使用的超时值（以秒为单位），用于指示操作系统在 FSCTL_READ_USN_JOURNAL 操作请求的数据数超过更改日志中存在的数据时要执行的操作。

如果 Timeout 为零且 BytesToWaitFor 为非零值，并且 FSCTL_READ_USN_JOURNAL 操作调用到达更改日志的末尾而找不到要返回的数据， 则FSCTL_READ_USN_JOURNAL 将等到未筛选数据的 BytesToWaitFor 字节添加到更改日志，然后检索指定的记录。

如果 Timeout 为非零值， BytesToWaitFor 为非零值，并且 FSCTL_READ_USN_JOURNAL 操作调用到达更改日志的末尾而找不到要返回的数据， 则FSCTL_READ_USN_JOURNAL 等待 Timeout 秒，然后尝试返回指定的记录。 超时秒后，FSCTL_READ_USN_JOURNAL检索指定范围内可用的任何记录。

在任一情况下，在超时期限过后，将处理追加到更改日志的任何新数据。 如果指定集仍然没有要返回的记录，则重复超时期限。 在此模式下， FSCTL_READ_USN_JOURNAL 保持未完成状态，直到返回至少一条记录或取消 I/O。

如果 BytesToWaitFor 为零，则忽略 Timeout 。 对于异步打开的句柄，也会忽略超时。

BytesToWaitFor

添加到更改日志的未筛选数据的字节数。 使用此值和 Timeout 告知操作系统，如果 FSCTL_READ_USN_JOURNAL 操作请求的数据多于更改日志中存在的数据，该怎么办。

如果 BytesToWaitFor 为零，则忽略 Timeout 。 在这种情况下，遇到更改日志文件的结尾时， FSCTL_READ_USN_JOURNAL 操作始终成功返回。 它还检索应用于下一 个FSCTL_READ_USN_JOURNAL 操作的 USN。 当返回的下一个 USN 与提供的 StartUsn 相同时，没有可用的记录。 调用进程不应立即再次使用 FSCTL_READ_USN_JOURNAL 。

由于 BytesToWaitFor 为零时无法预测返回的数据量，因此存在溢出输出缓冲区的风险。 若要降低此风险，请在重复FSCTL_READ_USN_JOURNAL操作中指定非零 BytesToWaitFor 值，直到更改日志中的所有记录都用完。 然后指定零以等待新记录。

或者，在FSCTL_READ_USN_JOURNAL操作调用中使用 DeviceIoControl 的 lpBytesReturned 参数来确定可用数据量，重新分配输出缓冲区 (，为新记录) 留出空间，然后再次调用 DeviceIoControl。

UsnJournalID

当前卷的日志实例的标识符。

如果更改日志已停止并重启或删除并重新创建，则 NTFS 文件系统可能会错过将事件放入更改日志中。 如果发生上述任一事件，NTFS 文件系统会为日志提供新的标识符。 如果日志标识符与当前日记标识符不一致，则对 DeviceIoControl 的调用会失败，并返回相应的错误代码。 若要检索新的日记标识符，请使用 FSCTL_QUERY_USN_JOURNAL 操作调用 DeviceIoControl。

MinMajorVersion

MaxMajorVersion

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows Server 2003 [仅限桌面应用]
标头 winioctl.h (包括 Windows.h)

另请参阅

FSCTL_QUERY_USN_JOURNAL

FSCTL_READ_USN_JOURNAL

USN_RECORD