Struct cbfsfilter::CBMonitor

Properties   Methods   Events   Config Settings   Errors  

The CBMonitor struct allows applications to monitor filesystem requests.

Syntax

cbfsfilter::CBMonitor

Remarks

The CBMonitor struct is a "monitoring-only" subset of the CBFilter struct; 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 struct's capabilities, please refer to the product's General Information topics.

Getting Started

1. If the struct'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 struct. This must be done each time the application starts.
3. Add one or more filter rules using methods like add_filter_rule. (Rules can also be added/removed after the filter is started.)
4. Call the start_filter method to start monitoring filesystem requests.
5. When finished, call the stop_filter method to stop monitoring filesystem requests.
6. To uninstall the struct'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.

Object Lifetime

The new() method returns a mutable reference to a struct instance. The object itself is kept in the global list maintainted by CBFSFilter. Due to this, the CBMonitor struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of CBMonitor when you have finished using the instance.

Property List

---

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

Method List

---

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

Event List

---

The following is the full list of the events fired by the struct with short descriptions. Click on the links for further details.

Config Settings

---

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

active Property (CBMonitor Struct)

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

Syntax

fn active(&self ) -> Result<bool, CBFSFilterError> 

Default Value

false

Remarks

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

This property is read-only.

Data Type

bool

altitude Property (CBMonitor Struct)

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

Syntax

fn altitude(&self ) -> Result<String, CBFSFilterError> 
fn set_altitude(&self, value : String) ->  Option<CBFSFilterError> 
fn set_altitude_ref(&self, value : &String) ->  Option<CBFSFilterError> 

Default Value

String::default()

Remarks

This property specifies the altitude that the struct'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

filter_rule_count Property (CBMonitor Struct)

The number of records in the FilterRule arrays.

Syntax

fn filter_rule_count(&self ) -> Result<i32, CBFSFilterError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• filter_rule_access_flags
• filter_rule_control_flags
• filter_rule_ea_name
• filter_rule_excluded_attributes
• filter_rule_included_attributes
• filter_rule_mask
• filter_rule_max_size
• filter_rule_min_size
• filter_rule_notify_flags

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

This property is read-only.

Data Type

i32

filter_rule_access_flags Property (CBMonitor Struct)

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

Syntax

fn filter_rule_access_flags(&self , FilterRuleIndex : i32) -> Result<i32, CBFSFilterError> 

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 struct, 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.

Data Type

i32

filter_rule_control_flags Property (CBMonitor Struct)

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

Syntax

fn filter_rule_control_flags(&self , FilterRuleIndex : i32) -> Result<i64, CBFSFilterError> 

Default Value

0

Remarks

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

This property indicates which filesystem operations, of those performed on matching files and directories, the struct 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 struct, 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.

Data Type

i64

filter_rule_ea_name Property (CBMonitor Struct)

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

Syntax

