FOLDERWATCH

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

• FolderWatch::Init (Initialize a watch folder)
• FolderWatch::Check (Forces a check on a folder)
• FolderWatch::Start (Start watching a folder)
• FolderWatch::Stop (Stop watching a folder)

Example

This example monitors the files in the current working directory, and its subdirectories, and prints out which file has changed and how.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;;

;; Callback

;;

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

 

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

 

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

;;

;; MAIN

;;

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

 

COMPILE_OPT IDL2

 

; Get working directory

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

8.4	Introduced