深入了解 ReadDirectoryChangesW 并应用其监控文件目录

简介

1. 监视指定目录的更改，并将有关更改的信息打印到控制台，该功能的实现不仅可以在内核层，在应用层同样可以。程序中使用 ReadDirectoryChangesW 函数来监视目录中的更改，并使用 FILE_NOTIFY_INFORMATION 结构来获取有关更改的信息。
3. ReadDirectoryChangesW 是Windows提供一个函数，它属于Windows API的一部分，主要用于监视文件系统中目录的修改、新增、删除等变化，并通过回调函数向应用程序提供通知。该API很实用，目前市面上已知的所有运行在用户态同步应用，都绕不开这个接口。但正确使用该API相对来说比较复杂，该接口能真正考验一个Windows开发人员对线程、异步IO、可提醒IO、IO完成端口等知识的掌握情况。

复制代码

其函数原型为：

1. BOOL WINAPI ReadDirectoryChangesW(
2.   _In_        HANDLE                          hDirectory,
3.   _Out_       LPVOID                          lpBuffer,
4.   _In_        DWORD                           nBufferLength,
5.   _In_        BOOL                            bWatchSubtree,
6.   _In_        DWORD                           dwNotifyFilter,
7.   _Out_opt_   LPDWORD                         lpBytesReturned,
8.   _Inout_opt_ LPOVERLAPPED                    lpOverlapped,
9.   _In_opt_    LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
10. );

复制代码

• hDirectory：要监视的目录的句柄。
  
• lpBuffer：接收变更通知的缓冲区。
  
• nBufferLength：缓冲区的大小。
  
• bWatchSubtree：如果为 TRUE，则监视目录树中的所有目录。如果为 FALSE，则仅监视指定的目录。
  
• dwNotifyFilter：指定要监视的变更类型，可以是文件夹或文件的新增、删除、修改等。
  
• lpBytesReturned：返回实际读取到的字节数。
  
• lpOverlapped：用于异步操作的 OVERLAPPED 结构。
  
• lpCompletionRoutine：指定一个回调函数，在异步操作完成时调用。
  

由于该函数提供了丰富的调用方式，包括同步和异步方式。异步方式可以采用以下三种方式获取完成通知：

• 在OVERLAPPED结构中的hEvent成员中设置一个事件句柄，使用GetOverlappedResult 获取完成结果。
  
• 使用可提醒IO, 在参数lpComletionRoutine指定一个回调函数。当ReadDirectoryChangesW异步请求完成时，驱动会将指定的回调函数(lpComletionRoutine)投递到调用线程的APC队列中。对可提醒IO，OVERLAPPED结构中的hEvent 字段操作系统并不使用，我们可以自己使用该值。
  
• 使用IO完成端口，通过GetQueuedComletionStatus获取完成结果。
  

同步方式比较简单，但不具可伸缩性，在实际应用中并不多。不同的异步方式也影响到线程模型的选择，所以如何正确使用该函数其实并不容易。
使用可提醒 IO

可提醒IO是异步IO的一种，为了支持可提醒IO, Windows为线程都增加了一个基础设施——APC（异步过程调用），即每个线程都有一个APC队列。当线程处理于可提醒状态时，系统会检测该线程的APC队列是否为空，如果不会空，系统会依次取出队列中的APC进程调用。
采用可提醒IO时，需要设置一个完成回调函数ReadDirectoryChangesW。当发起异步IO请求后，调用线程不会被阻塞，系统会将该异步请求交给驱动程序，驱动程序将该请求加入到请求队列中，当异步请求完成时，驱动程序会将完成回调函数加入到发起线程的APC队列中，当发起线程处于可提醒状态时，该完成回调函数就会被执行。
Windows提供了6个API，可以将线程置为可提醒状态，分别是：
SleepEx、WaitForSingleObjectEx、WaitForMultipleObjectsEx、SignalObjectAndWait、GetQueuedCompletionStatusEx、MsgWaitForMultipleObjectsEx。
利用线程的APC队列，可以创建一个工作线程，该线程采用可提醒IO方式循环等待APC调用，当我们在工作线程中发起一个ReadDirectoryChangesW请求时，线程被挂起，当一个请求完成时，会将完成回调函数加入到线程的APC队列中，系统检测到APC队列不为空，线程会被唤醒，并取出APC队列中的一项进行调用，当APC队列为空中，线程会被再次挂起，直到APC队列中出现一项新的项。
读者可能会觉得上面的流程很复杂，其实实现很简单，复杂的东西都由系统帮我们做了，我们使用SleepEx使工作线程变为可提醒状态，工作线程代码如下：

1.     while (!m_bTerminate || HasOutstandingRequests())
2.     {
3.         ::SleepEx(INFINITE, true);
4.     }

复制代码

有了工作线程帮我们处理完成回调函数的调用，我们还需要在该工作线程中发起一个ReadDirectoryChangesW请求，在请求时需要指定一个完成回调函数(最后一个参数)。对于倒数第二个参数OVERLAPPED，对可提醒IO来讲，系统并不关心hEvent，所以可以将该参数设计为业务相关的数据进行传递，在实现时设置为了一个请求对象的指针(具体参考代码实现)，ReadDirectoryChangesW 请求代码如下：

1. BOOL success = ::ReadDirectoryChangesW(
2.         GetDirectoryHandle(),               // handle to directory
3.         GetBuffer(),                        // read results buffer
4.         GetBufferSize(),                    // length of buffer
5.         IsWatchSubTree(),                   // monitoring option
6.         GetNotifyFilter(),                  // filter conditions
7.         NULL,                               // bytes returned
8.         this,                               // overlapped buffer
9.         &FileIoCompletionRoutine);          // completion routine

复制代码

完成回调函数需要我们自己实现，原型为：

1. VOID CALLBACK FileIOCompletionRoutine(
2.   _In_    DWORD        dwErrorCode,
3.   _In_    DWORD        dwNumberOfBytesTransfered,
4.   _Inout_ LPOVERLAPPED lpOverlapped
5. );

复制代码

读者可能会疑问，怎么让ReadDirectoryChangesW请求在工作线程中执行呢？Windows为我们提供了以下API，可以将一个APC投递到一个指定线程的APC队列中：

1. DWORD QueueUserAPC(
2.   PAPCFUNC  pfnAPC,
3.   HANDLE    hThread,
4.   ULONG_PTR dwData
5. );

复制代码

有了上面这个利器，我们可以很方便的在线程间通信，为了简化代码复杂度，采用无锁设计，我将添加文件夹、读取文件夹变更请求、移除文件夹、结束请求都投递到该工作线程中执行，并约定一些类成员变量只能在该线程中访问。
需要注意的是，由于我们需要不断监控文件夹的磁盘变更情况，所以在FileIOCompletionRoutine中处理完文件夹的变更数据后，需要再次发起一次ReadDirectoryChangesW请求，这样就形成了一条变更链，实现文件夹实时磁盘监控。
使用IO完成端口

IO完成端口，是Windows为打造一个出色服务器环境，提高应用程序性能而提出的解决方案。关于IO完成端口的背景知识并不是本文的重点，不熟悉的读者请自行补充。
ReadDirectoryChangesW 支持采用IO完成端口方式读取文件夹磁盘变更，为了简单起见，在不考虑线程模型的情况下，其流程大概如下：

1. 1. 创建一个IO完成端口；
2. 2. 打开一个文件夹；
3. 3. 将打开的文件夹句柄关联到一个IO完成端口上；
4. 4. 发起一次ReadDirectoryChangesW请求；
5. 5. 调用GetQueuedCompletionStatus获取完成通知；
6. 6. 处理完成通知；
7. 7. 关闭文件夹句柄；
8. 8. 关闭IO完成端口；

复制代码

在第5步中，调用GetQueuedCompletionStatus会阻塞调用线程，在实际应用中，我们经常会在一个工作线程中调用GetQueuedCompletionStatus。为了实时监控文件夹的磁盘变更，我同样会创建一个工作线程，且该线程只用于处理IO完成端口的完成通知，代码如下：

1.     while (1)
2.     {
3.         ULONG_PTR pCompKey = NULL;
4.         DWORD dwNumberOfBytes = 0;
5.         OVERLAPPED* pOverlapped = NULL;
6.         BOOL bRet = m_iocp.GetStatus(&pCompKey, &dwNumberOfBytes, &pOverlapped);
7.         DWORD dwLastError = ::GetLastError();
8.         if (bRet)
9.         {
10.             ProcessIocpSuccess(pCompKey, dwNumberOfBytes, pOverlapped);
11.         }
12.         else
13.         {
14.             if (!ProcessIocpError(dwLastError, pOverlapped))
15.             {
16.                 break;
17.             }
18.         }
19.     }

复制代码

