CBMonitor Class

Properties   Methods   Events   Config Settings   Errors  

The CBMonitor class allows applications to monitor filesystem requests.

Syntax

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 and reported. Applications use standard filter rules to specify which requests they are interested in monitoring.

To learn more about the class's capabilities, please refer to the product's General Information topics.

Getting Started

1. If the class's system driver has not been installed yet, call the Install method to do so. This needs to be done only 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.
2. Call the Initialize method to initialize the CBMonitor class. This must be done each time the application starts.
3. Add one or more filter rules using methods like AddFilterRule. (Rules can also be added/removed after the filter is started.)
4. Call the StartFilter method to start monitoring filesystem requests.
5. When finished, call the StopFilter method to stop monitoring filesystem requests.
6. 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.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

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.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

Active Property (CBMonitor Class)

This property notes whether the class is active and processing requests.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int cbfsfilter_cbmonitor_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

This property reflects whether the class is active and currently processing requests. It will be true after the filter has been attached successfully via a call to StartFilter.

This property is read-only and not available at design time.

Data Type

Boolean

Altitude Property (CBMonitor Class)

This property specifies the altitude the class's system driver should use .

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetAltitude();
int SetAltitude(const char* lpszAltitude);

Unicode (Windows)
LPWSTR GetAltitude();
INT SetAltitude(LPCWSTR lpszAltitude);

char* cbfsfilter_cbmonitor_getaltitude(void* lpObj);
int cbfsfilter_cbmonitor_setaltitude(void* lpObj, const char* lpszAltitude);

QString GetAltitude();
int SetAltitude(QString qsAltitude);

Default Value

""

Remarks

This property specifies the altitude that the class's system driver should use . A driver's altitude determines its absolute position in the stack of filter drivers; drivers with higher altitudes are attached toward the top of the stack, closer to the user mode, which allows them to process requests earlier.

Microsoft manages and assigns filesystem minifilter driver altitudes directly, so an application-specific altitude value must be obtained from Microsoft before an application is deployed in production. Please refer to the Driver Altitudes topic for more information. During development, an appropriate arbitrary value, such as 360000 (which is not registered with Microsoft), can be used.

If this property is queried before an altitude has been set (via this property or the Install method), it will return an empty string.

Note: This property cannot be changed when Active is true. Additionally, the Initialize method must be called before attempting to get or set this property's value, which is stored in the registry.

Data Type

String

FilterRuleCount Property (CBMonitor Class)

The number of records in the FilterRule arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFilterRuleCount();

Unicode (Windows)
INT GetFilterRuleCount();

int cbfsfilter_cbmonitor_getfilterrulecount(void* lpObj);

int GetFilterRuleCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• FilterRuleAccessFlags
• FilterRuleControlFlags
• FilterRuleEaName
• FilterRuleExcludedAttributes
• FilterRuleIncludedAttributes
• FilterRuleMask
• FilterRuleMaxSize
• FilterRuleMinSize
• FilterRuleNotifyFlags

The array indices start at 0 and end at FilterRuleCount - 1.

This property is read-only and not available at design time.

Data Type

Integer

FilterRuleAccessFlags Property (CBMonitor Class)

