FindFirstChangeNotification (Compact 2013)

3/26/2014

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, and the client receives recursive notifications. If it is set to FALSE, it monitors only the specified directory.

• dwNotifyFilter
  [in] Filter conditions that satisfy a change notification wait. The following table shows possible values. This parameter can be any combination of these values.

  Value	Description
  FILE_NOTIFY_CHANGE_ATTRIBUTES	Returns a change notification wait for any change to the attributes of files in the watched directory or subdirectory.
  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.
  FILE_NOTIFY_CHANGE_CREATION	Returns a change notification wait for any files created in the watched directory or subdirectory.
  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_ACCESS	Returns a change notification wait for any change to the last access time of files in the watched directory or subdirectory.
  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_SECURITY	Returns a change notification wait for any security-descriptor change in the watched directory or subdirectory.
  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.

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.

Requirements

See Also

Reference

File I/O Functions
FindCloseChangeNotification
FindNextChangeNotification