Share via


FindFirstChangeNotification

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

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] Parameter that indicates whether the function will monitor the directory or the directory tree. If this parameter is TRUE, the function monitors the directory tree rooted at the specified directory; if it is FALSE, it monitors only the specified directory.
  • dwNotifyFilter
    [in] Filter conditions that satisfy a change notification wait. The following table shows the possible values. This parameter can be one or more of these values.
    Value Description
    FILE_NOTIFY_CHANGE_FILE_NAME Returns a change notification wait for any file name change in the watched directory or subtree. Changes include renaming, creating, or deleting a file name.
    FILE_NOTIFY_CHANGE_DIR_NAME Returns a change notification wait for any directory-name change in the watched directory or subtree. Changes include creating or deleting a directory.
    FILE_NOTIFY_CHANGE_ATTRIBUTES Returns a change notification wait for any attribute change in the watched directory or subtree.
    FILE_NOTIFY_CHANGE_SIZE Returns a change notification wait for any file-size change in the watched directory or subtree. The OS detects a change in file size only when the file is written to the disk. For OSs that use extensive caching, detection occurs only when you sufficiently flush the cache.
    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 subtree causes a change notification wait operation to return. The OS detects a change to the last write-time only when the file is written to the disk. For OSs that use extensive caching, detection occurs only when you sufficiently flush the cache.

Return Values

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

If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

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

After the wait 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, you can close it by using the FindCloseChangeNotification function.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Winbase.h.
Link Library: Coredll.lib.

See Also

Wait Functions | FindCloseChangeNotification | FindNextChangeNotification

 Last updated on Friday, April 09, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.