Name
MonitorDirectory -- monitor changes in a directory (V8.0)
Synopsis
[id] = MonitorDirectory(id, dir$[, table])
Function
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 a vacant 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:

All:
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.

UserData:
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.

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.

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

Show TOC