Notifies the OS that a file or directory has changed.
def notify_directory_change(file_name: str, action: int, wait: bool) -> bool: ...
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 on_notify_directory_change should and should not be called:
- DO call on_notify_directory_change 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 on_notify_directory_change 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_ADDED||0x00000001||The specified file or directory has been created.|
|CBFS_NOTIFY_FLAG_REMOVED||0x00000002||The specified file or directory has been removed.
For directories, all handles to files in the directory are immediately closed.
|CBFS_NOTIFY_FLAG_MODIFIED||0x00000003||The 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_MODIFIED||0x00000004||The timestamp or other attributes of the specified file or directory have been modified.|
|CBFS_NOTIFY_FLAG_ALLOCATION_SIZE_MODIFIED||0x00000005||The 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_INVALIDATE||0x00000006||The 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 is ignored and is assumed to be set to False.