READ_USN_JOURNAL_DATA_V0 结构 (winioctl.h)
包含定义一组更新序列号的信息， (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;
} READ_USN_JOURNAL_DATA_V0, *PREAD_USN_JOURNAL_DATA_V0;
成员
StartUsn
开始读取更改日记帐的 USN。
若要在日记中的第一条记录处启动读取操作，请将 StartUsn 成员设置为零。 由于 USN 包含在每个日记记录中，因此输出缓冲区会告知读取操作实际开始的记录。
若要在特定记录处启动读取操作，请将 StartUsn 设置为该记录 USN。
如果指定的非零 USN 小于更改日志中的第一个 USN，则会发生错误并返回 ERROR_JOURNAL_ENTRY_DELETED 错误代码。 此代码可能指示指定的 USN 一次有效，但此后已被删除。
有关导航 READ_USN_JOURNAL_DATA_V0 中返回的更改日志缓冲区的详细信息，请参阅 遍历更改日记记录的缓冲区。
ReasonMask
标志掩码，每个标志都表示更改，文件或目录在更改日志中具有记录。 若要在 FSCTL_READ_USN_JOURNAL 操作中返回，更改日记记录必须至少设置其中一个标志。
有效标志的列表如下所示。 保留未使用的位。
| 值 | 含义 |
|---|---|
|
用户已更改一个或多个文件或目录属性 (如只读属性、隐藏属性、系统属性、存档属性或稀疏属性) ，或者更改了一个或多个时间戳。 |
|
文件或目录已关闭。 |
|
文件或目录的压缩状态从 或 更改为压缩。 |
|
文件或目录将添加到 。 |
|
文件或目录中的数据将被覆盖。 |
|
文件或目录将被截断。 |
|
用户对文件或目录扩展属性进行更改。 基于 Windows 的应用程序无法访问这些 NTFS 文件系统属性。 |
|
文件或目录已加密或解密。 |
|
首次创建文件或目录。 |
|
文件或目录已删除。 |
|
在文件或目录中添加或删除 NTFS 文件系统硬链接。 类似于 POSIX 硬链接的 NTFS 文件系统硬链接是查看同一文件或目录的多个目录条目之一。 |
|
用户更改了 FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 属性。 也就是说，用户将文件或目录从可编制内容索引的文件或目录更改为不能编制索引的文件或目录，反之亦然。 (内容索引允许通过构建所选 content 的数据库来快速搜索数据。) |
|
文件的一个或多个命名数据流已添加到 。 |
|
文件的一个或多个命名数据流中的数据将被覆盖。 |
|
文件的一个或多个命名数据流将被截断。 |
|
文件或目录的对象标识符已更改。 |
|
文件或目录已重命名，包含此日记记录的 USN_RECORD_V2 或 USN_RECORD_V3 结构中的文件名为新名称。 |
|
文件或目录已重命名，并且包含此日记记录 的USN_RECORD_V2 或 USN_RECORD_V3 结构中的文件名是以前的名称。 |
|
文件或目录中包含的重新分析点已更改，或者将重分析点添加到文件或目录中，或者从文件或目录中删除重分析点。 |
|
对文件或目录的访问权限进行了更改。 |
|
在文件或目录中添加或删除命名流，或者重命名命名流。 |
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。
要求
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 标头 | winioctl.h (包括 Windows.h) |