ReadDirectoryChangesW 函数 (winbase.h)
检索描述指定目录中更改的信息。 函数不会报告对指定目录本身的更改。
若要跟踪卷上的更改，请参阅更改日志。
语法
BOOL ReadDirectoryChangesW(
[in] HANDLE hDirectory,
[out] LPVOID lpBuffer,
[in] DWORD nBufferLength,
[in] BOOL bWatchSubtree,
[in] DWORD dwNotifyFilter,
[out, optional] LPDWORD lpBytesReturned,
[in, out, optional] LPOVERLAPPED lpOverlapped,
[in, optional] LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
参数
[in] hDirectory
要监视的目录的句柄。 必须使用 FILE_LIST_DIRECTORY 访问权限或访问权限（例如 包含FILE_LIST_DIRECTORY访问权限的GENERIC_READ ）打开 此 目录。
[out] lpBuffer
指向要在其中返回读取结果的 DWORD 对齐格式化缓冲区的指针。 此缓冲区的结构由 FILE_NOTIFY_INFORMATION 结构定义。 此缓冲区以同步或异步方式填充，具体取决于目录的打开方式以及为 lpOverlapped 参数提供的值。 有关详细信息，请参见“备注”部分。
[in] nBufferLength
lpBuffer 参数指向的缓冲区的大小（以字节为单位）。
[in] bWatchSubtree
如果此参数为 TRUE，则函数监视位于指定目录的根目录树。 如果此参数为 FALSE，则函数仅监视 由 hDirectory 参数指定的目录。
[in] dwNotifyFilter
函数检查以确定等待操作是否已完成的筛选条件。 此参数可使用以下一个或多个值。
[out, optional] lpBytesReturned
对于同步调用，此参数接收传输到 lpBuffer 参数的字节数。 对于异步调用，此参数未定义。 必须使用异步通知技术来检索传输的字节数。
[in, out, optional] lpOverlapped
指向 OVERLAPPED 结构的指针，该结构提供在异步操作期间使用的数据。 否则，此值为 NULL。 不使用此结构的 Offset 和 OffsetHigh 成员。
[in, optional] lpCompletionRoutine
指向完成或取消操作且调用线程处于可警报等待状态时调用的完成例程的指针。 有关此完成例程的详细信息，请参阅 FileIOCompletionRoutine。
返回值
如果该函数成功，则返回值为非零值。 对于同步调用，这意味着操作成功。 对于异步调用，这表示操作已成功排队。
如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。
如果网络重定向程序或目标文件系统不支持此操作，则函数将失败并 ERROR_INVALID_FUNCTION。
注解
若要获取目录的句柄，请使用带有 FILE_FLAG_BACKUP_SEMANTICS 标志的CreateFile 函数。
对 ReadDirectoryChangesW 的 调用可以同步或异步完成。 若要指定异步完成，请使用上述 CreateFile 打开目录，但另外在 dwFlagsAndAttributes 参数中指定 FILE_FLAG_OVERLAPPED 属性。 然后，在调用 ReadDirectoryChangesW 时指定 OVERLAPPED 结构。
首次调用 ReadDirectoryChangesW 时，系统会分配一个缓冲区来存储更改信息。 此缓冲区与目录句柄关联，直到其关闭且其大小在其生存期内不会更改。 调用此函数之间发生的目录更改将添加到缓冲区，然后随下一次调用一起返回。 如果缓冲区溢出， ReadDirectoryChangesW 仍将返回 true，但会丢弃缓冲区的整个内容， lpBytesReturned 参数将为零，这表示缓冲区太小，无法保存发生的所有更改。
成功同步完成后， lpBuffer 参数是格式化缓冲区，写入缓冲区的字节数以 lpBytesReturned 提供。 如果传输的字节数为零，则缓冲区过大，系统无法分配，或者太小，无法提供有关目录或子树中发生的所有更改的详细信息。 在这种情况下，应通过枚举目录或子树来计算更改。
对于异步完成，可以通过以下三种方式之一接收通知：
- 使用 GetOverlappedResult 函数。 若要通过 GetOverlappedResult 接收通知，请不要在 lpCompletionRoutine 参数中指定完成例程。 请务必将 OVERLAPPED 结构的 hEvent 成员设置为唯一事件。
- 使用 GetQueuedCompletionStatus 函数。 若要通过 GetQueuedCompletionStatus 接收通知，请不要在 lpCompletionRoutine 中指定完成例程。 通过调用 CreateIoCompletionPort 函数，将目录句柄 hDirectory 与完成端口相关联。
- 使用完成例程。 若要通过完成例程接收通知，请不要将目录与完成端口相关联。 在 lpCompletionRoutine 中指定完成例程。 每当线程处于可警报等待状态时，只要操作已完成或取消，将调用此例程。 系统不使用 OVERLAPPED 结构的 hEvent 成员，因此可以自己使用它。
当缓冲区长度大于 64 KB 且应用程序通过网络监视目录时，ReadDirectoryChangesW 将失败并ERROR_INVALID_PARAMETER。 这是因为基础文件共享协议存在数据包大小限制。
当缓冲区未在 DWORD 边界上对齐时，ReadDirectoryChangesW 将失败并ERROR_NOACCESS。
当系统无法记录对目录的所有更改时，ReadDirectoryChangesW 将失败并ERROR_NOTIFY_ENUM_DIR。 在这种情况下，应通过枚举目录或子树来计算更改。
如果使用短名称打开文件，则会收到短名称的更改通知。
在 Windows 8 和 Windows Server 2012 中，此函数由以下技术支持。
| 技术 | 支持 |
|---|---|
| 服务器消息块 (SMB) 3.0 协议 | 是 |
| SMB 3.0 透明故障转移 (TFO) | 是 |
| 具有横向扩展文件共享的 SMB 3.0 (SO) | 是 |
| 群集共享卷文件系统 (CSV) | 是 |
| 弹性文件系统 (ReFS) | 是 |
事务处理操作
如果某个事务绑定到目录句柄，则通知会遵循相应的事务隔离规则。要求
| 最低受支持的客户端 | Windows XP [桌面应用 | UWP 应用] |
| 最低受支持的服务器 | Windows Server 2003 [桌面应用 | UWP 应用] |
| 目标平台 | Windows |
| 标头 | winbase.h (包括 Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |