A Directory Monitor Class For Delphi

FILE_ACTION_ADDED	The file was added to the directory.
FILE_ACTION_REMOVED	The file was removed from the directory.
FILE_ACTION_MODIFIED	The file was modified. This can be a change in the time stamp or attributes.
FILE_ACTION_RENAMED_OLD_NAME	The file was renamed and this is the old name.
FILE_ACTION_RENAMED_NEW_NAME	The file was renamed and this is the new name.

Figure 2 - Possible values for the Action field.

The nBufferLength parameter is the size in bytes of lpBuffer.

The bWatchSubtree is a Boolean value that tells the function to watch sub-directories.

The dwNotifyFilter a bit mask that tells the function what events to look for. The values for this function are in figure 3.

Figure 3 - dwNotifyFilter options.

The lpBytesReturned parameter is the number of bytes written to the lpBuffer parameter when thefunction is used in synchronous calls. This parameter is undefined when the function is used in asynchronous calls (read on for more information on synchronous versus asynchronous calls).

The lpOverlapped parameter is a pointer to an TOverlapped record.

The lpCompletionRoutine parameter is a function pointer to an IO completion routine.  An IO completion routine prototype is defined in figure 4.

Figure 4 - An IO completion routine prototype.

Calling ReadDirectoryChangesW

There are two was to call ReadDirectoryChangesW, synchronous or asynchronous. As you might expect when calling ReadDirectoryChangesW synchronously it does not return until one of the events you are looking for happens. This is the easiest way to call ReadDirectoryChangesW but I have found it to be the least effective way to use the function.  I have included an example project that show how to use ReadDirectoryChangesW synchronously. The TDirectoryMonitor class uses the asynchronous method to call ReadDirectoryChangesW.

The TDirectoryMonitor class.

The TDirectoryMonitor class is described in figure 5. The TDirectoryMonitor class hides all of the details about ReadDirectoryChangesW from the caller.  The class exposes only two methods, four properties and one event. The two methods are Start and Stop. The Start method begins directory monitoring; the Stop method ends the monitoring. The properties are DirectoryToWatch, WatchSubFolders, Options, and WorkerThread. The DirectoryToWatch property defines the directory to watch.  The WatchSubFolder property defines if the class will notify the caller if an event occurs on a sub-directory.

Figure 5 – The TDirectoryMonitor Class.

The two less obvious properties are the OptionsOptions and the WorkerThread. The Options property is a set of TActionToWatch. TActionToWatch is an enumerated type that corresponds to the constants defined in figure  3. This property is not defaulted. It is left as an exercise for the reader to add defaults. The definition of TActionToWatch is shown in figure 6.

<pre>
TActionToWatch = (awChangeFileName,awChangeDirName,awChangeAttributes,awChangeSize,
awChangeLastWrite,awChangeLastAccess,awChangeCreation,awChangeSecurity);

TActionsToWatch = Set Of TActionToWatch;
</pre>

Figure 6 – TActionToWatch

The WorkerThread property is a class of TWorkerThread. TWorkerThread is a descendant of TThread. Why a thread? To explain that a fuller explanation of ReadDirectoryChangesW is needed. The ReadDirectoryChangesW function can be called one of two ways, synchronously or asynchronously. If called synchronously, the ReadDirectoryChangesW funcion doesn’t return until an event occurs. An asynchronous call the function return immediately and event notification is done through a completion port, a callback function, or overlapped I/O. To be able to receive these asynchronous notifications the thread that calls ReadDirectoryChangesW must be put in an alertable state. The up shot of both of these methods is that the calling thread is stopped until an event occurs. For a component to suspend the main thread is at best unexpected, at worst unacceptable. The WorkerThread takes care of this problem by creating a new thread outside the main thread. That way the main thread can continue while the worker thread waits for an event.

The Implementation

The implementation of the TDirectoryMonitor class begins with the TWorkerThread. As mentioned earlier the ReadDirectoryChangesW function can be called synchronously or asynchronously. The synchronous method is the easiest way to use ReadDirectoryChangesW, but there is a problem. The function will not return until an event occurs. This would mean the watch could not be terminated until after an event has occurred. For this reason the TWorkerThread uses the completion port asynchronous call. The completion port method allows the watch to be canceled by calling the PostQueuedCompletionStatus function. Microsoft also provides an example of the completion port option in MSDN. Examples of using ReadDirectoryChangesW synchronously and with a callback function are included in the examples file for this article available for download at my web site:http://www.biggbytesoftware.com/rod/ReadDirectoryChangesDownloads.html

