|
Overview |
|
|
|
Group |
|
|
|
Quick Info
Windows NT
| Yes
| Win95
| No
| Win32s
| No
| Import Library
| kernel32.lib
| Header File
| winbase.h
| Unicode
| WinNT
| Platform Notes
| None
|
|
|
ReadDirectoryChangesW
[New - Windows NT]
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
| );
|
|
Parameters
hDirectory
Identifies the directory to be watched. This directory must be opened with the
FILE_LIST_DIRECTORY access right.
lpBuffer
Specifies the address of the 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
Specifies the length of the buffer pointed to by the lpBuffer parameter.
bWatchSubtree
Specifies whether the ReadDirectoryChangesW function will monitor the directory or the directory tree. If TRUE is
specified, the function monitors the directory tree rooted at the specified directory.
If FALSE is specified, the function monitors only the directory specified by
the hDirectory parameter.
dwNotifyFilter
Specifies filter criteria 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
| 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.
|
lpBytesReturned
For synchronous calls, this parameter specifies 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
Points 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
Points to a completion routine to be called when the operation has been
completed 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.
Remarks
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:
- 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 completes 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.
See Also
CreateFile, CreateIoCompletionPort, FILE_NOTIFY_INFORMATION, FileIOCompletionRoutine, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED
| Last news from Greatis Software |
 |
|
Nostalgia .Net |
|
.Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More » |
| Recommended software for developers |
 |
|
Ultimate Pack |
|
Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More » |
 |
|
Form Designer .Net |
|
Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More » |
 |
|
Print Suite .Net |
|
Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More » |
 |
|
Gradient Controls .Net |
|
Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More » |
 |
|
Greatis iGrid |
|
iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More » |
All the contacts and projectsDmitry Vasiliev (just.dmitry)
Related LinksSoftware for Visual Studio .NET developers
Software for Delphi and C++ Builder developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET More Online Helps Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages
|
