Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function creates a change notification handle and sets up initial change notification filter conditions. A wait for a notification handle succeeds when a change matching the filter conditions occurs in the specified directory or subdirectory.

Syntax 

HANDLE FindFirstChangeNotification(
  LPCTSTR 
lpPathName,
  BOOL 
bWatchSubtree,
  DWORD 
dwNotifyFilter
);

Parameters

lpPathName

[in] Pointer to a null-terminated string that specifies the path of the directory to watch.

bWatchSubtree

[in] Indicates whether the function monitors the directory or the directory tree. If this parameter is set to TRUE, the function monitors the directory tree rooted at the specified directory. If it is set to FALSE, it monitors only the specified directory.

This function fails if this parameter is set to TRUE and the FILE_NOTIFY_CHANGE_CEGETINFO flag is set.

dwNotifyFilter

[in] Filter conditions that satisfy a change notification wait. The following table shows possible values. This parameter can be one or more of these values.

Value Description

FILE_NOTIFY_CHANGE_CEGETINFO

Returns a change notification wait for any information request in the watched directory or subdirectory. Must be specified to return any data to this function. This function fails if bWatchSubtreeis set to TRUE and the this flag is set.

FILE_NOTIFY_CHANGE_DIR_NAME

Returns a change notification wait for any directory-name change in the watched directory or subdirectory. Changes include creating or deleting a directory.

FILE_NOTIFY_CHANGE_FILE_NAME

Returns a change notification wait for any file name change in the watched directory or subdirectory. Changes include renaming, creating, or deleting a file.

FILE_NOTIFY_CHANGE_LAST_WRITE

Returns a change notification wait for any change to the last write time of files in the watched directory or subdirectory. The OS detects a change to the last write time only when the file is written to the disk. For an OS that uses extensive caching, detection occurs only when the cache is sufficiently flushed.

FILE_NOTIFY_CHANGE_SIZE

Returns a change notification wait for any file-size change in the watched directory or subdirectory. The OS detects a change in file size only when the file is written to the disk. For an OS that uses extensive caching, detection occurs only when the cache is sufficiently flushed.

Return Value

A handle to a find change notification object indicates success. INVALID_HANDLE_VALUE indicates failure. To get extended error information, call GetLastError.

Remarks

The wait functions can monitor the specified directory or subdirectory by using the handle returned by this function. A wait condition is satisfied when one of the filter conditions occurs in the monitored directory or subdirectory. For more information on the wait functions, see Wait Functions.

After the wait condition has been satisfied, the application can respond to this condition and continue monitoring the directory by calling the FindNextChangeNotificationfunction and the appropriate wait function. When you no longer need the handle, close it by using the FindCloseChangeNotificationfunction.

This function fails if bWatchSubtreeis set to TRUE and the FILE_NOTIFY_CHANGE_CEGETINFO flag is set.

Requirements

Header winbase.h
Library coredll.lib
Windows Embedded CE Windows CE .NET 4.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also