There are two things to focus on in the TWorkerThread. The Create constructor and the Execute method. The TThread Create constructor needs to be replaced because the WorkerThread needs more information. The most obvious piece of information is which directory to monitor. This is passed as the PathToWatch parameter. The next thing the thread will need is to know what events the ReadDirectoryChangesW function will watch for. This is set in the ActionsToWatch parameter. The parameter ParentWindow requires some more explanation.

Since the ReadDirectoryChangesW function is called in a separate thread, the main thread must be notified when one of the events the class is watching for occurs. There are two options to make this notification. The first is to use the Synchronize method of the thread. This will in effect suspend the worker thread until the main thread is done processing the event. Using this method may result in the loss of events. The second option is to send a message to the main thread, but to send a message the worker thread must know where to send the message. That’s what the ParentWindow parameter is for. It is the handle of the window that will receive messages generated by the worker thread.

The last parameter is WatchSubFolders. This determines if the ReadDirectoryChangesW function monitors sub-directories of the PathToWatch parameter. The body of the create function assigns all of the parameters to private variables and opens a handle to the directory. The thread is created in a suspended state so there is time to complete all of the setup tasks. The Create constructor implementation is shown in figure 7.

<pre>
constructor TWorkerThread.Create(const PathToWatch: String; ActionsToWatch: TActionsToWatch;
ParentWindow: THandle; WatchSubFolders : Boolean);
begin
Inherited Create(True);
FWatchSubFolders := WatchSubFolders;
FPathToWatch := PathToWatch;
FActionsToWatch := ActionsToWatch;
FParentWindow := ParentWindow;
FNotifyMask := GetNotifyMask;
FDirHandle := CreateFile(PChar(FPathToWatch),
FILE_LIST_DIRECTORY,
FILE_SHARE_READ Or FILE_SHARE_WRITE Or FILE_SHARE_DELETE,
Nil, OPEN_EXISTING,
FILE_FLAG_BACKUP_SEMANTICS Or FILE_FLAG_OVERLAPPED,
0);
GetMem(FBuffer,MAX_BUFFER);
FBufferLength := MAX_BUFFER;
Resume;
end
</pre>

Figure 7 – The TWorkerThread Constructor

Once the constructor has resumed the thread, control is passed to the Execute method.  The first thing the Execute method does is open a completion port.  All file event notifications will come through this completion port.  The result buffer is cleared and ReadDirectoryChangesW is called.  After the call to ReadDirectoryChangesW the Execute method enters a Repeat loop and calls GetQueuedCompletionStatus. GetQueuedCompletionStatus will wait for an event and the loop will then call ReadDirectoryChangesW again to wait for the next event until the thread is either terminated or an empty buffer is returned.  The buffer is empty when the completion port is shutdown.

Now that the worker thread is completed attention turns to the implementation of the TDriectoryMonitor class itself. As in the TWorkerThread class the TDirectoryMonitor class replaces the ancestor constructor.  Then new constructor is shown in figure 8.  The main reason for this is so the TDirectoryMonitor can create a window handle to receive the message from the worker thread.  This handle is obtained by calling the AllocateHWnd function and passing the address of the message handler procedure for the allocated window.  In this case the message handler procedure is named InternalWinProc and is shown in figure 9.

<pre>
constructorTDirectoryMonitor.Create;
begin
Inherited Create;
FWindowHandle := AllocateHWnd(InternalWinProc);
FWatchSubFolders := True;
end;
</pre>

Figure 8 – The TDirectoryMonitor Constructor

<pre>
procedureTDirectoryMonitor.InternalWinProc(var Msg: TMessage);
Const
TranslateActions : <b'>Array[FILE_ACTION_ADDED..FILE_ACTION_RENAMED_NEW_NAME] Of TDirectoryAction =
(daFileAdded, daFileRemoved,daFileModified,daFileRenamedOldName,daFileRenamedNewName);
begin
If Msg.Msg = CM_DIRECTORY_EVENT Then
begin
If Assigned(FOnDirectoryChange) then
FOnDirectoryChange(Self,TranslateActions[Msg.wParam], String(Pchar(Msg.LParam)));
StrDispose(PChar(Msg.LParam));
end;
end
</pre>

Figure 9 – The internal winproc.