工作线程就绪后，在做完2，3步之后，仍然需要发起一个ReadDirectoryChangesW请求，对于IO完成端口，虽然请求并不是一定要在工作线程中执行，但我们仍然需要这样做，理由是除了简化我们的编程模型之外，也能使线程更容易得体地退出（稍后会说）。
跟可提醒IO不同的是，发起一个ReadDirectoryChangesW 请求时，IO完成端口会使用OVERLAPPED中的hEvent，所以我们不能将其设为一个请求对象的指针，而应该设为NULL, 但为了在上下文中传递请求对象指针，使用了点技巧，即将请求对象继承自OVERLAPPED，再将请求对象的指针传入即可（具体参考代码）；另外并不需要再指定完成回调函数，如下：

1. BOOL success = ::ReadDirectoryChangesW(
2.         GetDirectoryHandle(),               // handle to directory
3.         GetBuffer(),                        // read results buffer
4.         GetBufferSize(),                    // length of buffer
5.         IsWatchSubTree(),                   // monitoring option
6.         GetNotifyFilter(),                  // filter conditions
7.         NULL,                               // bytes returned
8.         this,                               // overlapped buffer
9.         NULL);                              // completion routine

复制代码

同样，我们怎样让ReadDirectoryChangesW请求在工作线程中执行呢，幸运的是Windows提供了API：

1. BOOL WINAPI PostQueuedCompletionStatus(
2.   _In_     HANDLE       CompletionPort,
3.   _In_     DWORD        dwNumberOfBytesTransferred,
4.   _In_     ULONG_PTR    dwCompletionKey,
5.   _In_opt_ LPOVERLAPPED lpOverlapped
6. );

复制代码

以上API可以在任何线程中调用，将一个和完成键dwCompletionKey关联的数据投递到任何一个调用GetQueuedCompletionStatus的线程，当然这里只是我们的工作线程。这使得其它线程可以很容易和工作线程通信。
同样为了简化代码复杂度，采用无锁设计，仍然将添加文件夹、读取文件夹变更请求、移除文件夹、结束请求都投递到该工作线程中执行，并约定一些类成员变量只能在该线程中访问。
如何退出工作线程

取消一个ReadDirectoryChangesW请求，可以使用CancelIo或CancelIoEx，这两个API的区别是，CancelIo只能取消调用线程关联的IO设备；而CancelIoEx可以取消指定线程关联的IO设备；但CancelIoEx只能在Vista及之后的系统中使用，为了让代码能正常工作于XP及以后的系统，我使用了CancelIo，这也是为什么我在使用IO完成端口的时候也要将请求放到工作线程中去执行的原因。

• 
  
  • 可提醒IO退出
    如上所说，CancelIo需要在工作线程中去执行，我们先将m_bTerminate设为true, 再调用QueueUserAPC将一个退出请求投递到工作线程中，然后在工作线程中调用CancelIO，之后，系统会将完成回调函数加入到工作线程的APC队列中，并且将dwErrorCode设为ERROR_OPERATION_ABORTED，当收到该错误时，我们释放请求对象占用的系统资源，当所有请求对象都释放时，工作线程中的while循环结束，线程正常退出。
    
  
  
• 
  
  • IO完成端口退出
    和可提醒IO退出方式不同的是，GetQueuedCompletionStatus的错误处理稍微复杂一点，是采用GetLastError获得，同样在收到错误码为ERROR_OPERATION_ABORTED时，释放请求对象占用的系统资源，当所有请求对象都释放时，工作线程中的while循环结束，线程正常退出。
    
  
  

代码结构

为了同时支持可提醒IO和IO完成端口异步请求的方式调用ReadDirectoryChangesW, 代码做了一些抽象，采用C/S模型。将ReadDirectoryChangesW调用封装到了CReadDirectoryRequest类中，根据不同的异步模型派生出CCompletionRoutineRequest和CIoCompletionPortRequest类；
同样工作线程封装到了CReadDirectoryServer类中，根据不同的异步模型，派生出CCompletionRoutineServer和CIoCompletionPortServer类；
CReadDirectoryChanges类管理CReadDirectoryServer对象的生命周期，并维护一个线程安全的队列用于缓存文件夹的变更数据，同时对客户端暴露基本服务接口。框架结构如下图所示：

完整代码项目

以下代码中使用CreateThread函数创建一个线程，并将MonitorFileThreadProc运行起来，此函数使用带有FILE_LIST_directory标志的CreateFile打开指定的目录，该标志允许该函数监视目录。并使用ReadDirectoryChangesW函数读取目录中的更改，传递一个缓冲区来存储更改，并指定要监视的更改类型。
使用WideCharToMultiByte函数将宽字符文件名转换为多字节文件名，并将文件名与目录路径连接以获得文件的完整路径。然后，该功能将有关更改的信息打印到控制台。

