NotifyDirectoryChange Method

Notifies the OS that a file or directory has changed.


int NotifyDirectoryChange(const char* lpszFileName, int iAction, int bWait);
INT NotifyDirectoryChange(LPCWSTR lpszFileName, INT iAction, BOOL bWait);


If a file or directory is modified by some means external to the virtual filesystem, this method should be called to notify the OS. Doing so prompts the OS to make any requests necessary to obtain the most up-to-date information, which in turn causes the relevant class events to fire. This method returns either true or false to indicate whether it executed successfully.

Applications must be careful to call this method only when some changes have occurred that the OS has no possibility of detecting on its own. Said another way, applications should not call this method to notify the OS of changes made by invoking filesystem APIs on files and/or directories in the virtual filesystem; such changes are already inherently visible to OS.

For further clarity, here are a couple of examples describing scenarios in which NotifyDirectoryChange should and should not be called:

  • DO call NotifyDirectoryChange if, e.g., the application is in charge of mapping the contents of some database to its virtual filesystem, and an external process changes the database's contents directly. The OS only knows about the filesystem, it doesn't know or care about the database contents; so, the application must notify it that "something has changed".
  • DO NOT call NotifyDirectoryChange if, e.g., the application has created a virtual drive Z:, and either it or some other process makes a filesystem call against the virtual drive's contents; for example, DeleteFile("Z:\SomeFile.txt"). The OS detects such a change automatically since it was made via the filesystem APIs.

FileName specifies the path to the file or directory (in the virtual drive) that has changed. This path must not include a mounting point name.

Action specifies the type of change so that the OS knows what kind of information it needs to request. Possible values are:

CBFS_NOTIFY_FLAG_ADDED0x00000001The specified file or directory has been created.

CBFS_NOTIFY_FLAG_REMOVED0x00000002The specified file or directory has been removed.

For directories, all handles to files in the directory are immediately closed.

CBFS_NOTIFY_FLAG_MODIFIED0x00000003The specified file or directory has been modified.

For files, use this option when the file's contents have changed. For directories, use this option when there is a change in alternate data streams that belong to the directory.

If a directory is reported as modified, all handles to files in the directory are immediately invalidated.

CBFS_NOTIFY_FLAG_METADATA_MODIFIED0x00000004The timestamp or other attributes of the specified file or directory have been modified.

CBFS_NOTIFY_FLAG_ALLOCATION_SIZE_MODIFIED0x00000005The allocation size for the specified file or directory has been modified.

This option is only applicable if CorrectAllocationSizes is false.

CBFS_NOTIFY_FLAG_MODIFIED_NOT_INVALIDATE0x00000006The specified file or directory has been modified, but handles should not be invalidated.

Note that using this option can cause other applications to operate using stale data if they keep the specified file or directory open, since they have no way to know about the external changes.

Wait specifies whether this method should wait until the OS has finished making all of the requests necessary to handle the notification sent by this method. Passing true will cause this method to block until all requests are complete; while passing false will cause it to send the notification to the OS and return immediately, letting the OS make the necessary requests in the background. In the latter case, this method returns true, and an ERROR_IO_PENDING result code is reported to the OS.

Note: This method can only be called when Active is true. It may be called both within and outside of events; when called within an event, the Wait parameter must be false, otherwise the call will fail.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Copyright (c) 2020 Callback Technologies, Inc. - All rights reserved.
CBFS Connect 2020 C++ Edition - Version 20.0 [Build 7545]