FindFirstChangeNotification

HANDLE FindFirstChangeNotification(lpszPath, fWatchSubTree, fdwFilter)
LPTSTR lpszPath;	/* directory to watch	*/
BOOL fWatchSubTree;	/* watch subtree or just directory?	*/
DWORD fdwFilter;	/* filter conditions to watch for	*/

The FindFirstChangeNotification function creates a change notification handle and sets up initial change notification filter conditions. A wait on a notification handle is successful when a change matching the filter conditions occurs in the specified directory or subtree.

Parameters

lpszPath

Points to a null-terminated string specifying the pathname of the directory to watch.

fWatchSubTree

Specifies whether to monitor the directory or the directory tree. If TRUE, Win32 monitors the directory tree rooted at the specified directory; if FALSE, Win32 monitors only the specified directory.

fdwFilter

Specifies the filter conditions used to satisfy a change notification wait. This parameter may be some combination of the following values:

Value

Meaning

FILE_NOTIFY_CHANGE_FILENAME	Any file-name changes that occur in a directory or subtree being watched will satisfy a change notification wait. This includes renames, creations, and deletes.
FILE_NOTIFY_CHANGE_DIRNAME	Any directory-name changes that occur in a directory or subtree being watched will satisfy a change notification wait. This includes directory creations and deletions.
FILE_NOTIFY_CHANGE_ATTRIBUTES	Any attribute changes that occur in a directory or subtree being watched will satisfy a change notification wait.
FILE_NOTIFY_CHANGE_SIZE	Any file-size changes in the watch satisfy a change notification wait. The system detects a change in file size only when the file size changes on disk. For systems with extensive caching this may only occur when the system cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_WRITE	Any changes to the last write time of files in the watch satisfy a change notification wait. The system detects a change to the last write time only when the last write time changes on disk. For systems with extensive caching this may only occur when the system cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_SECURITY	Any security-descriptor changes that occur in a directory or subtree being watched will satisfy a change notification wait.

Return Value

If the function is successful, the return value is a handle to a find change notification object.

If the function fails, the return value is INVALID_HANDLE_VALUE. Use the GetLastError function to obtain extended error information.

Comments

The handle returned by this function can be used with the WaitForSingleObject or WaitForMultipleObjects functions to monitor the specified directory or subtree. A wait is satisfied when one of the filter conditions occurs in the monitored directory or subtree. After the wait is satisfied, the application can respond to this condition and continue monitoring the directory by calling FindNextChangeNotification and the appropriate wait function.

When the handle is no longer needed, it should be closed with the FindCloseChangeNotification function.

Example

The following example uses the directory-notification mechanism to update the changed directory.

DWORD WaitStatus;

HANDLE ChangeHandles[2];

* Watch C:\WINDOWS subtree for file creation and

* deletion

ChangeHandles[0] = FindFirstChangeNotification("C:\\WINDOWS", TRUE,

FILE_NOTIFY_CHANGE_FILENAME | FILE_NOTIFY_CHANGE_DIRNAME);

if (ChangeHandles[0] == INVALID_HANDLE_VALUE)

ExitProcess(GetLastError());

* Watch C:\ subtree for directory creation and

* deletion

ChangeHandles[1] = FindFirstChangeNotification("C:\\", TRUE,

FILE_NOTIFY_CHANGE_DIRNAME);

if (ChangeHandles[1] == INVALID_HANDLE_VALUE)

ExitProcess(GetLastError());

* Change notification is set. Now wait on both notification

* handles and refresh appropriately

while (TRUE) {

/* Wait for notification */

WaitStatus = WaitForMultipleObjects(2, ChangeHandles,

FALSE, -1);

switch (WaitStatus) {

case WAIT_OBJECT_0:

* notification handle for C:\WINDOWS kicked us out

* of the wait. Refresh this directory, and restart

* change notification

RefreshDirectory("C:\\WINDOWS"); /* app supplied */

if (FindNextChangeNotification(ChangeHandles[0]) == FALSE)

ExitProcess(GetLastError());

break;

case WAIT_OBJECT_0 + 1:

* notification handle for C:\ kicked us out

* of the wait. Refresh this directory, and restart

* change notification

RefreshTree("C:\\"); /* appl supplied function */

if (FindNextChangeNotification(ChangeHandles[1]) == FALSE)

ExitProcess(GetLastError());

break;

default:

ExitProcess(GetLastError());

}