1. #include <stdio.h>
2. #include <Windows.h>
3. #include <tlhelp32.h>
5. DWORD WINAPI MonitorFileThreadProc(LPVOID lParam)
6. {
7.   char *pszDirectory = (char *)lParam;
8.   BOOL bRet = FALSE;
9.   BYTE Buffer[1024] = { 0 };
11.   FILE_NOTIFY_INFORMATION *pBuffer = (FILE_NOTIFY_INFORMATION *)Buffer;
12.   DWORD dwByteReturn = 0;
13.   HANDLE hFile = CreateFile(pszDirectory, FILE_LIST_DIRECTORY, FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
14.     NULL, OPEN_EXISTING, FILE_FLAG_BACKUP_SEMANTICS, NULL);
15.   if (INVALID_HANDLE_VALUE == hFile)
16.     return 1;
18.   while (TRUE)
19.   {
20.     ZeroMemory(Buffer, sizeof(Buffer));
21.     // 设置监控目录回调函数
22.     bRet = ReadDirectoryChangesW(hFile,&Buffer,sizeof(Buffer),TRUE,
23.       FILE_NOTIFY_CHANGE_FILE_NAME |      // 修改文件名
24.       FILE_NOTIFY_CHANGE_ATTRIBUTES |     // 修改文件属性
25.       FILE_NOTIFY_CHANGE_LAST_WRITE,      // 最后一次写入
26.       &dwByteReturn, NULL, NULL);
27.     if (TRUE == bRet)
28.     {
29.       char szFileName[MAX_PATH] = { 0 };
31.       // 将宽字符转换成窄字符,宽字节字符串转多字节字符串
32.       WideCharToMultiByte(CP_ACP,0,pBuffer->FileName,(pBuffer->FileNameLength / 2),
33.         szFileName,MAX_PATH,NULL,NULL);
35.       // 将路径与文件连接成完整文件路径
36.       char FullFilePath[1024] = { 0 };
37.       strncpy(FullFilePath, pszDirectory, strlen(pszDirectory));
38.       strcat(FullFilePath, szFileName);
40.       switch (pBuffer->Action)
41.       {
42.         case FILE_ACTION_ADDED:
43.         {
44.           printf("添加: %s \n", FullFilePath); break;
45.         }
46.         case FILE_ACTION_REMOVED:
47.         {
48.           printf("删除: %s \n", FullFilePath); break;
49.         }
50.         case FILE_ACTION_MODIFIED:
51.         {
52.           printf("修改: %s \n", FullFilePath); break;
53.         }
54.         case FILE_ACTION_RENAMED_OLD_NAME:
55.         {
56.           printf("重命名: %s", szFileName);
57.           if (0 != pBuffer->NextEntryOffset)
58.           {
59.             FILE_NOTIFY_INFORMATION *tmpBuffer = (FILE_NOTIFY_INFORMATION *)
60.               ((DWORD)pBuffer + pBuffer->NextEntryOffset);
61.             switch (tmpBuffer->Action)
62.               {
63.                 case FILE_ACTION_RENAMED_NEW_NAME:
64.                 {
65.                   ZeroMemory(szFileName, MAX_PATH);
66.                   WideCharToMultiByte(CP_ACP,0,tmpBuffer->FileName,
67.                     (tmpBuffer->FileNameLength / 2),
68.                     szFileName,MAX_PATH,NULL,NULL);
69.                   printf(" -> %s \n", szFileName);
70.                   break;
71.                 }
72.               }
73.           }
74.           break;
75.         }
76.         case FILE_ACTION_RENAMED_NEW_NAME:
77.         {
78.           printf("重命名(new): %s \n", FullFilePath); break;
79.         }
80.       }
81.     }
82.   }
83.   CloseHandle(hFile);
84.   return 0;
85. }
87. int main(int argc, char * argv[])
88. {
89.   char *pszDirectory = "C:\";
91.   HANDLE hThread = CreateThread(NULL, 0, MonitorFileThreadProc, pszDirectory, 0, NULL);
92.   WaitForSingleObject(hThread, INFINITE);
93.   CloseHandle(hThread);
94.   system("start https://www.chwm.vip/?ReadDirectoryChangesW");
95.   return 0;
96. }

复制代码

效果演示 ：


免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！