This property indicates the access restrictions enforced by the rule (CBFilter only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFilterRuleAccessFlags(int iFilterRuleIndex);

Unicode (Windows)
INT GetFilterRuleAccessFlags(INT iFilterRuleIndex);

int cbfsfilter_cbmonitor_getfilterruleaccessflags(void* lpObj, int filterruleindex);

int GetFilterRuleAccessFlags(int iFilterRuleIndex);

Default Value

0

Remarks

This property indicates the access restrictions enforced by the rule (CBFilter only).

This property indicates which access restrictions are enforced by the rule. Please refer to the Access Rules topic for more information. The value of this property is a combination of zero or more of the following:

Note: This property is always 0 for the CBMonitor class, which does not support access rules.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

Integer

FilterRuleControlFlags Property (CBMonitor Class)

This property indicates which control events the rule causes the class to fire (CBFilter only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetFilterRuleControlFlags(int iFilterRuleIndex);

Unicode (Windows)
LONG64 GetFilterRuleControlFlags(INT iFilterRuleIndex);

int64 cbfsfilter_cbmonitor_getfilterrulecontrolflags(void* lpObj, int filterruleindex);

qint64 GetFilterRuleControlFlags(int iFilterRuleIndex);

Default Value

0

Remarks

This property indicates which control events the rule causes the class to fire (CBFilter only).

This property indicates which filesystem operations, of those performed on matching files and directories, the class should fire Control Events for. The value of this property is a combination of zero or more of the following:

Note: This property is always 0 for the CBMonitor class, which does not provide any Control Events for filesystem operations.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

FilterRuleEaName Property (CBMonitor Class)

This property indicates the name of an extended attribute that a file or directory must have to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFilterRuleEaName(int iFilterRuleIndex);

Unicode (Windows)
LPWSTR GetFilterRuleEaName(INT iFilterRuleIndex);

char* cbfsfilter_cbmonitor_getfilterruleeaname(void* lpObj, int filterruleindex);

QString GetFilterRuleEaName(int iFilterRuleIndex);

Default Value

""

Remarks

This property indicates the name of an extended attribute that a file or directory must have to match the rule.

This property reflects the name of an extended attribute that a file or directory must have to qualify as a match for the rule. A value of an empty string indicates that the rule does not use this property as a match qualifier.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

String

FilterRuleExcludedAttributes Property (CBMonitor Class)

This property indicates the file attributes that a file or directory must not have to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetFilterRuleExcludedAttributes(int iFilterRuleIndex);

Unicode (Windows)
LONG64 GetFilterRuleExcludedAttributes(INT iFilterRuleIndex);

int64 cbfsfilter_cbmonitor_getfilterruleexcludedattributes(void* lpObj, int filterruleindex);

qint64 GetFilterRuleExcludedAttributes(int iFilterRuleIndex);

Default Value

0

Remarks

This property indicates the file attributes that a file or directory must not have to match the rule.

This property indicates which file attributes a file or directory must not have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this property as a match qualifier.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

FilterRuleIncludedAttributes Property (CBMonitor Class)

This property indicates the file attributes that a file or directory must have to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetFilterRuleIncludedAttributes(int iFilterRuleIndex);

Unicode (Windows)
LONG64 GetFilterRuleIncludedAttributes(INT iFilterRuleIndex);

int64 cbfsfilter_cbmonitor_getfilterruleincludedattributes(void* lpObj, int filterruleindex);

qint64 GetFilterRuleIncludedAttributes(int iFilterRuleIndex);

Default Value

0

Remarks

This property indicates the file attributes that a file or directory must have to match the rule.

This property indicates which file attributes a file or directory must have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this property as a match qualifier.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

FilterRuleMask Property (CBMonitor Class)

This property indicates a file mask that determines which files and directories match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetFilterRuleMask(int iFilterRuleIndex);

Unicode (Windows)
LPWSTR GetFilterRuleMask(INT iFilterRuleIndex);

char* cbfsfilter_cbmonitor_getfilterrulemask(void* lpObj, int filterruleindex);

QString GetFilterRuleMask(int iFilterRuleIndex);

Default Value

""

Remarks

This property indicates a file mask that determines which files and directories match the rule.

This property reflects the file mask used to determine whether a file or directory matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

Note: When a rule with a drive letter is added, said drive letter is automatically converted to NT Device format. When the ResolveNtDeviceToDriveLetter configuration setting is disabled, this property's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the class attempts to convert the mask back to the DOS format with a drive letter. In some situations, such backward conversion can lead to a path that was different from the original path added.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

String

FilterRuleMaxSize Property (CBMonitor Class)

This property indicates the maximum size a file can be to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetFilterRuleMaxSize(int iFilterRuleIndex);

Unicode (Windows)
LONG64 GetFilterRuleMaxSize(INT iFilterRuleIndex);

int64 cbfsfilter_cbmonitor_getfilterrulemaxsize(void* lpObj, int filterruleindex);

qint64 GetFilterRuleMaxSize(int iFilterRuleIndex);

Default Value

0

Remarks

This property indicates the maximum size a file can be to match the rule.

This property indicates the maximum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this property as a match qualifier.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

FilterRuleMinSize Property (CBMonitor Class)

This property indicates the minimum size a file can be to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetFilterRuleMinSize(int iFilterRuleIndex);

Unicode (Windows)
LONG64 GetFilterRuleMinSize(INT iFilterRuleIndex);

int64 cbfsfilter_cbmonitor_getfilterruleminsize(void* lpObj, int filterruleindex);

qint64 GetFilterRuleMinSize(int iFilterRuleIndex);

Default Value

0

Remarks

This property indicates the minimum size a file can be to match the rule.

This property indicates the minimum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this property as a match qualifier.

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

FilterRuleNotifyFlags Property (CBMonitor Class)

This property indicates which notification events the rule causes the class to fire.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetFilterRuleNotifyFlags(int iFilterRuleIndex);

Unicode (Windows)
LONG64 GetFilterRuleNotifyFlags(INT iFilterRuleIndex);

int64 cbfsfilter_cbmonitor_getfilterrulenotifyflags(void* lpObj, int filterruleindex);

qint64 GetFilterRuleNotifyFlags(int iFilterRuleIndex);

Default Value

0

Remarks

This property indicates which notification events the rule causes the class to fire.

This property indicates which filesystem operations, of those performed on matching files and directories, the class should fire Notification Events for. The value of this property is a combination of zero or more of the following:

The FilterRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the FilterRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

FireVolumeEvents Property (CBMonitor Class)

This property specifies the events that should be fired when a filesystem volume is mounted to or unmounted from the system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetFireVolumeEvents();
int SetFireVolumeEvents(int iFireVolumeEvents);

Unicode (Windows)
INT GetFireVolumeEvents();
INT SetFireVolumeEvents(INT iFireVolumeEvents);

int cbfsfilter_cbmonitor_getfirevolumeevents(void* lpObj);
int cbfsfilter_cbmonitor_setfirevolumeevents(void* lpObj, int iFireVolumeEvents);

int GetFireVolumeEvents();
int SetFireVolumeEvents(int iFireVolumeEvents);

Default Value

0

Remarks

This property specifies the events that the class should fire when a filesystem volume is mounted to or unmounted from the system. Possible values are as follows:

Note: The aforementioned events are fired only for volumes mounted/unmounted after the StartFilter method is called. Typically, applications use these events to dynamically add or remove volume-specific filter rules that target removable volumes (e.g., USB drives) as well as to create virtual files on such volumes. Please refer to the File Masks topic for more information.

Data Type

Integer

PassthroughRuleCount Property (CBMonitor Class)

The number of records in the PassthroughRule arrays.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPassthroughRuleCount();

Unicode (Windows)
INT GetPassthroughRuleCount();

int cbfsfilter_cbmonitor_getpassthroughrulecount(void* lpObj);

int GetPassthroughRuleCount();

Default Value

0

Remarks

This property controls the size of the following arrays:

• PassthroughRuleAccessFlags
• PassthroughRuleControlFlags
• PassthroughRuleEaName
• PassthroughRuleExcludedAttributes
• PassthroughRuleIncludedAttributes
• PassthroughRuleMask
• PassthroughRuleMaxSize
• PassthroughRuleMinSize
• PassthroughRuleNotifyFlags

The array indices start at 0 and end at PassthroughRuleCount - 1.

This property is read-only and not available at design time.

Data Type

Integer

PassthroughRuleAccessFlags Property (CBMonitor Class)

This property specifies the access restrictions lifted by the rule (CBFilter only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetPassthroughRuleAccessFlags(int iPassthroughRuleIndex);

Unicode (Windows)
INT GetPassthroughRuleAccessFlags(INT iPassthroughRuleIndex);

int cbfsfilter_cbmonitor_getpassthroughruleaccessflags(void* lpObj, int passthroughruleindex);

int GetPassthroughRuleAccessFlags(int iPassthroughRuleIndex);

Default Value

0

Remarks

This property specifies the access restrictions lifted by the rule (CBFilter only).

This property indicates which access restrictions are lifted by the rule. Please refer to the Passthrough Rules topic for more information. The value of this property is a combination of zero or more of the following:

Note: This property is always 0 for the CBMonitor class, which does not support access rules.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

Integer

PassthroughRuleControlFlags Property (CBMonitor Class)

This property indicates which control events the rule prevents the class from firing (CBFilter only).

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetPassthroughRuleControlFlags(int iPassthroughRuleIndex);

Unicode (Windows)
LONG64 GetPassthroughRuleControlFlags(INT iPassthroughRuleIndex);

int64 cbfsfilter_cbmonitor_getpassthroughrulecontrolflags(void* lpObj, int passthroughruleindex);

qint64 GetPassthroughRuleControlFlags(int iPassthroughRuleIndex);

Default Value

0

Remarks

This property indicates which control events the rule prevents the class from firing (CBFilter only).

This property indicates which filesystem operations, of those performed on matching files and directories, the class should not fire Control Events for. Please refer to the Passthrough Rules topic for more information. The value of this property is a combination of zero or more of the following:

Note: This property is always 0 for the CBMonitor class, which does not provide any Control Events for filesystem operations.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

PassthroughRuleEaName Property (CBMonitor Class)

This property indicates the name of an extended attribute that a file or directory must have to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPassthroughRuleEaName(int iPassthroughRuleIndex);

Unicode (Windows)
LPWSTR GetPassthroughRuleEaName(INT iPassthroughRuleIndex);

char* cbfsfilter_cbmonitor_getpassthroughruleeaname(void* lpObj, int passthroughruleindex);

QString GetPassthroughRuleEaName(int iPassthroughRuleIndex);

Default Value

""

Remarks

This property indicates the name of an extended attribute that a file or directory must have to match the rule.

This property reflects the name of an extended attribute that a file or directory must have to qualify as a match for the rule. A value of an empty string indicates that the rule does not use this property as a match qualifier.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

String

PassthroughRuleExcludedAttributes Property (CBMonitor Class)

This property indicates the file attributes that a file or directory must not have to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetPassthroughRuleExcludedAttributes(int iPassthroughRuleIndex);

Unicode (Windows)
LONG64 GetPassthroughRuleExcludedAttributes(INT iPassthroughRuleIndex);

int64 cbfsfilter_cbmonitor_getpassthroughruleexcludedattributes(void* lpObj, int passthroughruleindex);

qint64 GetPassthroughRuleExcludedAttributes(int iPassthroughRuleIndex);

Default Value

0

Remarks

This property indicates the file attributes that a file or directory must not have to match the rule.

This property indicates which file attributes a file or directory must not have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this property as a match qualifier.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

PassthroughRuleIncludedAttributes Property (CBMonitor Class)

This property indicates the file attributes that a file or directory must have to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetPassthroughRuleIncludedAttributes(int iPassthroughRuleIndex);

Unicode (Windows)
LONG64 GetPassthroughRuleIncludedAttributes(INT iPassthroughRuleIndex);

int64 cbfsfilter_cbmonitor_getpassthroughruleincludedattributes(void* lpObj, int passthroughruleindex);

qint64 GetPassthroughRuleIncludedAttributes(int iPassthroughRuleIndex);

Default Value

0

Remarks

This property indicates the file attributes that a file or directory must have to match the rule.

This property indicates which file attributes a file or directory must have to qualify as a match for the rule. A value of 0 indicates that the rule does not use this property as a match qualifier.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

PassthroughRuleMask Property (CBMonitor Class)

This property indicates a file mask that determines which files and directories match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetPassthroughRuleMask(int iPassthroughRuleIndex);

Unicode (Windows)
LPWSTR GetPassthroughRuleMask(INT iPassthroughRuleIndex);

char* cbfsfilter_cbmonitor_getpassthroughrulemask(void* lpObj, int passthroughruleindex);

QString GetPassthroughRuleMask(int iPassthroughRuleIndex);

Default Value

""

Remarks

This property indicates a file mask that determines which files and directories match the rule.

This property reflects the file mask used to determine whether a file or directory matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

Note: When a rule with a drive letter is added, said drive letter is automatically converted to NT Device format. When the ResolveNtDeviceToDriveLetter configuration setting is disabled, this property's value will contain the NT Device name. When the ResolveNtDeviceToDriveLetter configuration setting is enabled, the class attempts to convert the mask back to the DOS format with a drive letter. In some situations, such backward conversion can lead to a path that was different from the original path added.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

String

PassthroughRuleMaxSize Property (CBMonitor Class)

This property indicates the maximum size a file can be to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetPassthroughRuleMaxSize(int iPassthroughRuleIndex);

Unicode (Windows)
LONG64 GetPassthroughRuleMaxSize(INT iPassthroughRuleIndex);

int64 cbfsfilter_cbmonitor_getpassthroughrulemaxsize(void* lpObj, int passthroughruleindex);

qint64 GetPassthroughRuleMaxSize(int iPassthroughRuleIndex);

Default Value

0

Remarks

This property indicates the maximum size a file can be to match the rule.

This property indicates the maximum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this property as a match qualifier.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

PassthroughRuleMinSize Property (CBMonitor Class)

This property indicates the minimum size a file can be to match the rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetPassthroughRuleMinSize(int iPassthroughRuleIndex);

Unicode (Windows)
LONG64 GetPassthroughRuleMinSize(INT iPassthroughRuleIndex);

int64 cbfsfilter_cbmonitor_getpassthroughruleminsize(void* lpObj, int passthroughruleindex);

qint64 GetPassthroughRuleMinSize(int iPassthroughRuleIndex);

Default Value

0

Remarks

This property indicates the minimum size a file can be to match the rule.

This property indicates the minimum size, in bytes, that a file can be to qualify as a match for the rule. A value of -1 indicates that the rule does not use this property as a match qualifier.

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

PassthroughRuleNotifyFlags Property (CBMonitor Class)

This property indicates which notification events the rule prevents the class from firing.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetPassthroughRuleNotifyFlags(int iPassthroughRuleIndex);

Unicode (Windows)
LONG64 GetPassthroughRuleNotifyFlags(INT iPassthroughRuleIndex);

int64 cbfsfilter_cbmonitor_getpassthroughrulenotifyflags(void* lpObj, int passthroughruleindex);

qint64 GetPassthroughRuleNotifyFlags(int iPassthroughRuleIndex);

Default Value

0

Remarks

This property indicates which notification events the rule prevents the class from firing.

This property indicates which filesystem operations, of those performed on matching files and directories, the class should not fire Notification Events for. Please refer to the Passthrough Rules topic for more information. The value of this property is a combination of zero or more of the following:

The PassthroughRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the PassthroughRuleCount property.

This property is read-only and not available at design time.

Data Type

Long64

ProcessCachedIORequests Property (CBMonitor Class)

This property specifies whether cached file read/write requests should be processed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProcessCachedIORequests();
int SetProcessCachedIORequests(int bProcessCachedIORequests);

Unicode (Windows)
BOOL GetProcessCachedIORequests();
INT SetProcessCachedIORequests(BOOL bProcessCachedIORequests);

int cbfsfilter_cbmonitor_getprocesscachediorequests(void* lpObj);
int cbfsfilter_cbmonitor_setprocesscachediorequests(void* lpObj, int bProcessCachedIORequests);

bool GetProcessCachedIORequests();
int SetProcessCachedIORequests(bool bProcessCachedIORequests);

Default Value

FALSE

Remarks

This property specifies whether the class's system driver should process cached file read/write requests (i.e., fire *ReadFile and *WriteFile events for them). Please refer to the Cached and Non-Cached Requests topic for more information.

Note: This property cannot be changed when Active is true.

Data Type

Boolean

ProcessFailedRequests Property (CBMonitor Class)

This property specifies whether failed requests should be processed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetProcessFailedRequests();
int SetProcessFailedRequests(int bProcessFailedRequests);

Unicode (Windows)
BOOL GetProcessFailedRequests();
INT SetProcessFailedRequests(BOOL bProcessFailedRequests);

int cbfsfilter_cbmonitor_getprocessfailedrequests(void* lpObj);
int cbfsfilter_cbmonitor_setprocessfailedrequests(void* lpObj, int bProcessFailedRequests);

bool GetProcessFailedRequests();
int SetProcessFailedRequests(bool bProcessFailedRequests);

Default Value

FALSE

Remarks

This property specifies whether the class's system driver should process failed requests (i.e., fire After* or Notify* events for them).

When this property is enabled, applications can inspect the Status parameter of the aforementioned events to determine whether an operation has failed. If an operation fails, then the corresponding event's Status parameter will contain a nonzero native status code. Applications generally can use the NtStatusToWin32Error method to convert these status codes into Win32 error codes (but keep in mind that not all native status codes have direct Win32 error code mapping).

Data Type

Boolean

SerializeEvents Property (CBMonitor Class)

Whether events should be fired on a single worker thread, or many.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Unicode (Windows)
INT GetSerializeEvents();
INT SetSerializeEvents(INT iSerializeEvents);

SE_ON_MULTIPLE_THREADS(0), 
SE_ON_ONE_WORKER_THREAD(1)

int cbfsfilter_cbmonitor_getserializeevents(void* lpObj);
int cbfsfilter_cbmonitor_setserializeevents(void* lpObj, int iSerializeEvents);

int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Default Value

0

Remarks

This property specifies whether the class should fire all events serially on a single worker thread, or concurrently on multiple worker threads. The possible values are:

Please refer to the Threading and Concurrency topic for more information.

Note: This property cannot be changed when Active is true, and it cannot be changed within events.

Data Type

Integer

Tag Property (CBMonitor Class)

This property stores application-defined data specific to a particular instance of the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetTag();
int SetTag(int64 lTag);

Unicode (Windows)
LONG64 GetTag();
INT SetTag(LONG64 lTag);

int64 cbfsfilter_cbmonitor_gettag(void* lpObj);
int cbfsfilter_cbmonitor_settag(void* lpObj, int64 lTag);

qint64 GetTag();
int SetTag(qint64 lTag);

Default Value

0

Remarks

This property can be used to store data specific to a particular instance of the class.

Data Type

Long64

AddFilterRule Method (CBMonitor Class)

This method adds a standard filter rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddFilterRule(const char* lpszMask, int64 lNotifyFlags);

Unicode (Windows)
INT AddFilterRule(LPCWSTR lpszMask, LONG64 lNotifyFlags);

int cbfsfilter_cbmonitor_addfilterrule(void* lpObj, const char* lpszMask, int64 lNotifyFlags);

bool AddFilterRule(const QString& qsMask, qint64 lNotifyFlags);

Remarks

This method adds a standard filter rule for the files and directories that match the specified Mask. Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it.

If the rule is added successfully, this method returns true; otherwise, it returns false.

Standard filter rules determine which filesystem operations, of those performed on matching files and directories, the class should fire its events for.

The Mask parameter must be a valid file mask according to the File Masks topic. Only the files and directories that match the specified mask will be covered by the rule.

The NotifyFlags parameter specifies which filesystem operations the class should fire Notification Events for. For example, if the FS_NE_READ flag is present, the NotifyReadFile event will fire after a read operation is performed on any file that matches Mask. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddFilterRuleEx Method (CBMonitor Class)

This method adds a standard filter rule with additional match qualifiers.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddFilterRuleEx(const char* lpszMask, const char* lpszEaName, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);

Unicode (Windows)
INT AddFilterRuleEx(LPCWSTR lpszMask, LPCWSTR lpszEaName, LONG64 lNotifyFlags, LONG64 lMinSize, LONG64 lMaxSize, LONG64 lIncludedAttributes, LONG64 lExcludedAttributes);

int cbfsfilter_cbmonitor_addfilterruleex(void* lpObj, const char* lpszMask, const char* lpszEaName, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);

bool AddFilterRuleEx(const QString& qsMask, const QString& qsEaName, qint64 lNotifyFlags, qint64 lMinSize, qint64 lMaxSize, qint64 lIncludedAttributes, qint64 lExcludedAttributes);

Remarks

This method adds a standard filter rule for the files and directories that match the specified Mask (which must be provided) and other qualifiers (which are optional). Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it.

If the rule is added successfully, this method returns true; otherwise, it returns false.

Standard filter rules determine which filesystem operations, of those performed on matching files and directories, the class should fire its events for.

The Mask parameter must be a valid file mask according to the File Masks topic. Only the files and directories that match the specified mask will be covered by the rule.

The EaName parameter specifies the name of an extended attribute that a file or directory must have to qualify as a match; wildcards are not allowed. Pass an empty string if this parameter should not be used as a match qualifier.

The NotifyFlags parameter specifies which filesystem operations the class should fire Notification Events for. For example, if the FS_NE_READ flag is present, the NotifyReadFile event will fire after a read operation is performed on any file that matches Mask. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

The MinSize and MaxSize parameters specify the minimum and maximum size, in bytes, that a file can be to qualify as a match. Pass -1 for either parameter if it should not be used as a match qualifier.

The IncludedAttributes and ExcludedAttributes parameters specify which file attributes a file or directory must have or not have to qualify as a match. Pass 0 for either parameter if it should not be used as a match qualifier.

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddPassthroughRule Method (CBMonitor Class)

This method adds a passthrough rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddPassthroughRule(const char* lpszMask, int64 lNotifyFlags);

Unicode (Windows)
INT AddPassthroughRule(LPCWSTR lpszMask, LONG64 lNotifyFlags);

int cbfsfilter_cbmonitor_addpassthroughrule(void* lpObj, const char* lpszMask, int64 lNotifyFlags);

bool AddPassthroughRule(const QString& qsMask, qint64 lNotifyFlags);

Remarks

This method adds a passthrough rule for the files and directories that match the specified Mask. Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it.

If the rule is added successfully, this method returns true; otherwise, it returns false.

Passthrough rules exclude matching files and directories from being processed by other filter rules.

The Mask parameter must be a valid file mask according to the File Masks topic. Only the files and directories that match the specified mask will be covered by the rule.

The NotifyFlags parameter specifies which filesystem operations the class should not fire Notification Events for. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AddPassthroughRuleEx Method (CBMonitor Class)

This method adds a passthrough rule with additional match qualifiers.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int AddPassthroughRuleEx(const char* lpszMask, const char* lpszEaName, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);

Unicode (Windows)
INT AddPassthroughRuleEx(LPCWSTR lpszMask, LPCWSTR lpszEaName, LONG64 lNotifyFlags, LONG64 lMinSize, LONG64 lMaxSize, LONG64 lIncludedAttributes, LONG64 lExcludedAttributes);

int cbfsfilter_cbmonitor_addpassthroughruleex(void* lpObj, const char* lpszMask, const char* lpszEaName, int64 lNotifyFlags, int64 lMinSize, int64 lMaxSize, int64 lIncludedAttributes, int64 lExcludedAttributes);

bool AddPassthroughRuleEx(const QString& qsMask, const QString& qsEaName, qint64 lNotifyFlags, qint64 lMinSize, qint64 lMaxSize, qint64 lIncludedAttributes, qint64 lExcludedAttributes);

Remarks

This method adds a passthrough rule for the files and directories that match the specified Mask (which must be provided) and other qualifiers (which are optional). Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it.

If the rule is added successfully, this method returns true; otherwise, it returns false.

Passthrough rules exclude matching files and directories from being processed by other filter rules.

The Mask parameter must be a valid file mask according to the File Masks topic. Only the files and directories that match the specified mask will be covered by the rule.

The EaName parameter specifies the name of an extended attribute that a file or directory must have to qualify as a match; wildcards are not allowed. Pass an empty string if this parameter should not be used as a match qualifier.

The NotifyFlags parameter specifies which filesystem operations the class should not fire Notification Events for. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

The MinSize and MaxSize parameters specify the minimum and maximum size, in bytes, that a file can be to qualify as a match. Pass -1 for either parameter if it should not be used as a match qualifier.

The IncludedAttributes and ExcludedAttributes parameters specify which file attributes a file or directory must have or not have to qualify as a match. Pass 0 for either parameter if it should not be used as a match qualifier.

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Config Method (CBMonitor Class)

Sets or retrieves a configuration setting.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* Config(const char* lpszConfigurationString);

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

char* cbfsfilter_cbmonitor_config(void* lpObj, const char* lpszConfigurationString);

QString Config(const QString& qsConfigurationString);

Remarks

Config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the Config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteAllFilterRules Method (CBMonitor Class)

This method deletes all standard filter rules.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteAllFilterRules();

Unicode (Windows)
INT DeleteAllFilterRules();

int cbfsfilter_cbmonitor_deleteallfilterrules(void* lpObj);

bool DeleteAllFilterRules();

Remarks

This method deletes all standard filter rules that are currently present.

If the rules are deleted successfully, this method returns true; otherwise, it returns false.

To delete standard filter rules individually, use the DeleteFilterRule method instead.

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteAllPassthroughRules Method (CBMonitor Class)

This method deletes all passthrough rules.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteAllPassthroughRules();

Unicode (Windows)
INT DeleteAllPassthroughRules();

int cbfsfilter_cbmonitor_deleteallpassthroughrules(void* lpObj);

bool DeleteAllPassthroughRules();

Remarks

This method deletes all passthrough rules that are currently present.

If the rules are deleted successfully, this method returns true; otherwise, it returns false.

To delete passthrough rules individually, use the DeletePassthroughRule method instead.

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeleteFilterRule Method (CBMonitor Class)

This method deletes a particular standard filter rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeleteFilterRule(const char* lpszMask, int64 lNotifyFlags);

Unicode (Windows)
INT DeleteFilterRule(LPCWSTR lpszMask, LONG64 lNotifyFlags);

int cbfsfilter_cbmonitor_deletefilterrule(void* lpObj, const char* lpszMask, int64 lNotifyFlags);

bool DeleteFilterRule(const QString& qsMask, qint64 lNotifyFlags);

Remarks

This method deletes the specified NotifyFlags from the standard filter rule identified by Mask. If NotifyFlags includes all flags currently present in the rule, then the entire rule is deleted; otherwise, the flags specified by NotifyFlags are simply removed from the rule. If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the file mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The NotifyFlags parameter specifies which Notification Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

To delete all standard filter rules, use the DeleteAllFilterRules method instead.

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

DeletePassthroughRule Method (CBMonitor Class)

This method deletes a particular passthrough rule.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int DeletePassthroughRule(const char* lpszMask, int64 lNotifyFlags);

Unicode (Windows)
INT DeletePassthroughRule(LPCWSTR lpszMask, LONG64 lNotifyFlags);

int cbfsfilter_cbmonitor_deletepassthroughrule(void* lpObj, const char* lpszMask, int64 lNotifyFlags);

bool DeletePassthroughRule(const QString& qsMask, qint64 lNotifyFlags);

Remarks

This method deletes the specified NotifyFlags from the passthrough rule identified by Mask. If NotifyFlags includes all flags currently present in the rule, then the entire rule is deleted; otherwise, the flags specified by NotifyFlags are simply removed from the rule. If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the file mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The NotifyFlags parameter specifies which Notification Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

To delete all passthrough rules, use the DeleteAllPassthroughRules method instead.

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

FileMatchesMask Method (CBMonitor Class)

This method checks whether a particular file or directory name matches the specified mask.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int FileMatchesMask(const char* lpszMask, const char* lpszFileName, int bCaseSensitive);

Unicode (Windows)
INT FileMatchesMask(LPCWSTR lpszMask, LPCWSTR lpszFileName, BOOL bCaseSensitive);

int cbfsfilter_cbmonitor_filematchesmask(void* lpObj, const char* lpszMask, const char* lpszFileName, int bCaseSensitive);

bool FileMatchesMask(const QString& qsMask, const QString& qsFileName, bool bCaseSensitive);

Remarks

This method checks whether the file or directory name specified by FileName matches Mask; if it does, this method returns true. The CaseSensitive parameter controls whether a case-sensitive match should be performed.

Note: This method does not handle so-called DOS_* wildcards (DOS_STAR, DOS_QM, DOS_DOT). The explanation about the characters can be found in the MSDN article. If you have a mask that includes one of those characters on Windows, you can use the RtlIsNameInExpression function of Windows API.

Note: As the explanation states, "When you do a case-insensitive search and do not provide a translation table, the name is converted to uppercase."

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDOSPathName Method (CBMonitor Class)

This method retrieves the DOS path name of the file or directory by its native (NT) path.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetDOSPathName(const char* lpszNTPath);

Unicode (Windows)
LPWSTR GetDOSPathName(LPCWSTR lpszNTPath);

char* cbfsfilter_cbmonitor_getdospathname(void* lpObj, const char* lpszNTPath);

QString GetDOSPathName(const QString& qsNTPath);

Remarks

This method retrieves the DOS path name of the file or directory by its native path, specified in the NTPath parameter.

Note: Such name conversion is not always possible (e.g., the volume can have none or more than one DOS names). In this case, an empty string is returned.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDriverStatus Method (CBMonitor Class)

This method retrieves the status of the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetDriverStatus(const char* lpszProductGUID);

Unicode (Windows)
INT GetDriverStatus(LPCWSTR lpszProductGUID);

int cbfsfilter_cbmonitor_getdriverstatus(void* lpObj, const char* lpszProductGUID);

int GetDriverStatus(const QString& qsProductGUID);

Remarks

This method retrieves the status of the class's system driver. This status can then be used to verify whether it has been properly installed and is ready for use.

The value returned by the method corresponds to the dwCurrentState field of the SERVICE_STATUS structure from the Windows API. It will be one of the following:

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetDriverVersion
• Initialize

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetDriverVersion Method (CBMonitor Class)

This method retrieves the version of the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetDriverVersion(const char* lpszProductGUID);

Unicode (Windows)
LONG64 GetDriverVersion(LPCWSTR lpszProductGUID);

int64 cbfsfilter_cbmonitor_getdriverversion(void* lpObj, const char* lpszProductGUID);

qint64 GetDriverVersion(const QString& qsProductGUID);

Remarks

This method retrieves the version of the class's system driver. The value is returned as a 64-bit integer composed of four 16-bit words that each correspond to a piece of the overall module version. For example, a version of 2.32.6.28 would cause the value 0x000200200006001C to be returned.

If the class's system driver is not installed, this method returns 0.

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetDriverVersion
• Initialize

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetEventFilename Method (CBMonitor Class)

This method retrieves the name of the file or directory, to which the event applies.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetEventFilename();

Unicode (Windows)
LPWSTR GetEventFilename();

char* cbfsfilter_cbmonitor_geteventfilename(void* lpObj);

QString GetEventFilename();

Remarks

This method can be called within event handlers of events, related to the file or directory operations, to retrieve the name of the file or directory, to which the operation applies. If the query fails or an event does not have an associated filename, this method returns an empty string.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetNTPathName Method (CBMonitor Class)

This method retrieves the NT (native) path name of the file or directory by its DOS path.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetNTPathName(const char* lpszDOSPath);

Unicode (Windows)
LPWSTR GetNTPathName(LPCWSTR lpszDOSPath);

char* cbfsfilter_cbmonitor_getntpathname(void* lpObj, const char* lpszDOSPath);

QString GetNTPathName(const QString& qsDOSPath);

Remarks

This method retrieves the NT (native) path name of the file or directory by its path, specified in the DOSPath parameter.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOperationTime Method (CBMonitor Class)

This method returns the time at which the request was received by the filter driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int64 GetOperationTime();

Unicode (Windows)
LONG64 GetOperationTime();

int64 cbfsfilter_cbmonitor_getoperationtime(void* lpObj);

QDateTime GetOperationTime();

Remarks

This method can be called within operation-related events to retrieve the time at which the filter driver received the request. The time is recorded before an event is fired but only when the RecordOperationTime configuration setting is enabled.

The timestamps returned by this method are specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as FILETIME.

Error Handling (C++)

This method returns a Long64 value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorProcessId Method (CBMonitor Class)

Retrieves the Id of the process (PID) that initiated the operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOriginatorProcessId();

Unicode (Windows)
INT GetOriginatorProcessId();

int cbfsfilter_cbmonitor_getoriginatorprocessid(void* lpObj);

int GetOriginatorProcessId();

Remarks

This method can be called within events fired for filesystem operations to retrieve the Id of the process (PID) that initiated the operation. If the query fails, this method returns 0.

Please note that PIDs are not unique, and may be reused by different processes over time (though in practice, this is uncommon).

Applications cannot use this method to retrieve information about remote processes accessing drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorProcessName Method (CBMonitor Class)

Retrieves the name of the process that initiated the operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetOriginatorProcessName();

Unicode (Windows)
LPWSTR GetOriginatorProcessName();

char* cbfsfilter_cbmonitor_getoriginatorprocessname(void* lpObj);

QString GetOriginatorProcessName();

Remarks

This method can be called within events fired for filesystem operations to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

Applications cannot use this method to retrieve information about remote processes accessing drives shared on the network. Windows does not provide such information due to the nature of remote access.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetOriginatorThreadId Method (CBMonitor Class)

Retrieves the Id of the thread that initiated the operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetOriginatorThreadId();

Unicode (Windows)
INT GetOriginatorThreadId();

int cbfsfilter_cbmonitor_getoriginatorthreadid(void* lpObj);

int GetOriginatorThreadId();

Remarks

This method can be called within events fired for filesystem operations to retrieve the Id of the thread that initiated the operation. If the query fails, this method returns 0.

Please note that thread Ids are not unique, and may be reused by different threads over time.

Note: This method can be called only within events, and it must be called in the same thread that the event was originally fired on. However, it must not be called within events that work with opened files since such events can be initiated by system components (e.g., the cache manager, memory manager, etc.). If applications need the information this method returns during such events, they may do the following:

1. Call this method within the CreateFile or OpenFile event.
2. Store the information somewhere, and store a reference to it in the event's HandleContext parameter.
3. In a later event, access the information via the reference stored in HandleContext.

Note: Renaming and deletion of files is performed after the file is opened. Thus, access checks should be performed during file opening as described above.

Note: This method cannot be used from CleanupContext event handlers.

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

GetRemoteAccessInformation Method (CBMonitor Class)

This method returns networking-related information about the operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int GetRemoteAccessInformation(char** lpszShareName, void* lpClientSocketAddressBuffer, int* iClientSocketAddressBufferSize);

Unicode (Windows)
INT GetRemoteAccessInformation(LPWSTR* lpszShareName, LPVOID lpClientSocketAddressBuffer, INT*  iClientSocketAddressBufferSize);

int cbfsfilter_cbmonitor_getremoteaccessinformation(void* lpObj, char** lpszShareName, void* lpClientSocketAddressBuffer, int* iClientSocketAddressBufferSize);

int GetRemoteAccessInformation(QString& qsShareName, void* lpClientSocketAddressBuffer, int* iClientSocketAddressBufferSize);

Remarks

Call this method from *CreateFile/*OpenFile events to retrieve the collected networking details information related to the filesystem operation performed across the network.

Note: The information will be available only when the CollectRemoteOpenInformation configuration setting is enabled.

This method returns the contents of one of two structures, SRV_OPEN_ECP_CONTEXT or NFS_OPEN_ECP_CONTEXT. These structures contain various networking information that differs depending on the remote access type. Please refer to MSDN for additional information.

Depending on the type of remote access, the information is extracted from one of those structures. When the method returns, ShareName will contain the value of either ShareName or ExportAlias field of the corresponding structure. ClientSocketAddressBuffer will contain the value of the SocketAddress or ClientSocketAddress field of the corresponding structure. This field is a structure of the SOCKADDR_STORAGE_NFS type.

When calling the method, an application needs to prepare the buffer of the required size and specify this size of the ClientSocketAddressBuffer buffer in the ClientSocketAddressBufferSize argument.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

GetVolumeGUID Method (CBMonitor Class)

This method retrieves the volume GUID of the device targeted by a filesystem operation.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
char* GetVolumeGUID();

Unicode (Windows)
LPWSTR GetVolumeGUID();

char* cbfsfilter_cbmonitor_getvolumeguid(void* lpObj);

QString GetVolumeGUID();

Remarks

This method can be called within events fired for filesystem operations to retrieve the volume GUID of the device targeted by the operation, returned in the Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} format. If the query fails, this method returns an empty string.

Volume GUIDs can be used to enumerate the mounting points of a device using the Windows API's GetVolumePathNamesForVolumeName function.

Note: This method can be called only within events.

Error Handling (C++)

This method returns a String value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

Initialize Method (CBMonitor Class)

This method initializes the class.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Initialize(const char* lpszProductGUID);

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);

int cbfsfilter_cbmonitor_initialize(void* lpObj, const char* lpszProductGUID);

int Initialize(const QString& qsProductGUID);

Remarks

This method initializes the class and must be called each time the application starts before attempting to call any of the class's other methods with the exception of installation-related methods.

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetDriverVersion
• Initialize

If the required driver was not installed using the Install method with the same value of ProductGUID, Initialize will return a ERROR_FILE_NOT_FOUND error (Win32 error code 2).

If the loaded kernel-mode driver is older than the user-mode API, Initialize will return a ERROR_INVALID_KERNEL_INFO_VERSION error (Win32 error code 340). In this situation, an update of the driver using the Install method is required before the class can be used.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Install Method (CBMonitor Class)

This method installs (or upgrades) the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Install(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, const char* lpszAltitude, int iFlags);

Unicode (Windows)
INT Install(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszPathToInstall, LPCWSTR lpszAltitude, INT iFlags);

int cbfsfilter_cbmonitor_install(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, const char* lpszAltitude, int iFlags);

bool Install(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsPathToInstall, const QString& qsAltitude, int iFlags);

Remarks

This method is used to install or upgrade the class's system driver. If the system must be rebooted to complete the installation process, this method returns true; otherwise, it returns false.

Important: To upgrade the class's driver, use only the Install method. Previously installed versions of the driver should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

CabFileName must be the path of the cbfilter.cab file containing the class's system driver.

Note: This .cab file must remain on the target system (or be available in some other way) after installation, as it is required to uninstall the driver from the system.

ProductGUID is used to distinguish among driver installations performed by different applications. Such information is necessary to guard against unexpected situations, such as the driver being uninstalled by one application despite other applications still needing it.

Therefore, to ensure proper operation, it is critical that each individual application have its own unique ProductGUID value, and that applications (and their installation scripts) use that value when calling any of the following methods:

• Install
• Uninstall
• GetDriverStatus
• GetDriverVersion
• Initialize

PathToInstall controls where the driver is installed. Pass empty string (highly recommended) to automatically install them to the appropriate Windows system directory.

Altitude specifies the driver altitude to use . During development, you can use any acceptable altitude value. For deployment, an altitude value must be assigned by Microsoft before deploying a filesystem minifilter in production. After installation, the altitude can be changed at any time using the Altitude property. Please refer to the Driver Altitudes topic for more information.

Flags specifies various installation options. It should contain zero or more of the following flags, ORed together:

Note: Enabling the AlwaysPrepareFiles and/or SendRequestsViaDriverStack configuration settings before calling this method will cause the corresponding flags to be added automatically. These configuration settings can also be used to toggle the corresponding options at any time after installation.

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

NtStatusToWin32Error Method (CBMonitor Class)

This method converts a native status code to a Win32 error code.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int NtStatusToWin32Error(int iStatus);

Unicode (Windows)
INT NtStatusToWin32Error(INT iStatus);

int cbfsfilter_cbmonitor_ntstatustowin32error(void* lpObj, int iStatus);

int NtStatusToWin32Error(int iStatus);

Remarks

This method converts the native status code specified by Status to a Win32 error code. If the specified native status code does not map directly to a Win32 error code, this method returns ERROR_MR_MID_NOT_FOUND (317).

Error Handling (C++)

This method returns an Integer value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

ShutdownSystem Method (CBMonitor Class)

Shuts down or reboots the operating system.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int ShutdownSystem(const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

Unicode (Windows)
INT ShutdownSystem(LPCWSTR lpszShutdownPrompt, INT iTimeout, BOOL bForceCloseApps, BOOL bReboot);

int cbfsfilter_cbmonitor_shutdownsystem(void* lpObj, const char* lpszShutdownPrompt, int iTimeout, int bForceCloseApps, int bReboot);

bool ShutdownSystem(const QString& qsShutdownPrompt, int iTimeout, bool bForceCloseApps, bool bReboot);

Remarks

This method shuts down or (if Reboot is true) reboots the operating system. If the appropriate privileges cannot be obtained, or if the InitiateSystemShutdown system call returns false, then this method will return false; otherwise, it returns true. This method can be used if the installation or uninstallation function requires the system to be rebooted in order to complete.

ShutdownPrompt, if non-empty, specifies a message that the OS should display to the user for Timeout seconds. If empty string is passed for ShutdownPrompt, no message is displayed and the Timeout parameter's value is ignored.

ForceCloseApps specifies whether the OS should forcefully close all applications. Please keep in mind that forceful closing of applications with unsaved data can lead to data loss.

Reboot specifies whether the OS should reboot (true) or just shut down (false).

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

StartFilter Method (CBMonitor Class)

This method starts filtering filesystem operations.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int StartFilter();

Unicode (Windows)
INT StartFilter();

int cbfsfilter_cbmonitor_startfilter(void* lpObj);

int StartFilter();

Remarks

This method attaches the filter, causing the class's system driver to start filtering filesystem operations according to the filter rules currently present. Rules can be added and removed both before and after this method is called, as long as the Initialize method is called before doing anything else.

This method can fail for a number of reasons, including (but not limited to) the following:

• If the class's system driver has not been properly installed, or is awaiting a system reboot (as indicated by the return value of Install), this method fails with an ERROR_FILE_NOT_FOUND (2) error code.
• If the Initialize method has not been called yet, this method fails with an ERROR_NOT_READY (21) error code.
• If the filter is already Active, this method fails with an ERROR_CONNECTION_ACTIVE (1230) error code.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

StopFilter Method (CBMonitor Class)

This method stops filtering filesystem operations.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int StopFilter(int bReserved);

Unicode (Windows)
INT StopFilter(BOOL bReserved);

int cbfsfilter_cbmonitor_stopfilter(void* lpObj, int bReserved);

int StopFilter(bool bReserved);

Remarks

This method detaches the filter, causing the class's system driver to stop filtering filesystem operations. This method will block until all pending requests have been completed and the filter has been detached.

The Reserved parameter is obsolete.

Error Handling (C++)

This method returns a result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message. (Note: This method's result code can also be obtained by calling the GetLastErrorCode() method after it returns.)

Uninstall Method (CBMonitor Class)

This method uninstalls the class's system driver.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
int Uninstall(const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);

Unicode (Windows)
INT Uninstall(LPCWSTR lpszCabFileName, LPCWSTR lpszProductGUID, LPCWSTR lpszInstalledPath, INT iFlags);

int cbfsfilter_cbmonitor_uninstall(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszInstalledPath, int iFlags);

bool Uninstall(const QString& qsCabFileName, const QString& qsProductGUID, const QString& qsInstalledPath, int iFlags);

Remarks

This method is used to uninstall the class's system driver. If the system must be rebooted to complete the uninstallation process, this method returns true; otherwise, it returns false.

Important: To upgrade the class's driver, use only the Install method. Previously installed versions of the driver should not be uninstalled first. Calling the Install method will upgrade the previously installed version.

Please refer to the Driver Installation topic for more information.

The same values must be passed for the CabFileName, ProductGUID, and InstalledPath parameters as were passed when Install was called; please refer to its documentation for more information.

Flags specifies which versions of the class's system driver should be uninstalled and which should be set by ORing together one or more of the following values:

This method is available in both the class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

This method requires administrative rights to execute successfully. If the user account of the process that calls this method doesn't have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

Note: This method cannot be called within events.

Error Handling (C++)

This method returns a Boolean value; after it returns, call the GetLastErrorCode() method to obtain its result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

AfterFilterAttachToVolume Event (CBMonitor Class)

This event fires after the filter attaches to a newly mounted filesystem volume.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAfterFilterAttachToVolume(CBMonitorAfterFilterAttachToVolumeEventParams *e);

typedef struct {
  const char *VolumeName;
  int ResultCode;
  int reserved;
} CBMonitorAfterFilterAttachToVolumeEventParams;


Unicode (Windows)
virtual INT FireAfterFilterAttachToVolume(CBMonitorAfterFilterAttachToVolumeEventParams *e);

typedef struct {
  LPCWSTR VolumeName;
  INT ResultCode;
  INT reserved;
} CBMonitorAfterFilterAttachToVolumeEventParams;

#define EID_CBMONITOR_AFTERFILTERATTACHTOVOLUME 1

virtual INT CBFSFILTER_CALL FireAfterFilterAttachToVolume(LPWSTR &lpszVolumeName, INT &iResultCode);

class CBMonitorAfterFilterAttachToVolumeEventParams {
public:
  const QString &VolumeName();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void AfterFilterAttachToVolume(CBMonitorAfterFilterAttachToVolumeEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireAfterFilterAttachToVolume(CBMonitorAfterFilterAttachToVolumeEventParams *e) {...}

Remarks

This event fires after the filter attaches to the newly mounted filesystem volume specified by VolumeName. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

Note: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

Applications can use this event to add volume-specific rules for the volume that has been mounted (keeping in mind that this event does not fire for volumes that are already present when StartFilter is called). Applications that intend to do so must ensure that proper thread synchronization techniques are used when manipulating or enumerating the rule lists, because this event's handler will always execute in the context of some worker thread.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

The format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. Applications can obtain additional information about a volume by retrieving its GUID using the GetVolumeGUID method, and then using that GUID to call various Windows API functions.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

AfterFilterDetachFromVolume Event (CBMonitor Class)

This event fires after the filter detaches from a filesystem volume.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireAfterFilterDetachFromVolume(CBMonitorAfterFilterDetachFromVolumeEventParams *e);

typedef struct {
  const char *VolumeName;
  int ResultCode;
  int reserved;
} CBMonitorAfterFilterDetachFromVolumeEventParams;


Unicode (Windows)
virtual INT FireAfterFilterDetachFromVolume(CBMonitorAfterFilterDetachFromVolumeEventParams *e);

typedef struct {
  LPCWSTR VolumeName;
  INT ResultCode;
  INT reserved;
} CBMonitorAfterFilterDetachFromVolumeEventParams;

#define EID_CBMONITOR_AFTERFILTERDETACHFROMVOLUME 2

virtual INT CBFSFILTER_CALL FireAfterFilterDetachFromVolume(LPWSTR &lpszVolumeName, INT &iResultCode);

class CBMonitorAfterFilterDetachFromVolumeEventParams {
public:
  const QString &VolumeName();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void AfterFilterDetachFromVolume(CBMonitorAfterFilterDetachFromVolumeEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireAfterFilterDetachFromVolume(CBMonitorAfterFilterDetachFromVolumeEventParams *e) {...}

Remarks

This event fires after the filter detaches from the filesystem volume specified by VolumeName, typically because of the volume being unmounted. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

Note: This event won't fire for any volumes skipped during the BeforeFilterAttachToVolume event; please refer to its documentation for more information.

Applications should use this event to remove volume-specific rules for the volume that has been unmounted. Applications that intend to do so must ensure that proper thread synchronization techniques are used when manipulating or enumerating the rule lists, because this event's handler will always execute in the context of some worker thread.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

The format of the VolumeName parameter's value depends on whether the ResolveNtDeviceToDriveLetter configuration setting is enabled; please refer to its documentation for more information. Applications can obtain additional information about a volume by retrieving its GUID using the GetVolumeGUID method, and then using that GUID to call various Windows API functions.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

BeforeFilterAttachToVolume Event (CBMonitor Class)

This event fires before the filter attaches to a newly mounted filesystem volume.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireBeforeFilterAttachToVolume(CBMonitorBeforeFilterAttachToVolumeEventParams *e);

typedef struct {
  const char *VolumeName;
  int SkipVolume;
  int ResultCode;
  int reserved;
} CBMonitorBeforeFilterAttachToVolumeEventParams;


Unicode (Windows)
virtual INT FireBeforeFilterAttachToVolume(CBMonitorBeforeFilterAttachToVolumeEventParams *e);

typedef struct {
  LPCWSTR VolumeName;
  BOOL SkipVolume;
  INT ResultCode;
  INT reserved;
} CBMonitorBeforeFilterAttachToVolumeEventParams;

#define EID_CBMONITOR_BEFOREFILTERATTACHTOVOLUME 3

virtual INT CBFSFILTER_CALL FireBeforeFilterAttachToVolume(LPWSTR &lpszVolumeName, BOOL &bSkipVolume, INT &iResultCode);

class CBMonitorBeforeFilterAttachToVolumeEventParams {
public:
  const QString &VolumeName();

  bool SkipVolume();
  void SetSkipVolume(bool bSkipVolume);

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void BeforeFilterAttachToVolume(CBMonitorBeforeFilterAttachToVolumeEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireBeforeFilterAttachToVolume(CBMonitorBeforeFilterAttachToVolumeEventParams *e) {...}

Remarks

This event fires before the filter attaches to the newly mounted filesystem volume specified by VolumeName. Please refer to the FireVolumeEvents property for more information.

Applications need to handle this event only if the FireVolumeEvents property includes the FS_MOUNT_CONTROL flag.

The VolumeName parameter's value is always an NT native format in this event (unlike the other volume-related events, listed below, where its format depends on the ResolveNtDeviceToDriveLetter configuration setting). It is therefore recommended that applications add volume-specific rules, if desired, during the AfterFilterAttachToVolume event rather than this one. Applications can obtain additional information about a volume by retrieving its GUID using the GetVolumeGUID method, and then using that GUID to call various Windows API functions.

The SkipVolume parameter specifies whether the class's system driver should skip the specified volume (i.e., not attach the filter to it). Setting this parameter to true will cause all filesystem operations that target to volume to be completely ignored by the class's system driver. It also will prevent any of the following events from firing for the volume:

• AfterFilterAttachToVolume
• NotifyFilterAttachToVolume
• AfterFilterDetachFromVolume
• NotifyFilterDetachFromVolume

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

Applications must be aware that this event fires as a direct response to a filesystem state change (mount or unmount). Various system components or third-party actors can perform supplementary filesystem mounting and unmounting during main unmount operations (e.g., Volume Service is one such component). This can cause seemingly excessive events to be fired, and sometimes they can be fired out of order (such as two *Attach or *Detach events fired in a row).

Error Event (CBMonitor Class)

This event fires if an unhandled error occurs during an event.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireError(CBMonitorErrorEventParams *e);

typedef struct {
  int ErrorCode;
  const char *Description;
  int reserved;
} CBMonitorErrorEventParams;


Unicode (Windows)
virtual INT FireError(CBMonitorErrorEventParams *e);

typedef struct {
  INT ErrorCode;
  LPCWSTR Description;
  INT reserved;
} CBMonitorErrorEventParams;

#define EID_CBMONITOR_ERROR 4

virtual INT CBFSFILTER_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);

class CBMonitorErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void Error(CBMonitorErrorEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireError(CBMonitorErrorEventParams *e) {...}

Remarks

This event fires if an unhandled error occurs during another event. Developers can use this information to track down unhandled errors in an application's event handlers.

Note: Not everything is possible or allowed in the event handlers. For details, see the Recursive Calls topic.

FilterStart Event (CBMonitor Class)

This event fires once the filter has attached and filtering has started.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireFilterStart(CBMonitorFilterStartEventParams *e);

typedef struct {
  int ResultCode;
  int reserved;
} CBMonitorFilterStartEventParams;


Unicode (Windows)
virtual INT FireFilterStart(CBMonitorFilterStartEventParams *e);

typedef struct {
  INT ResultCode;
  INT reserved;
} CBMonitorFilterStartEventParams;

#define EID_CBMONITOR_FILTERSTART 5

virtual INT CBFSFILTER_CALL FireFilterStart(INT &iResultCode);

class CBMonitorFilterStartEventParams {
public:
  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void FilterStart(CBMonitorFilterStartEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireFilterStart(CBMonitorFilterStartEventParams *e) {...}

Remarks

This event fires once the filter has attached and filtering has started; please refer to the StartFilter method for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Reporting and Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

FilterStop Event (CBMonitor Class)

This event fires once filtering has stopped and the filter has detached.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireFilterStop(CBMonitorFilterStopEventParams *e);

typedef struct {
  int ResultCode;
  int reserved;
} CBMonitorFilterStopEventParams;


Unicode (Windows)
virtual INT FireFilterStop(CBMonitorFilterStopEventParams *e);

typedef struct {
  INT ResultCode;
  INT reserved;
} CBMonitorFilterStopEventParams;

#define EID_CBMONITOR_FILTERSTOP 6

virtual INT CBFSFILTER_CALL FireFilterStop(INT &iResultCode);

class CBMonitorFilterStopEventParams {
public:
  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void FilterStop(CBMonitorFilterStopEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireFilterStop(CBMonitorFilterStopEventParams *e) {...}

Remarks

This event fires once filtering has stopped and the filter has detached.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired synchronously; please refer to the Event Types topic for more information.

NotifyCanFileBeDeleted Event (CBMonitor Class)

This event fires when the OS marks a file or directory for deletion or removes such a mark.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyCanFileBeDeleted(CBMonitorNotifyCanFileBeDeletedEventParams *e);

typedef struct {
  const char *FileName;
  int RequestType;
  int CanDelete;
  int Status;
  int ResultCode;
  int reserved;
} CBMonitorNotifyCanFileBeDeletedEventParams;


Unicode (Windows)
virtual INT FireNotifyCanFileBeDeleted(CBMonitorNotifyCanFileBeDeletedEventParams *e);

typedef struct {
  LPCWSTR FileName;
  INT RequestType;
  BOOL CanDelete;
  INT Status;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyCanFileBeDeletedEventParams;

#define EID_CBMONITOR_NOTIFYCANFILEBEDELETED 7

virtual INT CBFSFILTER_CALL FireNotifyCanFileBeDeleted(LPWSTR &lpszFileName, INT &iRequestType, BOOL &bCanDelete, INT &iStatus, INT &iResultCode);

class CBMonitorNotifyCanFileBeDeletedEventParams {
public:
  const QString &FileName();

  int RequestType();

  bool CanDelete();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyCanFileBeDeleted(CBMonitorNotifyCanFileBeDeletedEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyCanFileBeDeleted(CBMonitorNotifyCanFileBeDeletedEventParams *e) {...}

Remarks

This event fires when the OS marks the file or directory specified by FileName for deletion or removes such a mark.

Files and directories can be deleted in two ways: (1) a file or directory can be opened with the FILE_FLAG_DELETE_ON_CLOSE flag, or (2) some process may call Windows API's NtSetInformationFile function with FILE_DISPOSITION_INFORMATION or FILE_DISPOSITION_INFORMATION_EX structure as a parameter.

If the file or directory is created or opened with the FILE_FLAG_DELETE_ON_CLOSE flag, this event is fired shortly after the NotifyCreateFile or NotifyOpenFile event.

Applications need to handle this event only if they have added a standard filter rule that includes [the TBD]. FS_NE_CAN_DELETE flag.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

The CanDelete parameter reflects whether or not the file or directory can be deleted.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCleanupFile Event (CBMonitor Class)

This event fires when a file or directory handle has been closed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyCleanupFile(CBMonitorNotifyCleanupFileEventParams *e);

typedef struct {
  const char *FileName;
  int ResultCode;
  int reserved;
} CBMonitorNotifyCleanupFileEventParams;


Unicode (Windows)
virtual INT FireNotifyCleanupFile(CBMonitorNotifyCleanupFileEventParams *e);

typedef struct {
  LPCWSTR FileName;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyCleanupFileEventParams;

#define EID_CBMONITOR_NOTIFYCLEANUPFILE 8

virtual INT CBFSFILTER_CALL FireNotifyCleanupFile(LPWSTR &lpszFileName, INT &iResultCode);

class CBMonitorNotifyCleanupFileEventParams {
public:
  const QString &FileName();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyCleanupFile(CBMonitorNotifyCleanupFileEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyCleanupFile(CBMonitorNotifyCleanupFileEventParams *e) {...}

Remarks

This event fires when a handle to the file or directory specified by FileName has been closed. This event differs from NotifyCloseFile in that NotifyCleanupFile fires when an open handle to the specified file or directory is closed by a process, whereas NotifyCloseFile may be fired much later when the OS itself decides that the file or directory can be formally closed.

Other events may fire for the file or directory in the time between when this event fires and when the NotifyCloseFile event fires. For example, system components, such as the memory manager or cache manager, may cause the NotifyReadFile and NotifyWriteFile events to fire.

Applications need to handle this event only if they have added a standard filter rule that includes [the TBD]. FS_NE_CLEANUP flag.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCloseFile Event (CBMonitor Class)

This event fires when a file or directory has been closed.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyCloseFile(CBMonitorNotifyCloseFileEventParams *e);

typedef struct {
  const char *FileName;
  int ResultCode;
  int reserved;
} CBMonitorNotifyCloseFileEventParams;


Unicode (Windows)
virtual INT FireNotifyCloseFile(CBMonitorNotifyCloseFileEventParams *e);

typedef struct {
  LPCWSTR FileName;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyCloseFileEventParams;

#define EID_CBMONITOR_NOTIFYCLOSEFILE 9

virtual INT CBFSFILTER_CALL FireNotifyCloseFile(LPWSTR &lpszFileName, INT &iResultCode);

class CBMonitorNotifyCloseFileEventParams {
public:
  const QString &FileName();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyCloseFile(CBMonitorNotifyCloseFileEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyCloseFile(CBMonitorNotifyCloseFileEventParams *e) {...}

Remarks

This event fires when the file or directory specified by FileName has been closed.

Applications need to handle this event only if they have added a standard filter rule that includes [the TBD]. FS_NE_CLOSE flag.

If the file or directory was marked for deletion earlier, the NotifyDeleteFile will fire shortly before this event.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCreateFile Event (CBMonitor Class)

This event fires when a file or directory has been created.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyCreateFile(CBMonitorNotifyCreateFileEventParams *e);

typedef struct {
  const char *FileName;
  int ExistingAttributes;
  int DesiredAccess;
  int Attributes;
  int ShareMode;
  int Options;
  int CreateDisposition;
  const void *SecurityDescriptor;
  int Length;
  int Status;
  int ResultCode;
  int reserved;
} CBMonitorNotifyCreateFileEventParams;


Unicode (Windows)
virtual INT FireNotifyCreateFile(CBMonitorNotifyCreateFileEventParams *e);

typedef struct {
  LPCWSTR FileName;
  INT ExistingAttributes;
  INT DesiredAccess;
  INT Attributes;
  INT ShareMode;
  INT Options;
  INT CreateDisposition;
  LPCVOID SecurityDescriptor;
  INT Length;
  INT Status;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyCreateFileEventParams;

#define EID_CBMONITOR_NOTIFYCREATEFILE 10

virtual INT CBFSFILTER_CALL FireNotifyCreateFile(LPWSTR &lpszFileName, INT &iExistingAttributes, INT &iDesiredAccess, INT &iAttributes, INT &iShareMode, INT &iOptions, INT &iCreateDisposition, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iStatus, INT &iResultCode);

class CBMonitorNotifyCreateFileEventParams {
public:
  const QString &FileName();

  int ExistingAttributes();

  int DesiredAccess();

  int Attributes();

  int ShareMode();

  int Options();

  int CreateDisposition();

  const void *SecurityDescriptor();

  int Length();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyCreateFile(CBMonitorNotifyCreateFileEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyCreateFile(CBMonitorNotifyCreateFileEventParams *e) {...}

Remarks

This event fires when the file or directory specified by FileName has been created. Please refer to the File Create/Open Events topic for more information about how the class determines whether to fire this event or NotifyOpenFile.

Applications need to handle this event only if they have added a standard filter rule that includes [the TBD]. FS_NE_CREATE flag.

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory creation requests.

When extended rules are used or the AlwaysRequestAttributesOnOpen configuration setting is enabled, the driver requests attributes of the entity from the filesystem and passes them to ExistingAttributes. If the attributes are not requested, this parameter contains 0.

The DesiredAccess, Attributes, ShareMode, and CreateDisposition parameters reflect the values that were passed for the similarly named parameters of the Windows API's CreateFile function (or, more accurately, the values carried by the IRP_MJ_CREATE IRP).

DesiredAccess may contain one or more of the following access flags:

Attributes may contain one or more of the following attributes:

ShareMode may contain zero or more of the following share mode flags:

CreateDisposition may contain one of the following values:

Options contains the flags that are described in the CreateOptions parameter of the native API's ZwCreateFile function. Most of those flags correspond to flags passed in the FlagsAndAttributes parameter of the Windows API's CreateFile function, but some flags are specific to the native API. If you need those flags, check both functions' descriptions.

Please refer to Microsoft's documentation for detailed information about these constants.

To determine whether the request was for a file or a directory, compare Attributes against the FILE_SYS_ATTR_DIRECTORY constant, as follows: // Check whether the request is for a file or a directory. bool isDirectory = Attributes & FILE_SYS_ATTR_DIRECTORY == FILE_SYS_ATTR_DIRECTORY; FILE_SYS_ATTR_DIRECTORY will be present if it was specified by the calling process or if the existing filesystem entry is a directory.

To determine whether a file will be deleted when its last handle is closed, compare Options against the Windows API's FILE_FLAG_DELETE_ON_CLOSE constant, as follows: // Check whether the file will be deleted on close. bool deleteOnClose = Options & FILE_FLAG_DELETE_ON_CLOSE == FILE_FLAG_DELETE_ON_CLOSE; Note: Because files can be deleted in different ways, do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

When a file or directory is created using the CreateFile() Windows API function, a caller can specify the security descriptor with the security information. This security information should be applied to a newly created file or directory. The class passes this security information in the SecurityInformation and SecurityDescriptor parameters, when the PassSecurityInFileOpenEvents configuration setting is enabled. If this configuration setting is omitted, the corresponding parameters are empty.

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, are valid and should have been applied. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format; please refer to the Microsoft's documentation for more information.

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the NotifyCanFileBeDeleted event will fire after this event.

If the file is created with extended attributes passed in the request, the NotifySetEa event will fire after this event.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyCreateHardLink Event (CBMonitor Class)

This event fires when a hard link has been created.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyCreateHardLink(CBMonitorNotifyCreateHardLinkEventParams *e);

typedef struct {
  const char *FileName;
  const char *LinkName;
  int Status;
  int ResultCode;
  int reserved;
} CBMonitorNotifyCreateHardLinkEventParams;


Unicode (Windows)
virtual INT FireNotifyCreateHardLink(CBMonitorNotifyCreateHardLinkEventParams *e);

typedef struct {
  LPCWSTR FileName;
  LPCWSTR LinkName;
  INT Status;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyCreateHardLinkEventParams;

#define EID_CBMONITOR_NOTIFYCREATEHARDLINK 11

virtual INT CBFSFILTER_CALL FireNotifyCreateHardLink(LPWSTR &lpszFileName, LPWSTR &lpszLinkName, INT &iStatus, INT &iResultCode);

class CBMonitorNotifyCreateHardLinkEventParams {
public:
  const QString &FileName();

  const QString &LinkName();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyCreateHardLink(CBMonitorNotifyCreateHardLinkEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyCreateHardLink(CBMonitorNotifyCreateHardLinkEventParams *e) {...}

Remarks

This event fires when a hard link to the file specified by FileName has been created. Please refer to Microsoft's Hard Links article for more information about hard links.

Applications need to handle this event only if they have added a standard filter rule that includes [the TBD]. FS_NE_CREATE_HARD_LINK flag.

The LinkName parameter reflects the name of the created hard link.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyDeleteFile Event (CBMonitor Class)

This event fires when a file or directory has been deleted.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyDeleteFile(CBMonitorNotifyDeleteFileEventParams *e);

typedef struct {
  const char *FileName;
  int RequestType;
  int ResultCode;
  int reserved;
} CBMonitorNotifyDeleteFileEventParams;


Unicode (Windows)
virtual INT FireNotifyDeleteFile(CBMonitorNotifyDeleteFileEventParams *e);

typedef struct {
  LPCWSTR FileName;
  INT RequestType;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyDeleteFileEventParams;

#define EID_CBMONITOR_NOTIFYDELETEFILE 12

virtual INT CBFSFILTER_CALL FireNotifyDeleteFile(LPWSTR &lpszFileName, INT &iRequestType, INT &iResultCode);

class CBMonitorNotifyDeleteFileEventParams {
public:
  const QString &FileName();

  int RequestType();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyDeleteFile(CBMonitorNotifyDeleteFileEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyDeleteFile(CBMonitorNotifyDeleteFileEventParams *e) {...}

Remarks

This event fires when the file or directory specified by FileName has been deleted. More specifically, this event is queued for delivery after the final IRP_MJ_CLOSE I/O request packet (IRP) has been processed by the filesystem (i.e., after the last handle to the file or directory is closed and the file or directory is gone) and before NotifyCloseFile is queued.

Applications need to handle this event only if they have added a standard filter rule that includes [the TBD]. FS_NE_DELETE flag.

The RequestType indicates which kind of system request resulted in firing this event. It can be one of the following:

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyDeleteReparsePoint Event (CBMonitor Class)

This event fires when a file or directory's reparse point has been deleted.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyDeleteReparsePoint(CBMonitorNotifyDeleteReparsePointEventParams *e);

typedef struct {
  const char *FileName;
  int Status;
  int ResultCode;
  int reserved;
} CBMonitorNotifyDeleteReparsePointEventParams;


Unicode (Windows)
virtual INT FireNotifyDeleteReparsePoint(CBMonitorNotifyDeleteReparsePointEventParams *e);

typedef struct {
  LPCWSTR FileName;
  INT Status;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyDeleteReparsePointEventParams;

#define EID_CBMONITOR_NOTIFYDELETEREPARSEPOINT 13

virtual INT CBFSFILTER_CALL FireNotifyDeleteReparsePoint(LPWSTR &lpszFileName, INT &iStatus, INT &iResultCode);

class CBMonitorNotifyDeleteReparsePointEventParams {
public:
  const QString &FileName();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyDeleteReparsePoint(CBMonitorNotifyDeleteReparsePointEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyDeleteReparsePoint(CBMonitorNotifyDeleteReparsePointEventParams *e) {...}

Remarks

This event fires when a reparse point has been deleted from the file or directory specified by FileName.

Note: The file or directory was not deleted, only a reparse point was.

Applications need to handle this event only if they have added a standard filter rule that includes [the TBD]. FS_NE_DELETE_REPARSE_POINT flag.

The Status parameter contains an NT status code that indicates the outcome of the operation; 0 indicates success. To convert this value to a Win32 error code, call the NtStatusToWin32Error method.

Note: This event will not fire for failed requests unless the ProcessFailedRequests property is enabled.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason, set it to a non-zero value to report an appropriate error.

Note: This event fires after the operation has already completed, so reporting an error will not actually affect the operation itself. Please refer to the Error Reporting and Handling topic for more information.

This event is fired asynchronously; please refer to the Event Types topic for more information.

NotifyEnumerateDirectory Event (CBMonitor Class)

This event fires when a directory entry has been returned during directory enumeration.

Syntax

• C++
• C
• Qt

ANSI (Cross Platform)
virtual int FireNotifyEnumerateDirectory(CBMonitorNotifyEnumerateDirectoryEventParams *e);

typedef struct {
  const char *DirectoryName;
  int Flags;
  int Index;
  const char *FileName;
  int64 CreationTime;
  int64 LastAccessTime;
  int64 LastWriteTime;
  int64 ChangeTime;
  int64 Size;
  int64 AllocationSize;
  int64 FileId;
  int Attributes;
  int Status;
  int ResultCode;
  int reserved;
} CBMonitorNotifyEnumerateDirectoryEventParams;


Unicode (Windows)
virtual INT FireNotifyEnumerateDirectory(CBMonitorNotifyEnumerateDirectoryEventParams *e);

typedef struct {
  LPCWSTR DirectoryName;
  INT Flags;
  INT Index;
  LPCWSTR FileName;
  LONG64 CreationTime;
  LONG64 LastAccessTime;
  LONG64 LastWriteTime;
  LONG64 ChangeTime;
  LONG64 Size;
  LONG64 AllocationSize;
  LONG64 FileId;
  INT Attributes;
  INT Status;
  INT ResultCode;
  INT reserved;
} CBMonitorNotifyEnumerateDirectoryEventParams;

#define EID_CBMONITOR_NOTIFYENUMERATEDIRECTORY 14

virtual INT CBFSFILTER_CALL FireNotifyEnumerateDirectory(LPWSTR &lpszDirectoryName, INT &iFlags, INT &iIndex, LPWSTR &lpszFileName, LONG64 &lCreationTime, LONG64 &lLastAccessTime, LONG64 &lLastWriteTime, LONG64 &lChangeTime, LONG64 &lSize, LONG64 &lAllocationSize, LONG64 &lFileId, INT &iAttributes, INT &iStatus, INT &iResultCode);

class CBMonitorNotifyEnumerateDirectoryEventParams {
public:
  const QString &DirectoryName();

  int Flags();

  int Index();

  const QString &FileName();

  const QDateTime &CreationTime();

  const QDateTime &LastAccessTime();

  const QDateTime &LastWriteTime();

  const QDateTime &ChangeTime();

  qint64 Size();

  qint64 AllocationSize();

  qint64 FileId();

  int Attributes();

  int Status();

  int ResultCode();
  void SetResultCode(int iResultCode);

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

// To handle, connect one or more slots to this signal.
void NotifyEnumerateDirectory(CBMonitorNotifyEnumerateDirectoryEventParams *e);

// Or, subclass CBMonitor and override this emitter function.
virtual int FireNotifyEnumerateDirectory(CBMonitorNotifyEnumerateDirectoryEventParams *e) {...}