ReadDirectoryChangesW的用法

Retrieves information that describes the changes within the specified directory. The function does not report changes to the specified directory itself.

To track changes on a volume, see change journals.

Syntax

BOOL WINAPI ReadDirectoryChangesW(
  __in         HANDLE hDirectory,
  __out        LPVOID lpBuffer,
  __in         DWORD nBufferLength,
  __in         BOOL bWatchSubtree,
  __in         DWORD dwNotifyFilter,
  __out_opt    LPDWORD lpBytesReturned,
  __inout_opt  LPOVERLAPPED lpOverlapped,
  __in_opt     LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);

hDirectory [in]

A handle to the directory to be monitored. This directory must be opened with the FILE_LIST_DIRECTORY access right.

Windows 2000:  Only one handle is serviced at a time. Additional handle requests are not serviced until the previous service request is completed.

lpBuffer [out]

A pointer to the DWORD-aligned formatted buffer in which the read results are to be returned. The structure of this buffer is defined by the FILE_NOTIFY_INFORMATION structure. This buffer is filled either synchronously or asynchronously, depending on how the directory is opened and what value is given to the lpOverlapped parameter. For more information, see the Remarks section.

nBufferLength [in]

The size of the buffer that is pointed to by the lpBuffer parameter, in bytes.

bWatchSubtree [in]

If this parameter is TRUE, the function monitors the directory tree rooted at the specified directory. If this parameter is FALSE, the function monitors only the directory specified by the hDirectory parameter.

dwNotifyFilter [in]

The filter criteria that the function checks to determine if the wait operation has completed. This parameter can be one or more of the following values.

Value	Meaning
FILE_NOTIFY_CHANGE_FILE_NAME 0x00000001	Any file name change in the watched directory or subtree causes a change notification wait operation to return. Changes include renaming, creating, or deleting a file.
FILE_NOTIFY_CHANGE_DIR_NAME 0x00000002	Any directory-name change in the watched directory or subtree causes a change notification wait operation to return. Changes include creating or deleting a directory.
FILE_NOTIFY_CHANGE_ATTRIBUTES 0x00000004	Any attribute change in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_SIZE 0x00000008	Any file-size change in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change in file size only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_WRITE 0x00000010	Any change to the last write-time of files in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change to the last write-time only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_ACCESS 0x00000020	Any change to the last access time of files in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_CREATION 0x00000040	Any change to the creation time of files in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_SECURITY 0x00000100	Any security-descriptor change in the watched directory or subtree causes a change notification wait operation to return.

 

lpBytesReturned [out, optional]

For synchronous calls, this parameter receives the number of bytes transferred into the lpBuffer parameter. For asynchronous calls, this parameter is undefined. You must use an asynchronous notification technique to retrieve the number of bytes transferred.

lpOverlapped [in, out, optional]

A pointer to an OVERLAPPED structure that supplies data to be used during asynchronous operation. Otherwise, this value is NULL. The Offset and OffsetHigh members of this structure are not used.

lpCompletionRoutine [in, optional]

A pointer to a completion routine to be called when the operation has been completed or canceled and the calling thread is in an alertable wait state. For more information about this completion routine, see FileIOCompletionRoutine.

Return Value

If the function succeeds, the return value is nonzero. For synchronous calls, this means that the operation succeeded. For asynchronous calls, this indicates that the operation was successfully queued.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

If the network redirector or the target file system does not support this operation, the function fails with ERROR_INVALID_FUNCTION.

Remarks

To obtain a handle to a directory, use the CreateFile function with the FILE_FLAG_BACKUP_SEMANTICS flag.

A call to ReadDirectoryChangesW can be completed synchronously or asynchronously. To specify asynchronous completion, open the directory with CreateFile as shown above, but additionally specify the FILE_FLAG_OVERLAPPED attribute in the dwFlagsAndAttributes parameter. Then specify an OVERLAPPED structure when you call ReadDirectoryChangesW.

When you first call ReadDirectoryChangesW, the system allocates a buffer to store change information. This buffer is associated with the directory handle until it is closed and its size does not change during its lifetime. Directory changes that occur between calls to this function are added to the buffer and then returned with the next call. If the buffer overflows, the entire contents of the buffer are discarded and the lpBytesReturned parameter contains zero.

Upon successful synchronous completion, the lpBuffer parameter is a formatted buffer and the number of bytes written to the buffer is available in lpBytesReturned. If the number of bytes transferred is zero, the buffer was either too large for the system to allocate or too small to provide detailed information on all the changes that occurred in the directory or subtree. In this case, you should compute the changes by enumerating the directory or subtree.

For asynchronous completion, you can receive notification in one of three ways:

• Using the GetOverlappedResult function. To receive notification through GetOverlappedResult, do not specify a completion routine in the lpCompletionRoutine parameter. Be sure to set the hEvent member of the OVERLAPPED structure to a unique event.
• Using the GetQueuedCompletionStatus function. To receive notification through GetQueuedCompletionStatus, do not specify a completion routine in lpCompletionRoutine. Associate the directory handle hDirectory with a completion port by calling the CreateIoCompletionPort function.
• Using a completion routine. To receive notification through a completion routine, do not associate the directory with a completion port. Specify a completion routine in lpCompletionRoutine. This routine is called whenever the operation has been completed or canceled while the thread is in an alertable wait state. The hEvent member of the OVERLAPPED structure is not used by the system, so you can use it yourself.

For more information, see Synchronous and Asynchronous I/O.

ReadDirectoryChangesW fails with ERROR_INVALID_PARAMETER when the buffer length is greater than 64 KB and the application is monitoring a directory over the network. This is due to a packet size limitation with the underlying file sharing protocols.

ReadDirectoryChangesW fails with ERROR_NOACCESS when the buffer is not aligned on a DWORD boundary.

Windows 2000:  Clients that attempt multiple simultaneous long-term requests against a server, for example change notifications, should be running Service Pack 2 or higher. See Knowledge Base article Q271148 for more details.

If you opened the file using the short name, you can receive change notifications for the short name.

Transacted Operations

If there is a transaction bound to the directory handle, then the notifications follow the appropriate transaction isolation rules. 

 

Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	WinBase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

 

 

 

上面是MSDN的原文，摘要下：

 

1.该函数用来监控文件夹变化，基本步骤是：

    a.使用CreateFile打开目录，打开目录的时候一定要包含FILE_LIST_DIRECTORY参数，貌似是要取得一个什么权限；

    b.然后使用该函数监听，收到系统的消息后，从lpbuffer里面取得Action和Filename；

 

2.该函数可以同步调用或者异步调用，是同步还是异步取决于CreateFile时给的参数，和该函数的第7个参数LPOVERLAPPED lpOverlapped：

    a.同步调用，则CreateFile时使用FILE_LIST_DIRECTORY,第7个参数设置为nil;

    b.异步调用，则CreateFile时还要指定FILE_FLAG_OVERLAPPED，第7个参数还要给个值；

 

3.第三个参数和第四个参数设置缓冲区，最大64KB，如果监视目录下一次操作太多的文件，超过缓冲区（缓冲区溢出），就会丢失消息什么的；