MonitorDirectory -- monitor changes in a directory (V8.0)
[id] = MonitorDirectory(id, dir$[, table])
This function can be used to monitor changes in the directory specified by dir$. In order to monitor directory changes, MonitorDirectory() will create a new directory object and assign the specified id to it. If you pass Nil in id, MonitorDirectory() will automatically choose an identifier and return it.

Whenever something in the directory specified by dir$ changes, MonitorDirectory() will send a DirectoryChanged event to your script. In order to handle this event, you need to install an event handler for it first using the InstallEventHandler() function. See InstallEventHandler for details.

MonitorDirectory() also accepts an optional table argument which allows you to configure some further options. The following tags are currently recognized by the optional table argument:

If this tag is set to True, MonitorDirectory() will forward all directory change notifications from the operating system to your script. Think twice before using this because, depending on the operating system and file system, you might get several messages for just a single change because of file system internals. By default, MonitorDirectory() will try to filter such duplicate notifications for you so that you don't get several messages for just a single change. If you don't want MonitorDirectory() to apply this filter, i.e. if you want all notifications, set this tag to True. Defaults to False.

This tag can be set to a value of an arbitrary type. MonitorDirectory() will store it in the MonitorUserData field of the message that is sent by InstallEventHandler(). This is useful for avoiding global variables.

If this tag is set to True, your event callback will also be notified about what exactly has changed. Your event callback will receive two new parameters: Type informing you about the type of change, i.e. whether a file or directory has been added, removed, or changed, and Name will contain the name of the file or directory that has been changed. Note that the All table tag (see above) will be ignored when setting ReportChanges to True. (V9.0)

Note that the directory object created by this function must only be used for monitoring directory changes. It is not possible to pass it to other directory functions like NextDirectoryEntry() or RewindDirectory(). An exception is the CloseDirectory() function: You should call CloseDirectory() as soon as you are finished monitoring the directory. This ensures that no resources are wasted and no unnecessary messages are posted to your script.

Also note that some file systems do not support monitoring of directories. This can happen especially on network volumes or network file systems. In that case, MonitorDirectory() can fail.

id for the directory or Nil for auto id selection
name of the directory to monitor
optional: table containing further parameters (see above)
optional: identifier of the directory; will only be returned when you pass Nil as argument 1 (see above)
InstallEventHandler({DirectoryChanged = Function(msg)
MonitorDirectory(1, "Data")
The code above monitors all changes in the "Data" directory and prints a message whenever something changes in that directory.

Show TOC