The IDL folder watching system monitors folders for changes and invokes a user-defined callback whenever a change occurs. This enables IDL programmers to create a "batch" client that watches a specified "hot folder" and subsequently performs processing when specific conditions have been met (i.e., a file has been added to, modified, or deleted from the folder).
- If a file is added and removed between FolderWatch checks of a directory, IDL will not notice an "event" and will not report a change to the contents.
- Very large directories may take several seconds to check. Execution of IDL will be suspended during the check.
- Folder watching interrupts PRO code execution.
- When watching a directory, FOLDERWATCH will only issue "add" or "remove" notifications. A folder will never be reported as being modified.
Methods and Additional Information
Example
This example monitors the files in the current working directory, and its subdirectories, and prints out which file has changed and how.
pro MyCallback, obj, data
COMPILE_OPT IDL2
ret = "The file "
ret += data.file
ret += " has been "
if data.added then ret += "added to"
if data.modified then ret += "modified in"
if data.removed then ret += "removed from"
ret += " the working directory. "
ret += strtrim(obj.user_data,2)
PRINT, ret
end
COMPILE_OPT IDL2
CD, current=c
f = FOLDERWATCH( c, 'MyCallback', user_data="HURRAY!", /RECURSIVE )
end
The example monitors the current working directory (and subdirectories) for all files and prints out what file has changed and how.
FolderWatch::Init
The FolderWatch::Init method initializes a FolderWatch object.
Note: Creation of a FolderWatch object automatically starts it.
Syntax
Obj = FolderWatch.Init( Folder, Callback [, /ADDED] [, /MODIFIED] [, /REMOVED] [, FREQUENCY=value] [/RECURSIVE] [, USER_DATA=variable] )
Return Value
Returns an object of type FolderWatch.
Arguments
Folder
A required string indicating the path of the folder to monitor.
Callback
A required string value specifying the name of the procedure that IDL should invoke when the specified event happens. The Callback is invoked each time a file changes (i.e., there is not just one Callback per time interval that contains an array of all of the changes that occurred, but instead, one per file change).
The callback must have the following signature:
PRO Name , Obj [, data]
|
Value |
Type |
Description |
|
Name
|
|
Name of the routine.
|
|
Obj
|
|
A reference to the FolderWatch object.
|
|
data
|
Structure
|
A required IDLFolderWatchInfo structure containing the following fields:
- file: a full-qualified path to the file that changed
- added: Boolean, set to 1 if the file was added.
- removed: Boolean, set to 1 if the file was removed.
- modified: Boolean, set to 1 if the file was modified.
Use to determine which file changed, and how.
|
|
|
|
|
Keywords
ADDED
Set this optional keyword in order to fire a Callback when a file has been added to the watch folder. If you do not specify ADDED, MODIFIED, or REMOVED, then all are set.
Note: If ADDED is specified, then MODIFIED and REMOVED are unset.
MODIFIED
Set this optional keyword in order to fire a Callback when a file has been modified in the watch folder. If you do not specify ADDED, MODIFIED, or REMOVED, then all are set.
Note: If MODIFIED is specified, then ADDED and REMOVED are unset.
REMOVED
Set this optional keyword in order to fire a Callback when a file has been removed from the watch folder. If you do not specify ADDED, MODIFIED, or REMOVED, then all are set.
Note: If REMOVED is specified, then ADDED and MODIFIED are unset.
FREQUENCY
Set this optional keyword to equal the number of seconds to wait before checking the folder for further changes in the files. Defaults to 1 and is a double-precision number.
RECURSIVE
Set this optional keyword to monitor all files in a directory and subdirectories. Defaults to no recursion.
USER_DATA
Optional data to be delivered to the Callback function. The delivered data will be a copy of the original. If USER_DATA is not supplied then the callback receives !NULL. USER_DATA can be any valid IDL value. Examples of valid IDL values include: a constant, variable, expression, an array, etc.
FolderWatch::Check
Use this method to force IDL to check the specified directory for changes.
Note: This does not start or stop a watch process on a folder.
Syntax
Obj.Check
Return Value
None.
Arguments
None.
Keywords
None.
FolderWatch::Start
Use this method to begin watching a folder.
Note: Creation of a FolderWatch object automatically starts it.
Syntax
Obj.Start
Return Value
None.
Arguments
None.
Keywords
None.
FolderWatch::Stop
Use this method to stop watching a specified folder.
Syntax
Obj.Stop
Return Value
None.
Arguments
None.
Keywords
None.
Version History