CDirectoryChangeWatcher

// DirectoryChanges.cpp: implementation of the CDirectoryChangeWatcher and CDirectoryChangeHandler classes. // /////////////////////////////////////////////////////////////////// /// /*********************************************************** Author: Wes Jones wesj@hotmail.com File: DirectoryChanges.cpp Latest Changes: 11/22/2001 -- Fixed bug causing file name's to be truncated if longer than 130 characters. Fixed CFileNotifyInformation::GetFileName() Thanks to Edric(uo_edric@hotmail.com) for pointing this out. Added code to enable process privileges when CDirectoryChangeWatcher::WatchDirectory() is first called. See docuementation API for ReadDirectoryChangesW() for more information of required privileges. Currently enables these privileges: (11/22/2001) SE_BACKUP_NAME SE_CHANGE_NOTIFY_NAME SE_RESTORE_NAME(02/09/2002) Implemented w/ helper class CPrivilegeEnabler. 11/23/2001 Added classes so that all notifications are handled by the same thread that called CDirectoryChangeWatcher::WatchDirectory(), ie: the main thread. CDirectoryChangeHandler::On_Filexxxx() functions are now called in the context of the main thread instead of the worker thread. This is good for two reasons: 1: The worker thread spends less time handling each notification. The worker thread simply passes the notification to the main thread, which does the processing. This means that each file change notification is handled as fast as possible and ReadDirectoryChangesW() can be called again to receive more notifications faster. 2: This makes it easier to make an ActiveX or ATL object with this class because the events that are fired, fire in the context of the main thread. The fact that I'm using a worker thread w/ this class is totally transparent to a client user. If I decide to turn this app into an ActiveX or ATL object I don't have to worry about wierd COM rules and multithreading issues, and neither does the client, be the client a VB app, C++ app, Delphi app, or whatever. Implemented with CDelayedDirectoryChangeHandler in DirectoryChangeHandler.h/.cpp 02/06/2002 Fixed a bug that would cause an application to hang. If ReadDirectoryChangesW was to fail during normal operation, the short story is that the application would hang when it called CDirectoryChangeWatcher::UnwatchDirectory(const CString & ) One way to reproduce this behavior on the old code is to watch a directory using a UNC path, and then change the IP address of that machine while the watch was running. Exitting the app after this would cause it to hang. Steps to reproduce it: 1) Assume that the computer running the code is named 'ThisComputer' and there is a shared folder named 'FolderName' 2) Start a watch on a folder using a UNC path: ie: \\ThisComputer\FolderName eg: CDirectoryChangeWatcher watcher; watcher.WatchDirectory(_T("\\\\ThisComputer\\FolderName",/ * other parameters * /) 3) Change the IP address of 'ThisComputer' ** ReadDirectoryChangesW() will fail some point after this. 4) Exit the application... it may hang. Anyways, that's what the bug fix is for. 02/06/2002 New side effects for CDirectoryChangeHandler::On_ReadDirectoryChangeError() If CDirectoryChangeHandler::On_ReadDirectoryChangeError() is ever executed the directory that you are watching will have been unwatched automatically due to the error condition. A call to CDirectoryChangeWatcher::IsWatchingDirectory() will fail because the directory is no longer being watched. You'll need to re-watch that directory. 02/09/2002 Added a parameter to CDirectoryChangeHandler::On_ReadDirectoryChangeError() Added the parameter: const CString & strDirectoryName The new signature is now: virtual void CDirectoryChangeHandler::On_ReadDirectoryChangeError(DWORD dwError, const CString & strDirectoryName); This new parameter gives you the name of the directory that the error occurred on. 04/25/2002 Provided a way to get around the requirement of a message pump. A console app can now use this w/out problems by passing false to the constructor of CDirectoryChangeWatcher. An app w/ a message pump can also pass false if it so desires w/out problems. 04/25/2002 Added two new virtual functions to CDirectoryChangeHandler Added: On_WatchStarted(DWORD dwError, const CString & strDirectoryName) On_WatchStopped(const CString & strDirectoryName); See header file for details. 04/27/2002 Added new function to CDirectoryChangeHandler: Added virtual bool On_FilterNotification(DWORD dwNotifyAction, LPCTSTR szFileName, LPCTSTR szNewFileName) This function is called before any notification function, and allows the CDirectoryChangeHandler derived class to ignore file notifications by performing a programmer defined test. By ignore, i mean that On_FileAdded(), On_FileRemoved(), On_FileModified(), or On_FileNameChanged() will NOT be called if this function returns false. The default implementation always returns true, signifying that ALL notifications are to be called. 04/27/2002 Added new Parameters to CDirectoryChangeWatcher::WatchDirectory() The new parameters are: LPCTSTR szIncludeFilter LPCTSTR szExcludeFilter Both parameters are defaulted to NULL. Signature is now: CDirectoryChangeWatcher::WatchDirectory(const CString & strDirToWatch, DWORD dwChangesToWatchFor, CDirectoryChangeHandler * pChangeHandler, BOOL bWatchSubDirs = FALSE, LPCTSTR szIncludeFilter = NULL, LPCTSTR szExcludeFilter = NULL) 04/27/2002 Added support for include and exclude filters. These filters allow you to receive notifications for just the files you want... ie: you can specify that you only want to receive notifications for changes to "*.txt" files or some other such file filter. NOTE: This feature is implemented w/ the PathMatchSpec() api function which is only available on NT4.0 if Internet Explorer 4.0 or above is installed. See MSDN for PathMatchSpec(). Win2000, and XP do not have to worry about it. Filter specifications: Accepts wild card characters * and ?, just as you're used to for the DOS dir command. It is possible to specify multiple extenstions in the filter by separating each filter spec with a semi-colon. eg: "*.txt;*.tmp;*.log" <-- this filter specifies all .txt, .tmp, & .log files Filters are passed as parameters to CDirectoryChangeWatcher::WatchDirectory() NOTE: The filters you specify take precedence over CDirectoryChangeHandler::On_FilterNotification(). This means that if the file name does not pass the filters that you specify when the watch is started, On_FilterNotification() will not be called. Filter specifications are case insensitive, ie: ".tmp" and ".TMP" are the same FILTER TYPES: Include Filter: If you specify an include filter, you are specifying that you only want to receive notifications for specific file types. eg: "*.log" means that you only want notifications for changes to files w/ an exention of ".log". Changes to ALL OTHER other file types are ignored. An empty, or not specified include filter means that you want notifications for changes of ALL