The next important method in the TDirecotryMonitor class is the Start method. The start method creates the worker thread that watches the directory in the DirectoryToWatch property. The Stop Method cancels the monitoring by posting the completion port with a zero (null) information value.

Using The TDirectoryMonitor Class.

Using the TDirectoryMonitor class requires five steps.
The first step is to create an instance of the class.  The create constructor requires no parameters, so this is familiar to users of TstringList and other classes.
The next step is to set what events to watch for.  This is done by setting the value of the property ActionsToWatch property.
The third step is to set the value of the DirectoryToWatch property. The directory specified must exist; the class will not create it, and setting this property to a directory that does not exist will cause an error when the worker thread calls CreateFile. 
The fourth step is to assign an event handler to the OnDirectoryChange event.  The OnDirectoryChange event handler is where the user will decide what to do when a file notification event occurs.  The OnDirectoryChange event has the following definition :

<pre>
procedure(Sender : TObject; Action : TDirectoryAction; FileName : String) Of Object;
</pre>

Sender is the instance of the class that caused the event.  Action describes what event occurred.  The possible values are described in figure 10. FileName is the name of the file the action occurred on.
The last step is to call the Start method.  A complete example program describing these steps is shown in figure 11 (also available for download at my web site http://www.biggbytesoftware.com/rod/ReadDirectoryChangesDownloads.html.

daFileAdded	The file in Filename has been added.
DaFileRemoved	The file has been deleted.
DaFileModified	The file has been changed.
DaFileRenamedOldName	The file has been renamed and FileName is the old file name.
DaFileRenamedNewName	The file has been renamed and FileName is the new file name.

Figure 10 – Action value descriptions.

<pre>
{$WARN UNIT_PLATFORM OFF}
unit DirectoryMonitorDemoU;

interface

uses
Windows, Messages, SysUtils, variants, Classes, Graphics, Controls, Forms,
Dialogs, StdCtrls, DirectoryMonitor;

type
TfrmDemo = class(TForm)
Button1: TButton;
Memo1: TMemo;
Button2: TButton;
procedure FormCreate(Sender: TObject);
procedure FormDestroy(Sender: TObject);
procedure Button1Click(Sender: TObject);
procedure Button2Click(Sender: TObject);
private
{ Private declarations }
FDirMon : TDirectoryMonitor;
procedure DirChange(Sender : TObject; Action : TDirectoryAction; FileName : String);
public
{ Public declarations }
end;

var
frmDemo: TfrmDemo;

implementation
Uses
FileCtrl;

{$R *.dfm}

procedure TfrmDemo.FormCreate(Sender: TObject);
begin
FDirMon := TDirectoryMonitor.Create;
FDirMon.OnDirectoryChange := DirChange;
FDirMon.Options := [awChangeFileName,awChangeDirName,awChangeSize,awChangeLastWrite];
end;

procedure TfrmDemo.FormDestroy(Sender: TObject);
begin
FDirMon.Free;
end;

procedure TfrmDemo.Button1Click(Sender: TObject);
var
S : String;
begin
SelectDirectory('Select A Directory To Monitor','',S);
If S <> '' Then
FDirMon.DirectoryToWatch := S;
FDirMon.Start;
end;

procedure TfrmDemo.Button2Click(Sender: TObject);
begin
FDirMon.Stop;
end;

procedure TfrmDemo.DirChange(Sender: TObject; Action: TDirectoryAction; FileName: String);
Const
ActionDesc : Array[TDirectoryAction] Of String =
('FILE_ACTION_ADDED. The file %s was added to the directory.',
'FILE_ACTION_REMOVED. The file %s was removed from the directory.',
'FILE_ACTION_MODIFIED. The file %s was modified.
'This can be a change in the time stamp or attributes.',
'FILE_ACTION_RENAMED_OLD_NAME. The file %s was renamed, and this is the old name.',
'FILE_ACTION_RENAMED_NEW_NAME The file %s was renamed and this is the new name.');

begin
Memo1.Lines.Add(Format(ActionDesc[Action],[FileName]));
end;

end.
</pre>

Figure 11 – A small sample program.

The Wrap Up

Monitoring a directory using ReadDirectoryChangesW can be a daunting task, but by wraping the complexity of it into an easy to use class I hope I have made the task a little less daunting.  BUT do take note, this class is not perfect nor was it meant to be. There needs to be more error handling and maybe some properties added before it would be production ready. I leave these things as an exercise for the reader.

About The Author
Rodney Holiman is a software developer and consultant specializing in Borland Delphi.