CBMonitor Class
Properties Methods Events Configuration Settings Errors
The CBMonitor class allows applications to monitor filesystem requests.
Syntax
cbfsfilter.Cbmonitor
Remarks
The CBMonitor class is a "monitoring-only" subset of the CBFilter class; it gives applications the ability to monitor filesystem requests, allowing them to be logged, reported, etc. Applications use standard filter rules to specify which requests they're interested in monitoring.
To learn more about the class's capabilities, please refer to the product's General Information topics.
Getting Started
- If the class's system driver hasn't been installed yet, call the Install method to do so. This only needs to be done once.
- In production, the driver can be installed (or updated) ahead-of-time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
- Call the Initialize method to initialize the CBMonitor class. This must be done each time the application starts.
- Add one or more filter rules using methods like AddFilterRule. (Rules can also be added/removed after the filter is started.)
- Call the StartFilter method to start monitoring filesystem requests.
- When finished, call the StopFilter method to stop monitoring filesystem requests.
- To uninstall the class's system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
- In production, the driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
Property List
The following is the full list of the properties of the class with short descriptions. Click on the links for further details.
| Active | Whether the class is active and processing requests. |
| Altitude | The altitude the class's system driver should use when operating in minifilter mode. |
| FilterMode | The filter mode the class's system driver should use. |
| FilterRules | Collection of filter rules. |
| FireVolumeEvents | The events that should be fired when a filesystem volume is mounted to or unmounted from the system. |
| PassthroughRules | Collection of passthrough rules. |
| ProcessCachedIORequests | Whether cached file read/write requests should be processed. |
| ProcessFailedRequests | Whether failed requests should be processed. |
| SerializeEvents | Whether events should be fired on a single worker thread, or many. |
| Tag | Stores application-defined data specific to this instance of the class. |
Method List
The following is the full list of the methods of the class with short descriptions. Click on the links for further details.
| AddFilterRule | Adds a standard filter rule. |
| AddFilterRuleEx | Adds a standard filter rule with additional match qualifiers. |
| AddPassthroughRule | Adds a passthrough rule. |
| AddPassthroughRuleEx | Adds a passthrough rule with additional match qualifiers. |
| Config | Sets or retrieves a configuration setting. |
| DeleteAllFilterRules | Deletes all standard filter rules. |
| DeleteAllPassthroughRules | Deletes all passthrough rules. |
| DeleteFilterRule | Deletes a particular standard filter rule. |
| DeletePassthroughRule | Deletes a particular passthrough rule. |
| FileMatchesMask | Checks whether a particular file or directory name matches the specified mask. |
| FlushNotificationQueue | Flushes the notification event queue. |
| GetDriverStatus | Retrieves the status of the class's system driver. |
| GetDriverVersion | Retrieves the version of the class's system driver. |
| GetOriginatorProcessId | Retrieves the Id of the process (PID) that initiated the operation. |
| GetOriginatorProcessName | Retrieves the name of the process that initiated the operation. |
| GetOriginatorThreadId | Retrieves the Id of the thread that initiated the operation. |
| GetVolumeGUID | Retrieves the volume GUID of the device targeted by a filesystem operation. |
| Initialize | Initializes the class. |
| Install | Installs (or upgrades) the class's system driver. |
| NtStatusToWin32Error | Converts a native status code to a Win32 error code. |
| ShutdownSystem | Shuts down or reboots the operating system. |
| StartFilter | Start filtering filesystem operations. |
| StopFilter | Stop filtering filesystem operations. |
| Uninstall | Uninstalls the class's system driver. |
Event List
The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.
| AfterFilterAttachToVolume | Fires after the filter attaches to a newly-mounted filesystem volume. |
| AfterFilterDetachFromVolume | Fires after the filter detaches from a filesystem volume. |
| BeforeFilterAttachToVolume | Fires before the filter attaches to a newly-mounted filesystem volume. |
| Error | Fires if an unhandled error occurs during an event. |
| FilterStart | Fires once the filter has attached and filtering has started. |
| FilterStop | Fires once filtering has stopped and the filter has detached. |
| NotifyCanFileBeDeleted | Fires when the OS marks a file or directory for deletion or removes such a mark. |
| NotifyCleanupFile | Fires when a file or directory handle has been closed. |
| NotifyCloseFile | Fires when a file or directory has been closed. |
| NotifyCreateFile | Fires when a file or directory has been created. |
| NotifyCreateHardLink | Fires when a hard link has been created. |
| NotifyDeleteFile | Fires when a file or directory has been deleted. |
| NotifyEnumerateDirectory | Fires when a directory entry has been returned during directory enumeration. |
| NotifyFilterAttachToVolume | Fires when the filter has been attached to a newly-mounted filesystem volume. |
| NotifyFilterDetachFromVolume | Fires when the filter has been detached from a filesystem volume. |
| NotifyFsctl | Fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred. |
| NotifyGetFileSecurity | Fires when a file or directory's security attributes have been retrieved. |
| NotifyGetFileSizes | Fires when a file's size information has been retrieved. |
| NotifyIoctl | Fires when an IRP_MJ_DEVICE_CONTROL operation has occurred. |
| NotifyLock | Fires when a range of bytes in a file has been locked. |
| NotifyOpenFile | Fires when a file or directory has been opened. |
| NotifyQueryFileInfo | Fires when information about a file or directory has been retrieved. |
| NotifyReadFile | Fires when data has been read from a file. |
| NotifyRenameOrMoveFile | Fires when a file or directory has been renamed or moved. |
| NotifySetAllocationSize | Fires when a file's allocation size has been changed. |
| NotifySetFileAttributes | Fires when a file or directory's attributes and/or times have been changed. |
| NotifySetFileInfo | Fires when information about a file or directory has been changed. |
| NotifySetFileSecurity | Fires when a file or directory's security attributes have been changed. |
| NotifySetFileSize | Fires when a file has been resized. |
| NotifyUnlockAll | Fires when all locked byte ranges in a file have been unlocked. |
| NotifyUnlockAllByKey | Fires when all locked byte ranges in a file, associated with a particular key, have been unlocked. |
| NotifyUnlockSingle | Fires when a particular locked byte range in a file has been unlocked. |
| NotifyWriteFile | Fires when data has been written to a file. |
| WorkerThreadCreation | Fires just after a new worker thread is created. |
| WorkerThreadTermination | Fires just before a worker thread is terminated. |
Configuration Settings
The following is a list of configuration settings for the class with short descriptions. Click on the links for further details.
| AlwaysPrepareFiles | Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the class is initialized. |
| FilterOwnRequests | Whether the class's system driver should filter requests made by the application itself. |
| ForceAppPermissionCheck | Whether the driver should require the controller process to have elevated or system privileges. |
| ForceSecurityChecks | Whether the driver should prevent the controller process from filtering files that it would not normally have access to. |
| LoggingEnabled | Whether extended logging is enabled. |
| MaxWorkerThreadCount | The maximum number of worker threads to use to fire events. |
| MinWorkerThreadCount | The minimum number of worker threads to use to fire events. |
| PreprocessedRulesCacheSize | Maximum number of preprocessed rules to keep cached. |
| ResolveNtDeviceToDriveLetter | Whether native device names are translated to drive letters. |
| SendRequestsViaDriverStack | Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers. |
| WorkerInitialStackSize | The initial stack size to create worker threads with. |
| BuildInfo | Information about the product's build. |
| LicenseInfo | Information about the current license. |