fn filter_rule_ea_name(&self , FilterRuleIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

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.

Data Type

String

filter_rule_excluded_attributes Property (CBMonitor Struct)

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

Syntax

fn filter_rule_excluded_attributes(&self , FilterRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

filter_rule_included_attributes Property (CBMonitor Struct)

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

Syntax

fn filter_rule_included_attributes(&self , FilterRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

filter_rule_mask Property (CBMonitor Struct)

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

Syntax

fn filter_rule_mask(&self , FilterRuleIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

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 struct 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.

Data Type

String

filter_rule_max_size Property (CBMonitor Struct)

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

Syntax

fn filter_rule_max_size(&self , FilterRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

filter_rule_min_size Property (CBMonitor Struct)

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

Syntax

fn filter_rule_min_size(&self , FilterRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

filter_rule_notify_flags Property (CBMonitor Struct)

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

Syntax

fn filter_rule_notify_flags(&self , FilterRuleIndex : i32) -> Result<i64, CBFSFilterError> 

Default Value

0

Remarks

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

This property indicates which filesystem operations, of those performed on matching files and directories, the struct 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.

Data Type

i64

fire_volume_events Property (CBMonitor Struct)

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

Syntax

fn fire_volume_events(&self ) -> Result<i32, CBFSFilterError> 
fn set_fire_volume_events(&self, value : i32) ->  Option<CBFSFilterError> 

Default Value

0

Remarks

This property specifies the events that the struct 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 start_filter 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

i32

normalize_short_file_names Property (CBMonitor Struct)

CBFILTER_NORMALIZE_SHORT_FILE_NAMES_NEVER 0 CBFILTER_NORMALIZE_SHORT_FILE_NAMES_LOCAL_FS 1 CBFILTER_NORMALIZE_SHORT_FILE_NAMES_ALWAYS 2, TBD.

Syntax

fn normalize_short_file_names(&self ) -> Result<i32, CBFSFilterError> 
fn set_normalize_short_file_names(&self, value : i32) ->  Option<CBFSFilterError> 

Default Value

0

Remarks

TBD.

Data Type

i32

passthrough_rule_count Property (CBMonitor Struct)

The number of records in the PassthroughRule arrays.

Syntax

fn passthrough_rule_count(&self ) -> Result<i32, CBFSFilterError> 

Default Value

0

Remarks

This property controls the size of the following arrays:

• passthrough_rule_access_flags
• passthrough_rule_control_flags
• passthrough_rule_ea_name
• passthrough_rule_excluded_attributes
• passthrough_rule_included_attributes
• passthrough_rule_mask
• passthrough_rule_max_size
• passthrough_rule_min_size
• passthrough_rule_notify_flags

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

This property is read-only.

Data Type

i32

passthrough_rule_access_flags Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_access_flags(&self , PassthroughRuleIndex : i32) -> Result<i32, CBFSFilterError> 

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 struct, 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.

Data Type

i32

passthrough_rule_control_flags Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_control_flags(&self , PassthroughRuleIndex : i32) -> Result<i64, CBFSFilterError> 

Default Value

0

Remarks

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

This property indicates which filesystem operations, of those performed on matching files and directories, the struct 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 struct, 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.

Data Type

i64

passthrough_rule_ea_name Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_ea_name(&self , PassthroughRuleIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

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.

Data Type

String

passthrough_rule_excluded_attributes Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_excluded_attributes(&self , PassthroughRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

passthrough_rule_included_attributes Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_included_attributes(&self , PassthroughRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

passthrough_rule_mask Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_mask(&self , PassthroughRuleIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

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 struct 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.

Data Type

String

passthrough_rule_max_size Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_max_size(&self , PassthroughRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

passthrough_rule_min_size Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_min_size(&self , PassthroughRuleIndex : i32) -> Result<i64, CBFSFilterError> 

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.

Data Type

i64

passthrough_rule_notify_flags Property (CBMonitor Struct)

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

Syntax

fn passthrough_rule_notify_flags(&self , PassthroughRuleIndex : i32) -> Result<i64, CBFSFilterError> 

Default Value

0

Remarks

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

This property indicates which filesystem operations, of those performed on matching files and directories, the struct 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.

Data Type

i64

process_cached_io_requests Property (CBMonitor Struct)

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

Syntax

fn process_cached_io_requests(&self ) -> Result<bool, CBFSFilterError> 
fn set_process_cached_io_requests(&self, value : bool) ->  Option<CBFSFilterError> 

Default Value

false

Remarks

This property specifies whether the struct'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

bool

process_failed_requests Property (CBMonitor Struct)

This property specifies whether failed requests should be processed.

Syntax

fn process_failed_requests(&self ) -> Result<bool, CBFSFilterError> 
fn set_process_failed_requests(&self, value : bool) ->  Option<CBFSFilterError> 

Default Value

false

Remarks

This property specifies whether the struct'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 nt_status_to_win32_error 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

bool

serialize_events Property (CBMonitor Struct)

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

Syntax

fn serialize_events(&self ) -> Result<i32, CBFSFilterError> 
fn set_serialize_events(&self, value : i32) ->  Option<CBFSFilterError> 

Default Value

0

Remarks

This property specifies whether the struct 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

i32

tag Property (CBMonitor Struct)

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

Syntax

fn tag(&self ) -> Result<i64, CBFSFilterError> 
fn set_tag(&self, value : i64) ->  Option<CBFSFilterError> 

Default Value

0

Remarks

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

Data Type

i64

add_filter_rule Method (CBMonitor Struct)

This method adds a standard filter rule.

Syntax

fn add_filter_rule(&self, mask : &String, notify_flags : i64) ->  Result<bool, CBFSFilterError>

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 struct 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 struct should fire Notification Events for. For example, if the FS_NE_READ flag is present, the on_notify_read_file 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

add_filter_rule_ex Method (CBMonitor Struct)

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

Syntax

fn add_filter_rule_ex(&self, mask : &String, ea_name : &String, notify_flags : i64, min_size : i64, max_size : i64, included_attributes : i64, excluded_attributes : i64) ->  Result<bool, CBFSFilterError>

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 struct 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 struct should fire Notification Events for. For example, if the FS_NE_READ flag is present, the on_notify_read_file 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

add_passthrough_rule Method (CBMonitor Struct)

This method adds a passthrough rule.

Syntax

fn add_passthrough_rule(&self, mask : &String, notify_flags : i64) ->  Result<bool, CBFSFilterError>

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 struct 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

add_passthrough_rule_ex Method (CBMonitor Struct)

This method adds a passthrough rule with additional match qualifiers.

Syntax

fn add_passthrough_rule_ex(&self, mask : &String, ea_name : &String, notify_flags : i64, min_size : i64, max_size : i64, included_attributes : i64, excluded_attributes : i64) ->  Result<bool, CBFSFilterError>

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 struct 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

config Method (CBMonitor Struct)

Sets or retrieves a configuration setting.

Syntax

fn config(&self, configuration_string : &String) ->  Result<String, CBFSFilterError>

Remarks

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

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, 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.

delete_all_filter_rules Method (CBMonitor Struct)

This method deletes all standard filter rules.

Syntax

fn delete_all_filter_rules(&self) ->  Result<bool, CBFSFilterError>

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 delete_filter_rule 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

delete_all_passthrough_rules Method (CBMonitor Struct)

This method deletes all passthrough rules.

Syntax

fn delete_all_passthrough_rules(&self) ->  Result<bool, CBFSFilterError>

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 delete_passthrough_rule 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

delete_filter_rule Method (CBMonitor Struct)

This method deletes a particular standard filter rule.

Syntax

fn delete_filter_rule(&self, mask : &String, notify_flags : i64) ->  Result<bool, CBFSFilterError>

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 delete_all_filter_rules 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

delete_passthrough_rule Method (CBMonitor Struct)

This method deletes a particular passthrough rule.

Syntax

fn delete_passthrough_rule(&self, mask : &String, notify_flags : i64) ->  Result<bool, CBFSFilterError>

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 delete_all_passthrough_rules 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 on_after_filter_attach_to_volume and on_after_filter_detach_from_volume 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.

file_matches_mask Method (CBMonitor Struct)

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

Syntax

fn file_matches_mask(&self, mask : &String, file_name : &String, case_sensitive : bool) ->  Result<bool, CBFSFilterError>

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."

get_dos_path_name Method (CBMonitor Struct)

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

Syntax

fn get_dos_path_name(&self, nt_path : &String) ->  Result<String, CBFSFilterError>

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.

get_driver_status Method (CBMonitor Struct)

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

Syntax

fn get_driver_status(&self, product_guid : &String) ->  Result<i32, CBFSFilterError>

Remarks

This method retrieves the status of the struct'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
• get_driver_status
• get_driver_version
• initialize

This method is available in both the struct 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.

get_driver_version Method (CBMonitor Struct)

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

Syntax

fn get_driver_version(&self, product_guid : &String) ->  Result<i64, CBFSFilterError>

Remarks

This method retrieves the version of the struct'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 struct'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
• get_driver_status
• get_driver_version
• initialize

This method is available in both the struct 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.

get_event_file_name Method (CBMonitor Struct)

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

Syntax

fn get_event_file_name(&self) ->  Result<String, CBFSFilterError>

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 file name, this method returns an empty string.

get_nt_path_name Method (CBMonitor Struct)

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

Syntax

fn get_nt_path_name(&self, dos_path : &String) ->  Result<String, CBFSFilterError>

Remarks

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

get_operation_time Method (CBMonitor Struct)

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

Syntax

fn get_operation_time(&self) ->  Result<chrono::DateTime<Utc>, CBFSFilterError>

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 .

get_originator_process_id Method (CBMonitor Struct)

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

Syntax

fn get_originator_process_id(&self) ->  Result<i32, CBFSFilterError>

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 on_create_file or on_open_file 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.

Please refer to the Contexts topic for more information on how to use events' context parameters.

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 on_cleanup_context event handlers.

get_originator_process_name Method (CBMonitor Struct)

Retrieves the name of the process that initiated the operation.

Syntax

fn get_originator_process_name(&self) ->  Result<String, CBFSFilterError>

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 on_create_file or on_open_file 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.

Please refer to the Contexts topic for more information on how to use events' context parameters.

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 on_cleanup_context event handlers.

get_originator_thread_id Method (CBMonitor Struct)

Retrieves the Id of the thread that initiated the operation.

Syntax

fn get_originator_thread_id(&self) ->  Result<i32, CBFSFilterError>

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 on_create_file or on_open_file 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.

Please refer to the Contexts topic for more information on how to use events' context parameters.

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 on_cleanup_context event handlers.

get_remote_access_information Method (CBMonitor Struct)

This method returns networking-related information about the operation.

Syntax

fn get_remote_access_information(&self, share_name : &mut String, client_socket_address_buffer : usize, client_socket_address_buffer_size : &mut i32) -> Option<CBFSFilterError>

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.

get_volume_guid Method (CBMonitor Struct)

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

Syntax

fn get_volume_guid(&self) ->  Result<String, CBFSFilterError>

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.

initialize Method (CBMonitor Struct)

This method initializes the struct.

Syntax

fn initialize(&self, product_guid : &String) -> Option<CBFSFilterError>

Remarks

This method initializes the struct and must be called each time the application starts before attempting to call any of the struct'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
• get_driver_status
• get_driver_version
• 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 struct can be used.

install Method (CBMonitor Struct)

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

Syntax

fn install(&self, cab_file_name : &String, product_guid : &String, path_to_install : &String, altitude : &String, flags : i32, allowed_controllers : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method is used to install or upgrade the struct'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 struct'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 struct'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
• get_driver_status
• get_driver_version
• 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.

AllowedControllers is the optional parameter that makes it possible to limit communication with the driver to just the predefined set of processes. When the caller specifies one or more names of the executable files, filtering can be started with the specified ProductGUID only when filtering is initiated by the process created from one of the listed executable files. If the name of the caller process does not match any of the allowed names, the call to start_filter will fail with an error.

The parameter may be either empty or contain one or more EXE file names with complete paths. Separate names/paths should be separated by the LF character (numeric code 10).

This method is available in both the struct 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 () error.

Note: This method cannot be called within events.

nt_status_to_win32_error Method (CBMonitor Struct)

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

Syntax

fn nt_status_to_win32_error(&self, status : i32) ->  Result<i32, CBFSFilterError>

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).

shutdown_system Method (CBMonitor Struct)

Shuts down or reboots the operating system.

Syntax

fn shutdown_system(&self, shutdown_prompt : &String, timeout : i32, force_close_apps : bool, reboot : bool) ->  Result<bool, CBFSFilterError>

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 struct 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.

start_filter Method (CBMonitor Struct)

This method starts filtering filesystem operations.

Syntax

fn start_filter(&self) -> Option<CBFSFilterError>

Remarks

This method attaches the filter, causing the struct'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 struct'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.

stop_filter Method (CBMonitor Struct)

This method stops filtering filesystem operations.

Syntax

fn stop_filter(&self) -> Option<CBFSFilterError>

Remarks

This method detaches the filter, causing the struct'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.

uninstall Method (CBMonitor Struct)

This method uninstalls the struct's system driver.

Syntax

fn uninstall(&self, cab_file_name : &String, product_guid : &String, installed_path : &String, flags : i32) ->  Result<bool, CBFSFilterError>

Remarks

This method is used to uninstall the struct'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 struct'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 struct'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 struct 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 () error.

Note: This method cannot be called within events.

on_after_filter_attach_to_volume Event (CBMonitor Struct)

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

Syntax

// CBMonitorAfterFilterAttachToVolumeEventArgs carries the CBMonitor AfterFilterAttachToVolume event's parameters.
pub struct CBMonitorAfterFilterAttachToVolumeEventArgs {
  fn volume_name(&self) -> &String
  fn volume_name_nt(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorAfterFilterAttachToVolumeEvent defines the signature of the CBMonitor AfterFilterAttachToVolume event's handler function.
pub trait CBMonitorAfterFilterAttachToVolumeEvent {
  fn on_after_filter_attach_to_volume(&self, sender : CBMonitor, e : &mut CBMonitorAfterFilterAttachToVolumeEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_after_filter_attach_to_volume(&self) -> &'a dyn CBMonitorAfterFilterAttachToVolumeEvent;
  pub fn set_on_after_filter_attach_to_volume(&mut self, value : &'a dyn CBMonitorAfterFilterAttachToVolumeEvent);
  ...
}

Remarks

This event fires after the filter attaches to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the fire_volume_events property for more information.

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

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

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications can obtain additional information about a volume by retrieving its GUID using the get_volume_guid method, and then using that GUID to call various Windows API functions.

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 start_filter 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. Note: if a path-based rule is added or removed, such a path should use the value from VolumeNameNT to avoid a possible deadlock, which may occur during resolving a DOS name to the NT format.

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 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 Handling topic for more information.

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

on_after_filter_detach_from_volume Event (CBMonitor Struct)

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

Syntax

// CBMonitorAfterFilterDetachFromVolumeEventArgs carries the CBMonitor AfterFilterDetachFromVolume event's parameters.
pub struct CBMonitorAfterFilterDetachFromVolumeEventArgs {
  fn volume_name(&self) -> &String
  fn volume_name_nt(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorAfterFilterDetachFromVolumeEvent defines the signature of the CBMonitor AfterFilterDetachFromVolume event's handler function.
pub trait CBMonitorAfterFilterDetachFromVolumeEvent {
  fn on_after_filter_detach_from_volume(&self, sender : CBMonitor, e : &mut CBMonitorAfterFilterDetachFromVolumeEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_after_filter_detach_from_volume(&self) -> &'a dyn CBMonitorAfterFilterDetachFromVolumeEvent;
  pub fn set_on_after_filter_detach_from_volume(&mut self, value : &'a dyn CBMonitorAfterFilterDetachFromVolumeEvent);
  ...
}

Remarks

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

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

Note: This event won't fire for any volumes skipped during the on_before_filter_attach_to_volume 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. Note: if a path-based rule is added or removed, such a path should use the value from VolumeNameNT to avoid a possible deadlock, which may occur during resolving a DOS name to the NT format.

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).

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

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 Handling topic for more information.

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

on_before_filter_attach_to_volume Event (CBMonitor Struct)

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

Syntax

// CBMonitorBeforeFilterAttachToVolumeEventArgs carries the CBMonitor BeforeFilterAttachToVolume event's parameters.
pub struct CBMonitorBeforeFilterAttachToVolumeEventArgs {
  fn volume_name(&self) -> &String
  fn volume_name_nt(&self) -> &String
  fn skip_volume(&self) -> bool
  fn set_skip_volume(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorBeforeFilterAttachToVolumeEvent defines the signature of the CBMonitor BeforeFilterAttachToVolume event's handler function.
pub trait CBMonitorBeforeFilterAttachToVolumeEvent {
  fn on_before_filter_attach_to_volume(&self, sender : CBMonitor, e : &mut CBMonitorBeforeFilterAttachToVolumeEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_before_filter_attach_to_volume(&self) -> &'a dyn CBMonitorBeforeFilterAttachToVolumeEvent;
  pub fn set_on_before_filter_attach_to_volume(&mut self, value : &'a dyn CBMonitorBeforeFilterAttachToVolumeEvent);
  ...
}

Remarks

This event fires before the filter attaches to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the fire_volume_events property for more information.

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

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications can obtain additional information about a volume by retrieving its GUID using the get_volume_guid method, and then using that GUID to call various Windows API functions.

The SkipVolume parameter specifies whether the struct'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 struct's system driver. It also will prevent any of the following events from firing for the volume:

• on_after_filter_attach_to_volume
• on_notify_filter_attach_to_volume
• on_after_filter_detach_from_volume
• on_notify_filter_detach_from_volume

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 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).

on_bypass_io_request Event (CBMonitor Struct)

This event fires when the OS sends one of BypassIO commands.

Syntax

// CBMonitorBypassIORequestEventArgs carries the CBMonitor BypassIORequest event's parameters.
pub struct CBMonitorBypassIORequestEventArgs {
  fn file_name(&self) -> &String
  fn request_code(&self) -> i32
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn reason(&self) -> &String
  fn set_reason(&self, value : String)
  fn set_reason_ref(&self, value : &String)
}

// CBMonitorBypassIORequestEvent defines the signature of the CBMonitor BypassIORequest event's handler function.
pub trait CBMonitorBypassIORequestEvent {
  fn on_bypass_io_request(&self, sender : CBMonitor, e : &mut CBMonitorBypassIORequestEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_bypass_io_request(&self) -> &'a dyn CBMonitorBypassIORequestEvent;
  pub fn set_on_bypass_io_request(&mut self, value : &'a dyn CBMonitorBypassIORequestEvent);
  ...
}

Remarks

This event fires when the OS sends a BypassIO request to a file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

If BypassIO is enabled successfully future operations on the specified file handle will not be visible to the struct. To ensure all future operations on the file are visible to the struct BypassIO should not be enabled. BypassIO is present in Windows 11; it is not used in Windows 10 and earlier systems, and also is not used in Server systems.

Applications need to handle this event only if they have added a standard filter rule that includes the any of the following flags: FS_BYPASS_IO (it should be passed among notification flags), FS_CE_BEFORE_READ, FS_CE_AFTER_READ, FS_CE_BEFORE_WRITE, FS_CE_AFTER_WRITE.

The RequestCode parameter contains the code of the request. The code may be the one of the following:

When the request code is BPIO_OP_ENABLE, an application is able to block BypassIO by specifying a non-zero value for Status and a description of the reason in the Reason parameter. If the application does so, it should return the same status and reason in response to BPIO_OP_QUERY requests to let the caller know that enabling would not be possible. BPIO_OP_QUERY requests are used, in particular, by diagnostics tools. Other operations may not be denied, and when the event is fired for one of those other operations, the struct ignores the values returned in the Status and Reason parameters.

The Status value should be one of the NTStatus codes defined in Windows SDK (Windows 11 SDK defines a group of STATUS_NOT_SUPPORTED_WITH_* constants for this).

The Reason should be set to a human-readable text that explains why BypassIO was blocked.

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

on_error Event (CBMonitor Struct)

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

Syntax

// CBMonitorErrorEventArgs carries the CBMonitor Error event's parameters.
pub struct CBMonitorErrorEventArgs {
  fn error_code(&self) -> i32
  fn description(&self) -> &String
}

// CBMonitorErrorEvent defines the signature of the CBMonitor Error event's handler function.
pub trait CBMonitorErrorEvent {
  fn on_error(&self, sender : CBMonitor, e : &mut CBMonitorErrorEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_error(&self) -> &'a dyn CBMonitorErrorEvent;
  pub fn set_on_error(&mut self, value : &'a dyn CBMonitorErrorEvent);
  ...
}

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.

on_filter_start Event (CBMonitor Struct)

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

Syntax

// CBMonitorFilterStartEventArgs carries the CBMonitor FilterStart event's parameters.
pub struct CBMonitorFilterStartEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorFilterStartEvent defines the signature of the CBMonitor FilterStart event's handler function.
pub trait CBMonitorFilterStartEvent {
  fn on_filter_start(&self, sender : CBMonitor, e : &mut CBMonitorFilterStartEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_filter_start(&self) -> &'a dyn CBMonitorFilterStartEvent;
  pub fn set_on_filter_start(&mut self, value : &'a dyn CBMonitorFilterStartEvent);
  ...
}

Remarks

This event fires once the filter has attached and filtering has started; please refer to the start_filter 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 Handling topic for more information.

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

on_filter_stop Event (CBMonitor Struct)

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

Syntax

// CBMonitorFilterStopEventArgs carries the CBMonitor FilterStop event's parameters.
pub struct CBMonitorFilterStopEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorFilterStopEvent defines the signature of the CBMonitor FilterStop event's handler function.
pub trait CBMonitorFilterStopEvent {
  fn on_filter_stop(&self, sender : CBMonitor, e : &mut CBMonitorFilterStopEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_filter_stop(&self) -> &'a dyn CBMonitorFilterStopEvent;
  pub fn set_on_filter_stop(&mut self, value : &'a dyn CBMonitorFilterStopEvent);
  ...
}

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 Handling topic for more information.

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

on_notify_can_file_be_deleted Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyCanFileBeDeletedEventArgs carries the CBMonitor NotifyCanFileBeDeleted event's parameters.
pub struct CBMonitorNotifyCanFileBeDeletedEventArgs {
  fn file_name(&self) -> &String
  fn request_type(&self) -> i32
  fn can_delete(&self) -> bool
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyCanFileBeDeletedEvent defines the signature of the CBMonitor NotifyCanFileBeDeleted event's handler function.
pub trait CBMonitorNotifyCanFileBeDeletedEvent {
  fn on_notify_can_file_be_deleted(&self, sender : CBMonitor, e : &mut CBMonitorNotifyCanFileBeDeletedEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_can_file_be_deleted(&self) -> &'a dyn CBMonitorNotifyCanFileBeDeletedEvent;
  pub fn set_on_notify_can_file_be_deleted(&mut self, value : &'a dyn CBMonitorNotifyCanFileBeDeletedEvent);
  ...
}

Remarks

This event fires when the OS marks the file or directory specified by FileName for deletion or removes such a mark. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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 on_notify_create_file or on_notify_open_file event.

Applications need to handle this event only if they have added a standard filter rule that includes the 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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_cleanup_file Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyCleanupFileEventArgs carries the CBMonitor NotifyCleanupFile event's parameters.
pub struct CBMonitorNotifyCleanupFileEventArgs {
  fn file_name(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyCleanupFileEvent defines the signature of the CBMonitor NotifyCleanupFile event's handler function.
pub trait CBMonitorNotifyCleanupFileEvent {
  fn on_notify_cleanup_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyCleanupFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_cleanup_file(&self) -> &'a dyn CBMonitorNotifyCleanupFileEvent;
  pub fn set_on_notify_cleanup_file(&mut self, value : &'a dyn CBMonitorNotifyCleanupFileEvent);
  ...
}

Remarks

This event fires when a handle to the file or directory specified by FileName has been closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event differs from on_notify_close_file in that on_notify_cleanup_file fires when an open handle to the specified file or directory is closed by a process, whereas on_notify_close_file 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 on_notify_close_file event fires. For example, system components, such as the memory manager or cache manager, may cause the on_notify_read_file and on_notify_write_file events to fire.

Applications need to handle this event only if they have added a standard filter rule that includes the 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 Handling topic for more information.

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

on_notify_close_file Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyCloseFileEventArgs carries the CBMonitor NotifyCloseFile event's parameters.
pub struct CBMonitorNotifyCloseFileEventArgs {
  fn file_name(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyCloseFileEvent defines the signature of the CBMonitor NotifyCloseFile event's handler function.
pub trait CBMonitorNotifyCloseFileEvent {
  fn on_notify_close_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyCloseFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_close_file(&self) -> &'a dyn CBMonitorNotifyCloseFileEvent;
  pub fn set_on_notify_close_file(&mut self, value : &'a dyn CBMonitorNotifyCloseFileEvent);
  ...
}

Remarks

This event fires when the file or directory specified by FileName has been closed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

If the file or directory was marked for deletion earlier, the on_notify_delete_file 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 Handling topic for more information.

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

on_notify_create_file Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyCreateFileEventArgs carries the CBMonitor NotifyCreateFile event's parameters.
pub struct CBMonitorNotifyCreateFileEventArgs {
  fn file_name(&self) -> &String
  fn existing_attributes(&self) -> i32
  fn desired_access(&self) -> i32
  fn attributes(&self) -> i32
  fn share_mode(&self) -> i32
  fn options(&self) -> i32
  fn create_disposition(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn status(&self) -> i32
  fn creation_status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyCreateFileEvent defines the signature of the CBMonitor NotifyCreateFile event's handler function.
pub trait CBMonitorNotifyCreateFileEvent {
  fn on_notify_create_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyCreateFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_create_file(&self) -> &'a dyn CBMonitorNotifyCreateFileEvent;
  pub fn set_on_notify_create_file(&mut self, value : &'a dyn CBMonitorNotifyCreateFileEvent);
  ...
}

Remarks

This event fires when the file or directory specified by FileName has been created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the struct determines whether to fire this event or on_notify_open_file.

Applications need to handle this event only if they have added a standard filter rule that includes the 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 struct 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 on_notify_can_file_be_deleted event will fire after this event.

If the file is created with extended attributes passed in the request, the on_notify_set_ea 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 nt_status_to_win32_error method.

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

The CreationStatus parameter indicates whether the file was created or opened and can be one of the following values:

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 Handling topic for more information.

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

on_notify_create_hard_link Event (CBMonitor Struct)

This event fires when a hard link has been created.

Syntax

// CBMonitorNotifyCreateHardLinkEventArgs carries the CBMonitor NotifyCreateHardLink event's parameters.
pub struct CBMonitorNotifyCreateHardLinkEventArgs {
  fn file_name(&self) -> &String
  fn link_name(&self) -> &String
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyCreateHardLinkEvent defines the signature of the CBMonitor NotifyCreateHardLink event's handler function.
pub trait CBMonitorNotifyCreateHardLinkEvent {
  fn on_notify_create_hard_link(&self, sender : CBMonitor, e : &mut CBMonitorNotifyCreateHardLinkEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_create_hard_link(&self) -> &'a dyn CBMonitorNotifyCreateHardLinkEvent;
  pub fn set_on_notify_create_hard_link(&mut self, value : &'a dyn CBMonitorNotifyCreateHardLinkEvent);
  ...
}

Remarks

This event fires when a hard link to the file specified by FileName has been created. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. 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 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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_delete_file Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyDeleteFileEventArgs carries the CBMonitor NotifyDeleteFile event's parameters.
pub struct CBMonitorNotifyDeleteFileEventArgs {
  fn file_name(&self) -> &String
  fn request_type(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyDeleteFileEvent defines the signature of the CBMonitor NotifyDeleteFile event's handler function.
pub trait CBMonitorNotifyDeleteFileEvent {
  fn on_notify_delete_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyDeleteFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_delete_file(&self) -> &'a dyn CBMonitorNotifyDeleteFileEvent;
  pub fn set_on_notify_delete_file(&mut self, value : &'a dyn CBMonitorNotifyDeleteFileEvent);
  ...
}

Remarks

This event fires when the file or directory specified by FileName has been deleted. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. 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 on_notify_close_file is queued.

Applications need to handle this event only if they have added a standard filter rule that includes the 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 Handling topic for more information.

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

on_notify_delete_reparse_point Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyDeleteReparsePointEventArgs carries the CBMonitor NotifyDeleteReparsePoint event's parameters.
pub struct CBMonitorNotifyDeleteReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyDeleteReparsePointEvent defines the signature of the CBMonitor NotifyDeleteReparsePoint event's handler function.
pub trait CBMonitorNotifyDeleteReparsePointEvent {
  fn on_notify_delete_reparse_point(&self, sender : CBMonitor, e : &mut CBMonitorNotifyDeleteReparsePointEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_delete_reparse_point(&self) -> &'a dyn CBMonitorNotifyDeleteReparsePointEvent;
  pub fn set_on_notify_delete_reparse_point(&mut self, value : &'a dyn CBMonitorNotifyDeleteReparsePointEvent);
  ...
}

Remarks

This event fires when a reparse point has been deleted from the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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 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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_enumerate_directory Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyEnumerateDirectoryEventArgs carries the CBMonitor NotifyEnumerateDirectory event's parameters.
pub struct CBMonitorNotifyEnumerateDirectoryEventArgs {
  fn directory_name(&self) -> &String
  fn flags(&self) -> i32
  fn index(&self) -> i32
  fn file_name(&self) -> &String
  fn creation_time(&self) -> &chrono::DateTime<Utc>
  fn last_access_time(&self) -> &chrono::DateTime<Utc>
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn change_time(&self) -> &chrono::DateTime<Utc>
  fn size(&self) -> i64
  fn allocation_size(&self) -> i64
  fn file_id(&self) -> i64
  fn attributes(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyEnumerateDirectoryEvent defines the signature of the CBMonitor NotifyEnumerateDirectory event's handler function.
pub trait CBMonitorNotifyEnumerateDirectoryEvent {
  fn on_notify_enumerate_directory(&self, sender : CBMonitor, e : &mut CBMonitorNotifyEnumerateDirectoryEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_enumerate_directory(&self) -> &'a dyn CBMonitorNotifyEnumerateDirectoryEvent;
  pub fn set_on_notify_enumerate_directory(&mut self, value : &'a dyn CBMonitorNotifyEnumerateDirectoryEvent);
  ...
}

Remarks

This event fires when a directory entry (i.e., file or subdirectory) has been returned during enumeration of the directory specified by DirectoryName. For more information about the DirectoryName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Flags parameter specifies supplementary information about enumeration. It is a combination of zero or more values:

If the Flags parameter contains FS_ENUM_INDEX_SPECIFIED, the Index parameter contains the index as provided by the OS.

The FileName parameter reflects the name of the directory entry.

The CreationTime, LastAccessTime, LastWriteTime, and ChangeTime parameters reflect the entry's time values, specified .

The Size parameter reflects the size of the file, in bytes; it is always 0 for subdirectories.

The AllocationSize parameter reflects the amount of space allocated for the file, in bytes; it is always 0 for subdirectories.

The FileId parameter reflects the unique Id of the entry, as reported by the filesystem. This Id is used by the network redirector, and some third-party applications, to open files and directories by Id instead of by name. The root directory always uses the predefined Id 0x7FFFFFFFFFFFFFFF.

The Attributes parameter reflects the entry's attributes; please refer to Microsoft's File Attribute Constants article for attribute descriptions.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_filter_attach_to_volume Event (CBMonitor Struct)

This event fires when the filter has been attached to a newly mounted filesystem volume.

Syntax

// CBMonitorNotifyFilterAttachToVolumeEventArgs carries the CBMonitor NotifyFilterAttachToVolume event's parameters.
pub struct CBMonitorNotifyFilterAttachToVolumeEventArgs {
  fn volume_name(&self) -> &String
  fn volume_name_nt(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyFilterAttachToVolumeEvent defines the signature of the CBMonitor NotifyFilterAttachToVolume event's handler function.
pub trait CBMonitorNotifyFilterAttachToVolumeEvent {
  fn on_notify_filter_attach_to_volume(&self, sender : CBMonitor, e : &mut CBMonitorNotifyFilterAttachToVolumeEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_filter_attach_to_volume(&self) -> &'a dyn CBMonitorNotifyFilterAttachToVolumeEvent;
  pub fn set_on_notify_filter_attach_to_volume(&mut self, value : &'a dyn CBMonitorNotifyFilterAttachToVolumeEvent);
  ...
}

Remarks

This event fires when the filter has been attached to the newly mounted filesystem volume specified by VolumeNameNT and, when possible, VolumeName. Please refer to the fire_volume_events property for more information.

Applications need to handle this event only if the fire_volume_events property includes the FS_MOUNT_NOTIFY flag.

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

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications that use volume-specific rules should typically add such rules during the on_after_filter_attach_to_volume event, which is fired synchronously, rather than this one.

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 Handling topic for more information.

This event is fired asynchronously; 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).

on_notify_filter_detach_from_volume Event (CBMonitor Struct)

This event fires when the filter has been detached from a filesystem volume.

Syntax

// CBMonitorNotifyFilterDetachFromVolumeEventArgs carries the CBMonitor NotifyFilterDetachFromVolume event's parameters.
pub struct CBMonitorNotifyFilterDetachFromVolumeEventArgs {
  fn volume_name(&self) -> &String
  fn volume_name_nt(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyFilterDetachFromVolumeEvent defines the signature of the CBMonitor NotifyFilterDetachFromVolume event's handler function.
pub trait CBMonitorNotifyFilterDetachFromVolumeEvent {
  fn on_notify_filter_detach_from_volume(&self, sender : CBMonitor, e : &mut CBMonitorNotifyFilterDetachFromVolumeEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_filter_detach_from_volume(&self) -> &'a dyn CBMonitorNotifyFilterDetachFromVolumeEvent;
  pub fn set_on_notify_filter_detach_from_volume(&mut self, value : &'a dyn CBMonitorNotifyFilterDetachFromVolumeEvent);
  ...
}

Remarks

This event fires when the filter has been detached from the filesystem volume specified by VolumeNameNT and, when possible, VolumeName, typically as a result of the volume being unmounted. Please refer to the fire_volume_events property for more information.

Applications need to handle this event only if the fire_volume_events property includes the FS_MOUNT_NOTIFY flag.

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

VolumeNameNT contains the name of the volume in the NT-native format, as received from the system. If the ResolveNtDeviceToDriveLetter configuration setting is enabled, and if it was possible to convert the NT name to the DOS format with a drive letter, VolumeName will contain the name in this format; otherwise, it will be empty.

Applications that use volume-specific rules typically should remove such rules during the on_after_filter_detach_from_volume event, which is fired synchronously, rather than this one.

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 Handling topic for more information.

This event is fired asynchronously; 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).

on_notify_fsctl Event (CBMonitor Struct)

This event fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred.

Syntax

// CBMonitorNotifyFsctlEventArgs carries the CBMonitor NotifyFsctl event's parameters.
pub struct CBMonitorNotifyFsctlEventArgs {
  fn file_name(&self) -> &String
  fn fs_control_code(&self) -> i32
  fn in_buffer(&self) -> *mut u8
  fn in_buffer_length(&self) -> i32
  fn in_buffer_valid_bytes(&self) -> i32
  fn out_buffer(&self) -> *mut u8
  fn out_buffer_length(&self) -> i32
  fn out_buffer_valid_bytes(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyFsctlEvent defines the signature of the CBMonitor NotifyFsctl event's handler function.
pub trait CBMonitorNotifyFsctlEvent {
  fn on_notify_fsctl(&self, sender : CBMonitor, e : &mut CBMonitorNotifyFsctlEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_fsctl(&self) -> &'a dyn CBMonitorNotifyFsctlEvent;
  pub fn set_on_notify_fsctl(&mut self, value : &'a dyn CBMonitorNotifyFsctlEvent);
  ...
}

Remarks

This event fires when an IRP_MJ_FILE_SYSTEM_CONTROL (FSCTL) operation has occurred. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwFsControlFile function (kernel mode); please refer to Microsoft's documentation for more information.

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

The FileName parameter reflects the file, directory, or volume targeted by the request.

The FsControlCode parameter reflects the requested filesystem control code (FSCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that contains the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation did not return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_get_file_security Event (CBMonitor Struct)

This event fires when a file or directory's security attributes have been retrieved.

Syntax

// CBMonitorNotifyGetFileSecurityEventArgs carries the CBMonitor NotifyGetFileSecurity event's parameters.
pub struct CBMonitorNotifyGetFileSecurityEventArgs {
  fn file_name(&self) -> &String
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyGetFileSecurityEvent defines the signature of the CBMonitor NotifyGetFileSecurity event's handler function.
pub trait CBMonitorNotifyGetFileSecurityEvent {
  fn on_notify_get_file_security(&self, sender : CBMonitor, e : &mut CBMonitorNotifyGetFileSecurityEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_get_file_security(&self) -> &'a dyn CBMonitorNotifyGetFileSecurityEvent;
  pub fn set_on_notify_get_file_security(&mut self, value : &'a dyn CBMonitorNotifyGetFileSecurityEvent);
  ...
}

Remarks

This event fires when security attributes have been retrieved for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Note: This event will not fire every time a file or directory is accessed. To check file security upon each access to a file or directory, implement the file create and open events and perform the necessary checks there instead.

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

The SecurityInformation parameter indicates which pieces of security information were requested. 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, if the request was successful, contains the requested 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.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_get_file_sizes Event (CBMonitor Struct)

This event fires when a file's size information has been retrieved.

Syntax

// CBMonitorNotifyGetFileSizesEventArgs carries the CBMonitor NotifyGetFileSizes event's parameters.
pub struct CBMonitorNotifyGetFileSizesEventArgs {
  fn file_name(&self) -> &String
  fn size(&self) -> i64
  fn allocation_size(&self) -> i64
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyGetFileSizesEvent defines the signature of the CBMonitor NotifyGetFileSizes event's handler function.
pub trait CBMonitorNotifyGetFileSizesEvent {
  fn on_notify_get_file_sizes(&self, sender : CBMonitor, e : &mut CBMonitorNotifyGetFileSizesEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_get_file_sizes(&self) -> &'a dyn CBMonitorNotifyGetFileSizesEvent;
  pub fn set_on_notify_get_file_sizes(&mut self, value : &'a dyn CBMonitorNotifyGetFileSizesEvent);
  ...
}

Remarks

This event fires when size information has been retrieved for the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Size parameter reflects the actual size of the file, in bytes.

The AllocationSize parameter reflects the amount of space allocated for the file, in bytes.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_get_reparse_point Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyGetReparsePointEventArgs carries the CBMonitor NotifyGetReparsePoint event's parameters.
pub struct CBMonitorNotifyGetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyGetReparsePointEvent defines the signature of the CBMonitor NotifyGetReparsePoint event's handler function.
pub trait CBMonitorNotifyGetReparsePointEvent {
  fn on_notify_get_reparse_point(&self, sender : CBMonitor, e : &mut CBMonitorNotifyGetReparsePointEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_get_reparse_point(&self) -> &'a dyn CBMonitorNotifyGetReparsePointEvent;
  pub fn set_on_notify_get_reparse_point(&mut self, value : &'a dyn CBMonitorNotifyGetReparsePointEvent);
  ...
}

Remarks

This event fires when reparse point information has been retrieved for the file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_GET_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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_ioctl Event (CBMonitor Struct)

This event fires when an IRP_MJ_DEVICE_CONTROL operation has occurred.

Syntax

// CBMonitorNotifyIoctlEventArgs carries the CBMonitor NotifyIoctl event's parameters.
pub struct CBMonitorNotifyIoctlEventArgs {
  fn file_name(&self) -> &String
  fn io_control_code(&self) -> i32
  fn in_buffer(&self) -> *mut u8
  fn in_buffer_length(&self) -> i32
  fn in_buffer_valid_bytes(&self) -> i32
  fn out_buffer(&self) -> *mut u8
  fn out_buffer_length(&self) -> i32
  fn out_buffer_valid_bytes(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyIoctlEvent defines the signature of the CBMonitor NotifyIoctl event's handler function.
pub trait CBMonitorNotifyIoctlEvent {
  fn on_notify_ioctl(&self, sender : CBMonitor, e : &mut CBMonitorNotifyIoctlEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_ioctl(&self) -> &'a dyn CBMonitorNotifyIoctlEvent;
  pub fn set_on_notify_ioctl(&mut self, value : &'a dyn CBMonitorNotifyIoctlEvent);
  ...
}

Remarks

This event fires when an IRP_MJ_DEVICE_CONTROL (IOCTL) operation has occurred. Such requests are sent using the Windows API's DeviceIoControl function (user mode), or ZwDeviceIoControlFile function (kernel mode). Please refer to Microsoft's documentation for more information.

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

The FileName parameter reflects the file, directory, or volume targeted by the request.

The IoControlCode parameter reflects the requested I/O control code (IOCTL).

The InBuffer parameter points to a memory buffer that contains the data required to perform the operation. The InBufferLength and InBufferValidBytes parameters reflect the capacity of InBuffer and the length of the data it contains (respectively), in bytes; InBufferValidBytes may be less than InBufferLength (unless the request did not include data, in which case both will be 0).

The OutBuffer parameter points to a memory buffer that contains the data returned by the operation. The OutBufferLength and OutBufferValidBytes parameters reflect the capacity of OutBuffer and the length of the data it contains (respectively), in bytes; OutBufferValidBytes may be less than OutBufferLength (unless the operation did not return data, in which case both will be 0).

Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_lock Event (CBMonitor Struct)

This event fires when a range of bytes in a file has been locked.

Syntax

// CBMonitorNotifyLockEventArgs carries the CBMonitor NotifyLock event's parameters.
pub struct CBMonitorNotifyLockEventArgs {
  fn file_name(&self) -> &String
  fn offset(&self) -> i64
  fn length(&self) -> i64
  fn key(&self) -> i64
  fn fail_immediately(&self) -> bool
  fn exclusive_lock(&self) -> bool
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyLockEvent defines the signature of the CBMonitor NotifyLock event's handler function.
pub trait CBMonitorNotifyLockEvent {
  fn on_notify_lock(&self, sender : CBMonitor, e : &mut CBMonitorNotifyLockEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_lock(&self) -> &'a dyn CBMonitorNotifyLockEvent;
  pub fn set_on_notify_lock(&mut self, value : &'a dyn CBMonitorNotifyLockEvent);
  ...
}

Remarks

This event fires when a range of bytes in the file specified by FileName has been locked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This request is made either by the OS, or on behalf of a user mode application that called the Windows API's LockFile or LockFileEx function.

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

The Offset parameter reflects the byte offset where the byte range lock starts.

The Length parameter reflects the length of the byte range lock.

The Key parameter reflects the key that the byte range lock is associated with. This key is used to identify the byte range lock in later unlock-by-key requests.

The FailImmediately parameter indicates whether the request was to fail if the lock could not be granted immediately.

The ExclusiveLock parameter indicates whether the byte range lock was to be exclusive (true) or shared (false).

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_open_file Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifyOpenFileEventArgs carries the CBMonitor NotifyOpenFile event's parameters.
pub struct CBMonitorNotifyOpenFileEventArgs {
  fn file_name(&self) -> &String
  fn existing_attributes(&self) -> i32
  fn desired_access(&self) -> i32
  fn attributes(&self) -> i32
  fn share_mode(&self) -> i32
  fn options(&self) -> i32
  fn create_disposition(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn status(&self) -> i32
  fn creation_status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyOpenFileEvent defines the signature of the CBMonitor NotifyOpenFile event's handler function.
pub trait CBMonitorNotifyOpenFileEvent {
  fn on_notify_open_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyOpenFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_open_file(&self) -> &'a dyn CBMonitorNotifyOpenFileEvent;
  pub fn set_on_notify_open_file(&mut self, value : &'a dyn CBMonitorNotifyOpenFileEvent);
  ...
}

Remarks

This event fires when the file or directory specified by FileName has been opened. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. Please refer to the File Create/Open Events topic for more information about how the struct determines whether to fire this event or on_notify_create_file.

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

Note: Applications must have the FilterOwnRequests configuration setting enabled if they wish to filter their own file/directory open 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 struct 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 on_notify_can_file_be_deleted event will fire after this event.

If the file is opened with extended attributes passed in the request, the on_notify_set_ea 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 nt_status_to_win32_error method.

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

The CreationStatus parameter indicates whether the file was created or opened and can be one of the following values:

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 Handling topic for more information.

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

on_notify_query_ea Event (CBMonitor Struct)

This event fires when information about the extended attributes of a file has been retrieved.

Syntax

// CBMonitorNotifyQueryEaEventArgs carries the CBMonitor NotifyQueryEa event's parameters.
pub struct CBMonitorNotifyQueryEaEventArgs {
  fn file_name(&self) -> &String
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn return_single_entry(&self) -> bool
  fn ea_list(&self) -> *mut u8
  fn ea_list_length(&self) -> i32
  fn ea_index(&self) -> i32
  fn restart_scan(&self) -> bool
  fn length_returned(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyQueryEaEvent defines the signature of the CBMonitor NotifyQueryEa event's handler function.
pub trait CBMonitorNotifyQueryEaEvent {
  fn on_notify_query_ea(&self, sender : CBMonitor, e : &mut CBMonitorNotifyQueryEaEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_query_ea(&self) -> &'a dyn CBMonitorNotifyQueryEaEvent;
  pub fn set_on_notify_query_ea(&mut self, value : &'a dyn CBMonitorNotifyQueryEaEvent);
  ...
}

Remarks

This event fires when information about the extended attributes of a file specified by FileName has been retrieved. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Buffer parameter points to a memory buffer that, if the request was successful, contains the requested information. The data in the buffer are formatted as a FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The Length parameter reflects the length of this buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

ReturnSingleEntry specifies that the filesystem had to return only the first entry it has found.

EaList is an optional parameter that points to a caller-supplied memory buffer specifying the extended attributes to be queried. The data in the buffer are formatted as a FILE_GET_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information. The EaListLength parameter reflects the length of this data, in bytes. If the caller of the FltQueryEaFile function did not specify any value, it will contain 0.

EaIndex is an optional parameter that specifies the starting index of the attribute, information about which was requested. This parameter is ignored by the filesystem if EaList points to a nonempty list. If the caller of the FltQueryEaFile function did not specify any value, the parameter will contain -1.

The RestartScan parameter instructs the filesystem to restart enumeration of extended attributes from the first entry. If the parameter is false, retrieval of the extended attributes is resumed by the filesystem after a previous request.

LengthReturned is an optional parameter that contains the size, in bytes, of the information, returned in the Buffer.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_query_file_info Event (CBMonitor Struct)

This event fires when information about a file or directory has been retrieved.

Syntax

// CBMonitorNotifyQueryFileInfoEventArgs carries the CBMonitor NotifyQueryFileInfo event's parameters.
pub struct CBMonitorNotifyQueryFileInfoEventArgs {
  fn file_name(&self) -> &String
  fn file_information_class(&self) -> i32
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn valid_bytes(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyQueryFileInfoEvent defines the signature of the CBMonitor NotifyQueryFileInfo event's handler function.
pub trait CBMonitorNotifyQueryFileInfoEvent {
  fn on_notify_query_file_info(&self, sender : CBMonitor, e : &mut CBMonitorNotifyQueryFileInfoEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_query_file_info(&self) -> &'a dyn CBMonitorNotifyQueryFileInfoEvent;
  pub fn set_on_notify_query_file_info(&mut self, value : &'a dyn CBMonitorNotifyQueryFileInfoEvent);
  ...
}

Remarks

This event fires when information about a file or directory specified by FileName has been retrieved. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtQueryInformationFile function.

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

The FileInformationClass parameter indicates what kind of file information was requested. Please refer to the NtQueryInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the requested file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains (respectively), in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtQueryInformationFile function's documentation for more information.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_read_file Event (CBMonitor Struct)

This event fires when data have been read from a file.

Syntax

// CBMonitorNotifyReadFileEventArgs carries the CBMonitor NotifyReadFile event's parameters.
pub struct CBMonitorNotifyReadFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn bytes_to_read(&self) -> i32
  fn direction(&self) -> i32
  fn bytes_read(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyReadFileEvent defines the signature of the CBMonitor NotifyReadFile event's handler function.
pub trait CBMonitorNotifyReadFileEvent {
  fn on_notify_read_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyReadFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_read_file(&self) -> &'a dyn CBMonitorNotifyReadFileEvent;
  pub fn set_on_notify_read_file(&mut self, value : &'a dyn CBMonitorNotifyReadFileEvent);
  ...
}

Remarks

This event fires when data have been read from a file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Position parameter reflects the byte offset in the file at which reading started.

The BytesToRead parameter reflects how many bytes were to be read from the file.

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

The BytesRead parameter reflects how many bytes were actually read from the file.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_rename_or_move_file Event (CBMonitor Struct)

This event fires when a file or directory has been renamed or moved.

Syntax

// CBMonitorNotifyRenameOrMoveFileEventArgs carries the CBMonitor NotifyRenameOrMoveFile event's parameters.
pub struct CBMonitorNotifyRenameOrMoveFileEventArgs {
  fn file_name(&self) -> &String
  fn new_file_name(&self) -> &String
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyRenameOrMoveFileEvent defines the signature of the CBMonitor NotifyRenameOrMoveFile event's handler function.
pub trait CBMonitorNotifyRenameOrMoveFileEvent {
  fn on_notify_rename_or_move_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyRenameOrMoveFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_rename_or_move_file(&self) -> &'a dyn CBMonitorNotifyRenameOrMoveFileEvent;
  pub fn set_on_notify_rename_or_move_file(&mut self, value : &'a dyn CBMonitorNotifyRenameOrMoveFileEvent);
  ...
}

Remarks

This event fires when a file or directory specified by FileName has been renamed or moved to NewFileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_RENAME flag. A rule's mask is matched against both previous and new file names, and the event will fire when either of the names matches the mask.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_set_allocation_size Event (CBMonitor Struct)

This event fires when a file's allocation size has been changed.

Syntax

// CBMonitorNotifySetAllocationSizeEventArgs carries the CBMonitor NotifySetAllocationSize event's parameters.
pub struct CBMonitorNotifySetAllocationSizeEventArgs {
  fn file_name(&self) -> &String
  fn allocation_size(&self) -> i64
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifySetAllocationSizeEvent defines the signature of the CBMonitor NotifySetAllocationSize event's handler function.
pub trait CBMonitorNotifySetAllocationSizeEvent {
  fn on_notify_set_allocation_size(&self, sender : CBMonitor, e : &mut CBMonitorNotifySetAllocationSizeEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_set_allocation_size(&self) -> &'a dyn CBMonitorNotifySetAllocationSizeEvent;
  pub fn set_on_notify_set_allocation_size(&mut self, value : &'a dyn CBMonitorNotifySetAllocationSizeEvent);
  ...
}

Remarks

This event fires when the allocation size of the file specified by FileName has been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The AllocationSize parameter reflects the new allocation size, in bytes. A file's allocation size is typically larger than its actual size because filesystem operations often reserve space on disk before writing additional data to a file.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_set_ea Event (CBMonitor Struct)

This event fires when information about the extended attributes of a file has been changed.

Syntax

// CBMonitorNotifySetEaEventArgs carries the CBMonitor NotifySetEa event's parameters.
pub struct CBMonitorNotifySetEaEventArgs {
  fn file_name(&self) -> &String
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifySetEaEvent defines the signature of the CBMonitor NotifySetEa event's handler function.
pub trait CBMonitorNotifySetEaEvent {
  fn on_notify_set_ea(&self, sender : CBMonitor, e : &mut CBMonitorNotifySetEaEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_set_ea(&self) -> &'a dyn CBMonitorNotifySetEaEvent;
  pub fn set_on_notify_set_ea(&mut self, value : &'a dyn CBMonitorNotifySetEaEvent);
  ...
}

Remarks

This event fires when information about the extended attributes of a file specified by FileName has been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

If the file is created or opened with extended attributes passed in the request, this event will fire shortly after the on_notify_create_file or on_notify_open_file event.

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

The Buffer parameter points to a memory buffer that specifies the extended attribute information. The Length parameter reflects the length of this buffer, 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 FILE_FULL_EA_INFORMATION structure; please refer to the Microsoft's documentation for more information.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_set_file_attributes Event (CBMonitor Struct)

This event fires when a file or directory's attributes or times have been changed.

Syntax

// CBMonitorNotifySetFileAttributesEventArgs carries the CBMonitor NotifySetFileAttributes event's parameters.
pub struct CBMonitorNotifySetFileAttributesEventArgs {
  fn file_name(&self) -> &String
  fn creation_time(&self) -> &chrono::DateTime<Utc>
  fn last_access_time(&self) -> &chrono::DateTime<Utc>
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn change_time(&self) -> &chrono::DateTime<Utc>
  fn attributes(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifySetFileAttributesEvent defines the signature of the CBMonitor NotifySetFileAttributes event's handler function.
pub trait CBMonitorNotifySetFileAttributesEvent {
  fn on_notify_set_file_attributes(&self, sender : CBMonitor, e : &mut CBMonitorNotifySetFileAttributesEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_set_file_attributes(&self) -> &'a dyn CBMonitorNotifySetFileAttributesEvent;
  pub fn set_on_notify_set_file_attributes(&mut self, value : &'a dyn CBMonitorNotifySetFileAttributesEvent);
  ...
}

Remarks

This event fires when the attributes or times of the file or directory specified by FileName have been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The CreationTime, LastAccessTime, LastWriteTime, and ChangeTime parameters reflect the new time values, specified . A value of January 1, 1601 00:00:00 UTC indicates that the corresponding time value was not included in the request.

The Attributes parameter reflects the new attributes; please refer to Microsoft's File Attribute Constants article for attribute descriptions.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_set_file_info Event (CBMonitor Struct)

This event fires when information about a file or directory has been changed.

Syntax

// CBMonitorNotifySetFileInfoEventArgs carries the CBMonitor NotifySetFileInfo event's parameters.
pub struct CBMonitorNotifySetFileInfoEventArgs {
  fn file_name(&self) -> &String
  fn file_information_class(&self) -> i32
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn valid_bytes(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifySetFileInfoEvent defines the signature of the CBMonitor NotifySetFileInfo event's handler function.
pub trait CBMonitorNotifySetFileInfoEvent {
  fn on_notify_set_file_info(&self, sender : CBMonitor, e : &mut CBMonitorNotifySetFileInfoEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_set_file_info(&self) -> &'a dyn CBMonitorNotifySetFileInfoEvent;
  pub fn set_on_notify_set_file_info(&mut self, value : &'a dyn CBMonitorNotifySetFileInfoEvent);
  ...
}

Remarks

This event fires when information about a file or directory specified by FileName has been changed. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic. This event typically fires in response to the Windows API's NtSetInformationFile function.

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

The FileInformationClass parameter indicates what kind of file information was set. Please refer to the NtSetInformationFile function's documentation for more information about possible values.

The Buffer parameter points to a memory buffer that, if the request was successful, contains the new file information. The BufferLength and ValidBytes parameters reflect the capacity of Buffer and the length of the data it contains (respectively), in bytes; ValidBytes may be less than BufferLength. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The format of the data is determined by the specified FileInformationClass; please refer to the NtSetInformationFile function's documentation for more information.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_set_file_security Event (CBMonitor Struct)

This event fires when a file or directory's security attributes have been changed.

Syntax

// CBMonitorNotifySetFileSecurityEventArgs carries the CBMonitor NotifySetFileSecurity event's parameters.
pub struct CBMonitorNotifySetFileSecurityEventArgs {
  fn file_name(&self) -> &String
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifySetFileSecurityEvent defines the signature of the CBMonitor NotifySetFileSecurity event's handler function.
pub trait CBMonitorNotifySetFileSecurityEvent {
  fn on_notify_set_file_security(&self, sender : CBMonitor, e : &mut CBMonitorNotifySetFileSecurityEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_set_file_security(&self) -> &'a dyn CBMonitorNotifySetFileSecurityEvent;
  pub fn set_on_notify_set_file_security(&mut self, value : &'a dyn CBMonitorNotifySetFileSecurityEvent);
  ...
}

Remarks

This event fires when security attributes have been changed for a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, were to be set. 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 new 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.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_set_file_size Event (CBMonitor Struct)

This event fires when a file has been resized.

Syntax

// CBMonitorNotifySetFileSizeEventArgs carries the CBMonitor NotifySetFileSize event's parameters.
pub struct CBMonitorNotifySetFileSizeEventArgs {
  fn file_name(&self) -> &String
  fn size(&self) -> i64
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifySetFileSizeEvent defines the signature of the CBMonitor NotifySetFileSize event's handler function.
pub trait CBMonitorNotifySetFileSizeEvent {
  fn on_notify_set_file_size(&self, sender : CBMonitor, e : &mut CBMonitorNotifySetFileSizeEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_set_file_size(&self) -> &'a dyn CBMonitorNotifySetFileSizeEvent;
  pub fn set_on_notify_set_file_size(&mut self, value : &'a dyn CBMonitorNotifySetFileSizeEvent);
  ...
}

Remarks

This event fires when the file specified by FileName has been resized, whether explicitly (e.g., truncation) or implicitly (i.e., as data are appended). For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Size parameter reflects the new file size, in bytes.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_set_reparse_point Event (CBMonitor Struct)

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

Syntax

// CBMonitorNotifySetReparsePointEventArgs carries the CBMonitor NotifySetReparsePoint event's parameters.
pub struct CBMonitorNotifySetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_tag(&self) -> i64
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifySetReparsePointEvent defines the signature of the CBMonitor NotifySetReparsePoint event's handler function.
pub trait CBMonitorNotifySetReparsePointEvent {
  fn on_notify_set_reparse_point(&self, sender : CBMonitor, e : &mut CBMonitorNotifySetReparsePointEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_set_reparse_point(&self) -> &'a dyn CBMonitorNotifySetReparsePointEvent;
  pub fn set_on_notify_set_reparse_point(&mut self, value : &'a dyn CBMonitorNotifySetReparsePointEvent);
  ...
}

Remarks

This event fires when a reparse point has been created or updated for a file or directory specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The ReparseTag parameter contains the reparse tag, which is the value the system uses to identify the format of the reparse point data.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_unlock_all Event (CBMonitor Struct)

This event fires when all locked byte ranges in a file have been unlocked.

Syntax

// CBMonitorNotifyUnlockAllEventArgs carries the CBMonitor NotifyUnlockAll event's parameters.
pub struct CBMonitorNotifyUnlockAllEventArgs {
  fn file_name(&self) -> &String
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyUnlockAllEvent defines the signature of the CBMonitor NotifyUnlockAll event's handler function.
pub trait CBMonitorNotifyUnlockAllEvent {
  fn on_notify_unlock_all(&self, sender : CBMonitor, e : &mut CBMonitorNotifyUnlockAllEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_unlock_all(&self) -> &'a dyn CBMonitorNotifyUnlockAllEvent;
  pub fn set_on_notify_unlock_all(&mut self, value : &'a dyn CBMonitorNotifyUnlockAllEvent);
  ...
}

Remarks

This event fires when all locked byte ranges in the file specified by FileName have been unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

Applications need to handle this event only if they have added a standard filter rule that includes the FS_NE_LOCK_CONTROL 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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_unlock_all_by_key Event (CBMonitor Struct)

This event fires when all locked byte ranges in a file, associated with a particular key, have been unlocked.

Syntax

// CBMonitorNotifyUnlockAllByKeyEventArgs carries the CBMonitor NotifyUnlockAllByKey event's parameters.
pub struct CBMonitorNotifyUnlockAllByKeyEventArgs {
  fn file_name(&self) -> &String
  fn key(&self) -> i64
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyUnlockAllByKeyEvent defines the signature of the CBMonitor NotifyUnlockAllByKey event's handler function.
pub trait CBMonitorNotifyUnlockAllByKeyEvent {
  fn on_notify_unlock_all_by_key(&self, sender : CBMonitor, e : &mut CBMonitorNotifyUnlockAllByKeyEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_unlock_all_by_key(&self) -> &'a dyn CBMonitorNotifyUnlockAllByKeyEvent;
  pub fn set_on_notify_unlock_all_by_key(&mut self, value : &'a dyn CBMonitorNotifyUnlockAllByKeyEvent);
  ...
}

Remarks

This event fires when all locked byte ranges in the file specified by FileName, and associated with the specified Key, have been unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Key parameter contains the key value specified when the byte ranges were locked. Please refer to the on_notify_lock event's documentation for more information.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_unlock_single Event (CBMonitor Struct)

This event fires when a particular locked byte range in a file has been unlocked.

Syntax

// CBMonitorNotifyUnlockSingleEventArgs carries the CBMonitor NotifyUnlockSingle event's parameters.
pub struct CBMonitorNotifyUnlockSingleEventArgs {
  fn file_name(&self) -> &String
  fn offset(&self) -> i64
  fn length(&self) -> i64
  fn key(&self) -> i64
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyUnlockSingleEvent defines the signature of the CBMonitor NotifyUnlockSingle event's handler function.
pub trait CBMonitorNotifyUnlockSingleEvent {
  fn on_notify_unlock_single(&self, sender : CBMonitor, e : &mut CBMonitorNotifyUnlockSingleEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_unlock_single(&self) -> &'a dyn CBMonitorNotifyUnlockSingleEvent;
  pub fn set_on_notify_unlock_single(&mut self, value : &'a dyn CBMonitorNotifyUnlockSingleEvent);
  ...
}

Remarks

This event fires when a particular locked byte range in a file specified by FileName has been unlocked. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Offset, Length, and Key parameters contain the starting byte offset, length, and key values, respectively, specified when the byte range was locked. Please refer to the on_notify_lock event's documentation for more information.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_notify_write_file Event (CBMonitor Struct)

This event fires when data have been written to a file.

Syntax

// CBMonitorNotifyWriteFileEventArgs carries the CBMonitor NotifyWriteFile event's parameters.
pub struct CBMonitorNotifyWriteFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn bytes_to_write(&self) -> i32
  fn direction(&self) -> i32
  fn bytes_written(&self) -> i32
  fn status(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorNotifyWriteFileEvent defines the signature of the CBMonitor NotifyWriteFile event's handler function.
pub trait CBMonitorNotifyWriteFileEvent {
  fn on_notify_write_file(&self, sender : CBMonitor, e : &mut CBMonitorNotifyWriteFileEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_notify_write_file(&self) -> &'a dyn CBMonitorNotifyWriteFileEvent;
  pub fn set_on_notify_write_file(&mut self, value : &'a dyn CBMonitorNotifyWriteFileEvent);
  ...
}

Remarks

This event fires when data have been written to the file specified by FileName. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

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

The Position parameter reflects the byte offset in the file at which writing started. A value of -1 means "append to the end of the file".

The BytesToWrite parameter reflects how many bytes were to be written to the file.

The Direction parameter indicates the request direction; please refer to the Cached and Non-Cached Requests topic for more information. Possible values are as follows:

The BytesWritten parameter reflects how many bytes were actually written to the file.

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 nt_status_to_win32_error method.

Note: This event will not fire for failed requests unless the process_failed_requests 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 Handling topic for more information.

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

on_worker_thread_creation Event (CBMonitor Struct)

Fires just after a new worker thread is created.

Syntax

// CBMonitorWorkerThreadCreationEventArgs carries the CBMonitor WorkerThreadCreation event's parameters.
pub struct CBMonitorWorkerThreadCreationEventArgs {
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBMonitorWorkerThreadCreationEvent defines the signature of the CBMonitor WorkerThreadCreation event's handler function.
pub trait CBMonitorWorkerThreadCreationEvent {
  fn on_worker_thread_creation(&self, sender : CBMonitor, e : &mut CBMonitorWorkerThreadCreationEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_worker_thread_creation(&self) -> &'a dyn CBMonitorWorkerThreadCreationEvent;
  pub fn set_on_worker_thread_creation(&mut self, value : &'a dyn CBMonitorWorkerThreadCreationEvent);
  ...
}

Remarks

This event fires just after a worker thread is created, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing when a new worker thread is created, such as allocating per-thread objects.

The struct maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic 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 Handling topic for more information.

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

on_worker_thread_termination Event (CBMonitor Struct)

Fires just before a worker thread is terminated.

Syntax

// CBMonitorWorkerThreadTerminationEventArgs carries the CBMonitor WorkerThreadTermination event's parameters.
pub struct CBMonitorWorkerThreadTerminationEventArgs {
}

// CBMonitorWorkerThreadTerminationEvent defines the signature of the CBMonitor WorkerThreadTermination event's handler function.
pub trait CBMonitorWorkerThreadTerminationEvent {
  fn on_worker_thread_termination(&self, sender : CBMonitor, e : &mut CBMonitorWorkerThreadTerminationEventArgs);
}

impl <'a> CBMonitor<'a> {
  pub fn on_worker_thread_termination(&self) -> &'a dyn CBMonitorWorkerThreadTerminationEvent;
  pub fn set_on_worker_thread_termination(&mut self, value : &'a dyn CBMonitorWorkerThreadTerminationEvent);
  ...
}

Remarks

This event fires just before a worker thread is terminated, in the context of that worker thread.

This event is optional; it is provided to give applications a chance to perform additional processing before a worker thread is terminated, such as deallocating per-thread objects.

The struct maintains a pool of worker threads and uses them to fire events; please refer to the Threading and Concurrency topic for more information.

Any errors that occur during this event are ignored.

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

Config Settings (CBMonitor Struct)

The struct accepts one or more of the following configuration settings. Configuration settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the struct, access to these internal properties is provided through the config method.

CBMonitor Config Settings

Base Config Settings

Trappable Errors (CBMonitor Struct)

The struct uses Windows error codes during operation as necessary. Please refer to the Error Handling topic for more information.

Special Use Errors