{{tag>category:"basic" category:"presentation server" }}

====== The DIRWATCHER control ======

=== Published 30 DEC 2021 at 07:06:18PM ===

With the release of version 10.1 a new control type called **DIRWATCHER** ("Directory Watcher") has been added to OpenInsight. This is a fairly simple control which allows you to monitor one or more directories on your system and then receive notifications when the contents are changed.

Using the control is very straightforward:

  * Use the **WATCHDIR** method to add a directory to monitor for changes.
  * Handle the **CHANGED** event to receive notifications of directory changes.
  * Use the **STOP** method to stop monitoring directories.

We'll take a quick look at each of these methods and events below along with a couple of important properties:

===== The WATCHDIR method =====

This method allows you to specify a directory to monitor along with some optional flags. It may be called multiple times to watch more than one directory.

<code wp-block-preformatted>
bSuccess = Exec_Method( CtrlEntID, "WATCHDIR", DirName, bSubtree, Flags )
</code>

|Parameter|Description                                                                                                                                                                                                                                                                                                                         |
|DirName  |(required) Specifies the name of the directory to watch. It should be a fully qualified, non-relative directory path.                                                                                                                                                                                                               |
|bSubtree |(optional) Set to TRUE$ to monitor all sub-directories beneath DirName as well. Defaults to FALSE$.                                                                                                                                                                                                                                 |
|Flags    |(optional) A bit-mask value containing a set of flags that denote the events to monitor in the directories. It defaults to the following flags:\\ \\ FILE_NOTIFY_CHANGE_FILE_NAME$\\ FILE_NOTIFY_CHANGE_LAST_WRITE$\\ FILE_NOTIFY_CHANGE_CREATION$\\ \\ The flag values are specified in the MSWIN_FILENOTIFY_EQUATES insert record,|


This method returns TRUE$ if successful, or FALSE$ otherwise.

===== The STOP method =====

This method stops the control monitoring its specified directories.

<code wp-block-preformatted>
bSuccess = Exec_Method( CtrlEntID, "STOP" )
</code>

This method returns TRUE$ if successful, or FALSE$ otherwise.

//(Note - to resume directory monitoring after the **STOP** method has been called the **WATCHDIR** method(s) must be executed again).//

===== The CHANGED event =====

This event is raised when changes have been detected in the monitored directories.

<code wp-block-preformatted>
bForward = CHANGED( NewData )
</code>

This event passes a single parameter called NewData which contains an @vm-delimited list of changed items (i.e. notifications). Each item in the list comprises an "action code" and the name and path of the affected file, delimited by an @svm.

Action codes are defined in the MSWIN_FILENOTIFY_EQUATES insert record like so:

<code wp-block-preformatted>
   equ FILE_ACTION_ADDED$               to 0x00000001   
   equ FILE_ACTION_REMOVED$             to 0x00000002   
   equ FILE_ACTION_MODIFIED$            to 0x00000003   
   equ FILE_ACTION_RENAMED_OLD_NAME$    to 0x00000004   
   equ FILE_ACTION_RENAMED_NEW_NAME$    to 0x00000005 
</code>

==== Remarks ====

If a monitored directory experiences a high volume of changes (such as copying or removing thousands of files) it could generate a correspondingly high number of **CHANGED** events, which in turn could produce an adverse affect on your application and slow it down. In order to deal with this potential issue it is possible to "bundle up" multiple notifications with the **NOTIFYTHRESHOLD** property into a single **CHANGED** event so they may be processed more efficiently.

===== The NOTIFYTHRESHOLD property =====

The **NOTIFYTHRESHOLD** property is an integer that specifies the //maximum number// of notifications that should be bundled before a **CHANGED** event is raised.

<code wp-block-preformatted>
CurrVal = Get_Property( CtrlEntID, "NOTIFYTHRESHOLD" )
PrevVal = Set_Property( CtrlEntID, "NOTIFYTHRESHOLD", NewVal )
</code>

By default it is set to 100.

===== The NOTIFYTIMER property =====

The **NOTIFYTIMER** property is an integer that specifies the number of milliseconds before a **CHANGED** event is raised if the **NOTIFYTHRESHOLD** property value is not met.

<code wp-block-preformatted>
CurrVal = Get_Property( CtrlEntID, "NOTIFYTIMER" )
PrevVal = Set_Property( CtrlEntID, "NOTIFYTIMER", NewVal )
</code>

By default it is set to 50 (ms).

==== Remarks ====

If the **NOTIFYTHRESHOLD** property is set to a value greater than 1 then the control will try to bundle that number of notifications together before raising a **CHANGED** event. However, when this is set to a high value it is possible that the threshold may not be reached in a timely fashion and the **CHANGED** event not actually raised.

//E.g. If the **NOTIFYTHRESHOLD** is set to 1000, and only 200 notifications are received then the **CHANGED** event would not be raised.//

To prevent this problem the **NOTIFYTIMER** property may be used to specify the amount of time after receiving the last notification before a **CHANGED** event is raised even if the **NOTIFYTHRESHOLD** is not met.

//E.g. in the example above, if the control had a **NOTIFYTIMER** of 50, then a **CHANGED** event would be raised 50ms after the last notification (200) was received, even though the **NOTIFYTHRESHOLD** of 1000 has not actually been met//.

===== Developer Notes =====

The **DIRWATCHER** control is intended as a "non-visual" control and should probably be hidden at runtime in your own applications. However, it is actually derived from a normal **STATIC** control so all of the properties and methods that apply to a **STATIC** apply to the **DIRWATCHER** as well, and you may use them as normal if you wish.




=== Comments ===





== Original ID: revdevx.com/?p=3646 ==