FindFirstChangeNotification

A version of this page is also available for

Windows Embedded CE 6.0 R3

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 bWatchSubtree is 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 FindNextChangeNotification function and the appropriate wait function. When you no longer need the handle, close it by using the FindCloseChangeNotification function.

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

Requirements

See Also

Reference

File I/O Functions
FindCloseChangeNotification
FindNextChangeNotification

Other Resources

Wait Functions