The ReadDirectoryChangesW function returns information describing the changes occurring within a directory.
BOOL ReadDirectoryChangesW(
HANDLE hDirectory, // handle to the directory to be watched
LPVOID lpBuffer, // pointer to the buffer to receive the read
// results
DWORD nBufferLength, // length of lpBuffer
BOOL bWatchSubtree, // flag for monitoring directory or
// directory tree
DWORD dwNotifyFilter, // filter conditions to watch for
LPDWORD lpBytesReturned, // number of bytes returned
LPOVERLAPPED lpOverlapped,
// pointer to structure needed for
// overlapped I/O
LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
// pointer to completion routine
);
Value | Meaning |
---|---|
FILE_NOTIFY_CHANGE_FILE_NAME | Any filename 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 | 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 | Any attribute change in the watched directory or subtree causes a change notification wait operation to return. |
FILE_NOTIFY_CHANGE_SIZE | 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 | 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 | 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 | 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 | Any security-descriptor change in the watched directory or subtree causes a change notification wait operation to return. |
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.
To obtain a handle to a directory, use the CreateFile function with FILE_FLAG_BACKUP_SEMANTICS as follows:
hDir = CreateFile(
DirName, // pointer to the file name
FILE_LIST_DIRECTORY, // access (read-write) mode
FILE_SHARE_READ|FILE_SHARE_DELETE, // share mode
NULL, // security descriptor
OPEN_EXISTING, // how to create
FILE_FLAG_BACKUP_SEMANTICS, // file attributes
NULL // file with attributes to copy
);
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.
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 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:
Windows NT: Requires version 4.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in winbase.h.
Import Library: Use kernel32.lib.
File I/O Overview, File Functions, CreateFile, CreateIoCompletionPort, FILE_NOTIFY_INFORMATION, FileIOCompletionRoutine, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED