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

函数检查以确定等待操作是否已完成的筛选条件。 此参数可使用以下一个或多个值。

值 含义
FILE_NOTIFY_CHANGE_FILE_NAME
0x00000001
 对受监视的目录或子树中文件名的任意更改都会导致返回一个更改通知等待操作。 更改包括重命名、创建或删除文件。
FILE_NOTIFY_CHANGE_DIR_NAME
0x00000002
 监视目录或子树中的任何目录名称更改都会导致更改通知等待操作返回。 更改包括创建或删除目录。
FILE_NOTIFY_CHANGE_ATTRIBUTES
0x00000004
 对受监视的目录或子树中属性的任意更改都会导致返回一个更改通知等待操作。
FILE_NOTIFY_CHANGE_SIZE
0x00000008
 对受监视的目录或子树中文件大小的任意更改都会导致返回一个更改通知等待操作。 仅当文件写入磁盘时，操作系统才会检测文件大小的更改。 对于使用大量缓存的操作系统，仅当缓存充分刷新时，才会进行检测。
FILE_NOTIFY_CHANGE_LAST_WRITE
0x00000010
 对受监视的目录或子树中文件的上次写入时间的任意更改都会导致返回一个更改通知等待操作。 仅当文件写入磁盘时，操作系统才会检测上次写入时间的更改。 对于使用大量缓存的操作系统，仅当缓存充分刷新时，才会进行检测。
FILE_NOTIFY_CHANGE_LAST_ACCESS
0x00000020
 对受监视目录或子树中文件上次访问时间的任何更改都会导致更改通知等待操作返回。
FILE_NOTIFY_CHANGE_CREATION
0x00000040
 对受监视目录或子树中文件创建时间的任何更改都会导致更改通知等待操作返回。
FILE_NOTIFY_CHANGE_SECURITY
0x00000100
 监视目录或子树中的任何安全描述符更改都会导致更改通知等待操作返回。

[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 成员，因此可以自己使用它。
有关详细信息，请参阅 同步和异步 I/O。

当缓冲区长度大于 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

另请参阅

CreateFile

CreateIoCompletionPort

目录管理函数

FILE_NOTIFY_INFORMATION

FileIOCompletionRoutine

GetOverlappedResult

GetQueuedCompletionStatus

OVERLAPPED