Struct cbfsfilter::CBFilter

Properties   Methods   Events   Config Settings   Errors  

The CBFilter struct allows applications to intercept and control filesystem requests.

Syntax

cbfsfilter::CBFilter

Remarks

The CBFilter struct gives applications the ability to intercept filesystem requests, allowing them to be altered, handled, or blocked. Applications use standard filter rules to specify which requests they are interested in intercepting; and special filter rules to enforce access restrictions and redirect requests to different files.

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 with 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 CBFilter 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 or removed after the filter is started.)
4. Call the start_filter method to start filtering filesystem requests.
5. When finished, call the stop_filter method to stop filtering 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 CBFilter struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of CBFilter 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 (CBFilter 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 (CBFilter 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

default_rule_count Property (CBFilter Struct)

The number of records in the DefaultRule arrays.

Syntax

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

Default Value

0

Remarks

This property controls the size of the following arrays:

• default_rule_access_flags
• default_rule_mask

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

This property is read-only.

Data Type

i32

default_rule_access_flags Property (CBFilter Struct)

This property indicates the access restrictions enforced by the rule.

Syntax

fn default_rule_access_flags(&self , DefaultRuleIndex : i32) -> Result<i32, CBFSFilterError> 

Default Value

0

Remarks

This property indicates the access restrictions enforced by the rule.

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

The DefaultRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DefaultRuleCount property.

This property is read-only.

Data Type

i32

default_rule_mask Property (CBFilter Struct)

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

Syntax

fn default_rule_mask(&self , DefaultRuleIndex : 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 DefaultRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the DefaultRuleCount property.

This property is read-only.

Data Type

String

file_flushing_behavior Property (CBFilter Struct)

This property specifies the file flushing and closing behavior that the struct's system driver should enforce.

Syntax

fn file_flushing_behavior(&self ) -> Result<i32, CBFSFilterError> 
fn set_file_flushing_behavior(&self, value : i32) ->  Option<CBFSFilterError> 

Default Value

0

Remarks

This property specifies what file flushing and closing behaviors the struct's system driver should enforce.

Applications that modify file data as it is being read or written may need to change this property's value to function correctly. For example, applications that provide on-the-fly encryption should choose the proper flags to ensure that other applications that have opened the files being encrypted cannot accidentally write nonencrypted data to the disk.

Applications that do not modify file data as it is being read or written can leave this property unchanged.

The value of this property should be constructed by ORing together zero or more of the following flags:

Data Type

i32

filter_rule_count Property (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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

reparse_rule_count Property (CBFilter Struct)

The number of records in the ReparseRule arrays.

Syntax

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

Default Value

0

Remarks

This property controls the size of the following arrays:

• reparse_rule_mask
• reparse_rule_reparse_mask

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

This property is read-only.

Data Type

i32

reparse_rule_mask Property (CBFilter Struct)

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

Syntax

fn reparse_rule_mask(&self , ReparseRuleIndex : 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 ReparseRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ReparseRuleCount property.

This property is read-only.

Data Type

String

reparse_rule_reparse_mask Property (CBFilter Struct)

This property contains a file mask that specifies where matching files and directories are redirected to.

Syntax

fn reparse_rule_reparse_mask(&self , ReparseRuleIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

Remarks

This property contains a file mask that specifies where matching files and directories are redirected to.

This property contains a file mask that specifies where files and directories that match reparse_rule_mask are redirected to. Please refer to the Reparse Rules topic for more information.

The ReparseRuleIndex parameter specifies the index of the item in the array. The size of the array is controlled by the ReparseRuleCount property.

This property is read-only.

Data Type

String

serialize_events Property (CBFilter 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 (CBFilter 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

virtual_file_count Property (CBFilter Struct)

The number of records in the VirtualFile arrays.

Syntax

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

Default Value

0

Remarks

This property controls the size of the following arrays:

• virtual_file_attributes
• virtual_file_change_time
• virtual_file_creation_time
• virtual_file_last_access_time
• virtual_file_last_write_time
• virtual_file_name
• virtual_file_nt_native_name
• virtual_file_size

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

This property is read-only.

Data Type

i32

virtual_file_attributes Property (CBFilter Struct)

This property specifies various attributes of a virtual file.

Syntax

fn virtual_file_attributes(&self , VirtualFileIndex : i32) -> Result<i32, CBFSFilterError> 

Default Value

0

Remarks

This property specifies various attributes of a virtual file.

This property specifies the attributes of the virtual file. The initial value is set to the one provided when the file was added to the list using add_virtual_file. An application may update the values using the update_virtual_file.

Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

i32

virtual_file_change_time Property (CBFilter Struct)

This property contains the time of the latest update of the metadata of a virtual file.

Syntax

fn virtual_file_change_time(&self , VirtualFileIndex : i32) -> Result<chrono::DateTime<Utc>, CBFSFilterError> 

Default Value

chrono::DateTime::from_timestamp(0, 0).unwrap()

Remarks

This property contains the time of the latest update of the metadata of a virtual file.

This property contains the time of the latest update of the metadata of the virtual file, specified . The initial value is set to the one provided when the file was added to the list using add_virtual_file. An application may update the values using the update_virtual_file.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

chrono::DateTime

virtual_file_creation_time Property (CBFilter Struct)

This property contains the time of creation of a virtual file.

Syntax

fn virtual_file_creation_time(&self , VirtualFileIndex : i32) -> Result<chrono::DateTime<Utc>, CBFSFilterError> 

Default Value

chrono::DateTime::from_timestamp(0, 0).unwrap()

Remarks

This property contains the time of creation of a virtual file.

This property contains the time of creation of the virtual file, specified . The initial value is set to the one provided when the file was added to the list using add_virtual_file. An application may update the values using the update_virtual_file.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

chrono::DateTime

virtual_file_last_access_time Property (CBFilter Struct)

This property contains the time of the latest access to a virtual file.

Syntax

fn virtual_file_last_access_time(&self , VirtualFileIndex : i32) -> Result<chrono::DateTime<Utc>, CBFSFilterError> 

Default Value

chrono::DateTime::from_timestamp(0, 0).unwrap()

Remarks

This property contains the time of the latest access to a virtual file.

This property contains the time of the latest access to the virtual file, specified . The initial value is set to the one provided when the file was added to the list using add_virtual_file. An application may update the values using the update_virtual_file.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

chrono::DateTime

virtual_file_last_write_time Property (CBFilter Struct)

This property contains the time of the latest modification of the data of a virtual file.

Syntax

fn virtual_file_last_write_time(&self , VirtualFileIndex : i32) -> Result<chrono::DateTime<Utc>, CBFSFilterError> 

Default Value

chrono::DateTime::from_timestamp(0, 0).unwrap()

Remarks

This property contains the time of the latest modification of the data of a virtual file.

This property contains the time of the latest modification of the data of the virtual file, specified . The initial value is set to the one provided when the file was added to the list using add_virtual_file. An application may update the values using the update_virtual_file.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

chrono::DateTime

virtual_file_name Property (CBFilter Struct)

This property contains the name name of a virtual file.

Syntax

fn virtual_file_name(&self , VirtualFileIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

Remarks

This property contains the name name of a virtual file.

This property contains the path and the name of the added file as they were specified in a call to add_virtual_file. The name is converted to the NT native format internally when the file or directory is added to the list.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

String

virtual_file_nt_native_name Property (CBFilter Struct)

This property contains the name name of a virtual file in NT native format.

Syntax

fn virtual_file_nt_native_name(&self , VirtualFileIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

Remarks

This property contains the name name of a virtual file in NT native format.

This property contains the path and the name of the added file; the contained path is in the NT native format.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

String

virtual_file_size Property (CBFilter Struct)

This property specifies the size of a virtual file.

Syntax

fn virtual_file_size(&self , VirtualFileIndex : i32) -> Result<i64, CBFSFilterError> 

Default Value

0

Remarks

This property specifies the size of a virtual file.

This property specifies the size of the virtual file. The initial value is set to the one provided when the file was added to the list using add_virtual_file. An application may update the values using the update_virtual_file.

Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The VirtualFileIndex parameter specifies the index of the item in the array. The size of the array is controlled by the VirtualFileCount property.

This property is read-only.

Data Type

i64

add_default_rule Method (CBFilter Struct)

This method adds a default rule.

Syntax

fn add_default_rule(&self, mask : &String, access_flags : i32, product_guid : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method adds a default 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.

Default rules, like access rules, instruct the struct's system driver to apply certain access restrictions to matching files and directories. However, unlike access rules, default rules are managed by the driver directly; they are activated as soon as the driver loads at boot time, and then continue to be enforced at all times, regardless of whether the application that added them is open.

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 AccessFlags parameter specifies which access restrictions the struct's system driver should apply to matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

The ProductGUID parameter identifies the application that the rule should be associated with in the registry. In most cases, the value passed for this parameter should be the same one that was used to call the initialize method.

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. Please refer to the Default Rules topic for more information.

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 Method (CBFilter Struct)

This method adds a standard filter rule or access rule.

Syntax

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

Remarks

This method adds a standard filter rule or access 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. Access rules instruct the struct's system driver to apply certain access restrictions to matching files and directories.

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 AccessFlags parameter specifies which access restrictions the struct's system driver should apply to matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

The ControlFlags parameter specifies which filesystem operations the struct should fire Control Events for. For example, if the FS_CE_BEFORE_READ and FS_CE_AFTER_READ flags are present, the on_before_read_file and on_after_read_file events will fire before and 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 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 (CBFilter Struct)

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

Syntax

fn add_filter_rule_ex(&self, mask : &String, ea_name : &String, access_flags : i32, control_flags : i64, 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 or access 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. Access rules instruct the struct's system driver to apply certain access restrictions to matching files and directories.

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 AccessFlags parameter specifies which access restrictions the struct's system driver should apply to matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

The ControlFlags parameter specifies which filesystem operations the struct should fire Control Events for. For example, if the FS_CE_BEFORE_READ and FS_CE_AFTER_READ flags are present, the on_before_read_file and on_after_read_file events will fire before and 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 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 (CBFilter Struct)

This method adds a passthrough rule.

Syntax

fn add_passthrough_rule(&self, mask : &String, access_flags : i32, control_flags : i64, 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 AccessFlags parameter specifies which access restrictions the struct's system driver should lift from matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

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

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 (CBFilter Struct)

This method adds a passthrough rule with additional match qualifiers.

Syntax

fn add_passthrough_rule_ex(&self, mask : &String, ea_name : &String, access_flags : i32, control_flags : i64, 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 AccessFlags parameter specifies which access restrictions the struct's system driver should lift from matching files and directories. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

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

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.

add_reparse_rule Method (CBFilter Struct)

This method adds a reparse rule.

Syntax

fn add_reparse_rule(&self, mask : &String, reparse_mask : &String, product_guid : &String, flags : i32) ->  Result<bool, CBFSFilterError>

Remarks

This method adds a reparse 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 replaces it.

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

Reparse rules are used to redirect access from a file or directory covered by Mask to another location in the filesystem, specified by ReparseMask.

The Mask and ReparseMask parameters must be valid file masks according to the File Masks topic. Only the files and directories that match Mask will be covered by the rule (i.e., redirected to the path specified by ReparseMask). For example, passing *.txt for Mask and *_1.txt for ReparseMask would cause, for example, test.txt to be redirected to test_1.txt.

More generally, for each wildcard (* or ?) present in Mask, there must be a corresponding wildcard (of the same type) in ReparseMask; and the wildcards in ReparseMask must appear in the same order as they do in Mask. For example, if Mask is 20??_Budget.*, then 20??_Budget_Report.* would be a legal value for ReparseMask; but 20??_Budget_Report.xls would not be, nor would 20*_Budget_Report.*.

The ProductGUID parameter identifies the application that the rule should be associated with in the registry. In most cases, the value passed for this parameter should be the same one that was used to call the initialize method.

The Flags parameter specifies how, exactly, the redirection should be performed. Possible values are as follows:

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_virtual_file Method (CBFilter Struct)

This method adds a virtual file to the list of virtual entries and makes it visible in the filesystem.

Syntax

fn add_virtual_file(&self, file_name : &String, creation_time : &chrono::DateTime<Utc>, last_access_time : &chrono::DateTime<Utc>, last_write_time : &chrono::DateTime<Utc>, change_time : &chrono::DateTime<Utc>, size : i64, attributes : i32) ->  Result<bool, CBFSFilterError>

Remarks

This method creates or opens a virtual file and adds it to the list of virtual entries, managed by the struct. If the struct is active, the virtual file also appears in the filesystem. Virtual directories are not supported.

The struct stores the creation parameters in the list. Adding the same file name several times will create only one list entry for each distinct file name, and subsequent calls to add_virtual_file with different parameters will be ignored. To update properties of the file that is already in the list, use the update_virtual_file method. To remove the file from the list, use the remove_virtual_file method.

The FileName parameter must contain the full path and name of the file being added. The drive on which the file resides may be referenced in one of following formats:

• A volume GUID, formatted like Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} . A path may start with the \\?\ prefix, such as "\\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}".
• A DOS name, formatted like C:\.
• A volume NT-native name, formatted like \Device\HarddiskVolumeX\, where X is the number of the volume.

To successfully add a virtual file, the volume in the path must already be present on the system.

Note: if an application adds multiple files to the same drive, it is more efficient to convert a GUID-based or a DOS-name-based volume name to the NT-native format using the get_nt_path_name method, then use the obtained NT-native volume name in the calls to this add_virtual_file method.

CreationTime, LastAccessTime, LastWriteTime, ChangeTime must specify the corresponding time values for the file, specified .

Size must be set to the size of the file. It may be 0 for an empty file or a positive value.

Attributes must be set to the file's attributes. Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The method will return true if the file was added to the list and false if the file is already present in the list. An error will be reported if adding the file failed on the driver side.

close_default_rules_snapshot Method (CBFilter Struct)

This method closes the previously created default rules snapshot.

Syntax

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

Remarks

This method closes the default rules snapshot previously created by create_default_rules_snapshot, releasing the memory associated with it. Please refer to that method's documentation for more information.

Note: This method cannot be called within events.

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.

close_reparse_rules_snapshot Method (CBFilter Struct)

This method closes the previously created reparse rules snapshot.

Syntax

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

Remarks

This method closes the reparse rules snapshot previously created by create_reparse_rules_snapshot, releasing the memory associated with it. Please refer to that method's documentation for more information.

Note: This method cannot be called within events.

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 (CBFilter 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.

create_default_rules_snapshot Method (CBFilter Struct)

This method creates a snapshot of information about the default rules that have been added.

Syntax

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

Remarks

This method creates a snapshot of information about all default rules that have been added by the application identified by ProductGUID. This information is then used to populate the DefaultRule* properties.

When the application is finished working with the default rules snapshot, it must close it by calling the close_default_rules_snapshot method to release the associated memory. If this method is called again before an existing snapshot is closed, the struct will attempt to close it before creating a new one.

Note: This method cannot be called within events.

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.

create_file_direct Method (CBFilter Struct)

This method creates or opens a file or directory by passing the request directly to the filesystem.

Syntax

fn create_file_direct(&self, file_name : &String, synchronize : bool, desired_access : i32, share_mode : i32, creation_disposition : i32, flags_and_attributes : i32, close_immediately : bool, send_via_stack : bool) ->  Result<i64, CBFSFilterError>

Remarks

This method should be used instead of the Windows API's CreateFile function to create or open a file or directory when an application needs to access this file without sending requests through the complete filesystem filter driver stack.

The parameters of this method correspond to the parameters of the CreateFile function.

If the file or directory is created or opened successfully, this method returns a file handle for it; otherwise, it returns INVALID_HANDLE_VALUE. The returned handle, if valid, must be closed using the Windows API's CloseHandle function when the application is finished with it. See the "Use of Handle" section below for details of how to use the handle.

If CloseImmediately is true, this method will create or open the specified file or directory and then immediately close the resulting handle. In this case, the handle will still be returned to indicate the success of the operation, but it will not be usable in any file operations.

The SendViaStack parameter specifies how the driver should send the request for opening the file as well as other requests that will be sent using the opened file handle. When this parameter is false, requests made by the application using the handle, created by the create_file_direct method, are sent directly to the filesystem. When some filter drivers are located lower in the driver stack than the CBFilter driver, such requests will bypass that filter drivers with possibly unexpected consequences (e.g., requests going to the wrong file, wrong data being read or written). Set this parameter to true to make the driver pass these requests down the filter stack, letting them reach other filter drivers before the filesystem.

When the SendViaStack parameter is false, requests against the returned file handle are routed directly to the filesystem (bypassing all filter drivers, including the struct's); applications can use it to call the Windows File API functions (ReadFile, WriteFile) within filesystem-related events without causing a system deadlock. However, pay special attention to the Synchronize parameter's documentation, which is given below.

The FileName, DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters correspond to the lpFileName, dwDesiredAccess, dwCreationDisposition, and dwFlagsAndAttributes parameters of the Windows API's CreateFile function (respectively).

Please refer to Microsoft's documentation for more information about how to set these parameters appropriately.

The CreationDisposition parameter should be set to one of the valid values and may not be 0. If any of these requirements is not met, the ERROR_INVALID_PARAMETER error is returned.

The ShareMode parameter should be set by ORing together zero or more of the following flags:

The Synchronize parameter specifies whether this method and operations with the resulting handle should be synchronized with the thread that originated the underlying filesystem request associated with the current event (i.e., the event that this method was called from).

The parameter is applicable only when a caller uses it to open the file, for which the event was fired, when isolation is not used. If the file create/open operation is isolated (the handler sets the Isolate parameter of the corresponding event to true), the application may safely set Synchronize to false. Also, the parameter should not be set to true when this method is called from the on_after_close_file event; when the event is fired, no file is open to synchronize operations with.

It is recommended to set Synchronize to true when the method is called from on_after_create_file and on_after_open_file event handlers. This helps prevent possible deadlocks in other filter drivers.

Please refer to Direct File operations for additional information about the use of a handle or a stream obtained using this method.

create_file_direct_as_stream Method (CBFilter Struct)

This method creates or opens a file by passing the request directly to the filesystem.

Syntax

fn create_file_direct_as_stream(&self, file_name : &String, synchronize : bool, desired_access : i32, share_mode : i32, creation_disposition : i32, flags_and_attributes : i32, send_via_stack : bool, handle : &mut i64) ->  Result<CBFSFilterStream, CBFSFilterError>

Remarks

This method should be used instead of the Windows API's CreateFile function to create or open a file when an application needs to access this file without sending requests through the complete filesystem filter driver stack.

The parameters of this method correspond to the parameters of the CreateFile function.

If the file is created or opened successfully, this method returns a stream object that provides access to its data; otherwise, it returns .

Upon success, the Handle parameter is populated with the file handle value. This handle value does not need to be closed - the struct will do this automatically when the stream is closed. See the "Use of Handle" section below for details of how to use the handle.

The SendViaStack parameter specifies how the driver should send the request for opening the file as well as other requests that will be sent using the opened file handle. When this parameter is false, requests made by the application using the handle, created by the create_file_direct method, are sent directly to the filesystem. When some filter drivers are located lower in the driver stack than the CBFilter driver, such requests will bypass that filter drivers with possibly unexpected consequences (e.g., requests going to the wrong file, wrong data being read or written). Set this parameter to true to make the driver pass these requests down the filter stack, letting them reach other filter drivers before the filesystem.

When the SendViaStack parameter is false, requests against the opened file are routed directly to the filesystem (bypassing all filter drivers, including the struct's); applications can use it within filesystem-related events without causing a system deadlock. However, pay special attention to the Synchronize parameter's documentation, which is given below.

The FileName, DesiredAccess, CreationDisposition, and FlagsAndAttributes parameters correspond to the lpFileName, dwDesiredAccess, dwCreationDisposition, and dwFlagsAndAttributes parameters of the Windows API's CreateFile function (respectively).

Please refer to Microsoft's documentation for more information about how to set these parameters appropriately.

The CreationDisposition parameter should be set to one of the valid values and may not be 0. If any of these requirements is not met, the ERROR_INVALID_PARAMETER error is returned.

The ShareMode parameter should be set by ORing together zero or more of the following flags:

The Synchronize parameter specifies whether this method and operations with the resulting handle should be synchronized with the thread that originated the underlying filesystem request associated with the current event (i.e., the event that this method was called from).

The parameter is applicable only when a caller uses it to open the file, for which the event was fired, when isolation is not used. If the file create/open operation is isolated (the handler sets the Isolate parameter of the corresponding event to true), the application may safely set Synchronize to false. Also, the parameter should not be set to true when this method is called from the on_after_close_file event; when the event is fired, no file is open to synchronize operations with.

It is recommended to set Synchronize to true when the method is called from on_after_create_file and on_after_open_file event handlers. This helps prevent possible deadlocks in other filter drivers.

Please refer to Direct File operations for additional information about the use of a handle or a stream obtained using this method.

create_reparse_rules_snapshot Method (CBFilter Struct)

This method creates a snapshot of information about the reparse rules that have been added.

Syntax

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

Remarks

This method creates a snapshot of information about all reparse rules that have been added by the application identified by ProductGUID. This information is then used to populate the ReparseRule* properties.

When the application is finished working with the reparse rules snapshot, it must close it by calling the close_reparse_rules_snapshot method to release the associated memory. If this method is called again before an existing snapshot is closed, the struct will attempt to close it before creating a new one.

Note: This method cannot be called within events.

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_filter_rules Method (CBFilter Struct)

This method deletes all standard filter rules and access rules.

Syntax

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

Remarks

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

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

To delete standard filter rules or access 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 (CBFilter 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_all_reparse_rules Method (CBFilter Struct)

This method deletes all reparse rules.

Syntax

fn delete_all_reparse_rules(&self, product_guid : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method deletes all reparse rules associated with the application identified by ProductGUID.

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

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the initialize method. Please refer to the add_reparse_rule method's documentation for more information.

To delete reparse rules individually, use the delete_reparse_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_default_rule Method (CBFilter Struct)

This method deletes a particular default rule.

Syntax

fn delete_default_rule(&self, mask : &String, access_flags : i32, product_guid : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method deletes the specified AccessFlags from the default rule identified by Mask and associated with the application identified by ProductGUID. If AccessFlags includes all flags currently present in the rule, then the entire rule is deleted; otherwise, the flags specified by AccessFlags 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 AccessFlags parameter specifies which access restrictions 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:

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the initialize method. Please refer to the add_default_rule method's documentation for more information.

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. Please refer to the Default Rules topic for more information.

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 (CBFilter Struct)

This method deletes a particular standard filter rule or access rule.

Syntax

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

Remarks

This method deletes the specified AccessFlags, ControlFlags, and/or NotifyFlags from the standard filter rule and/or access rule identified by Mask. If the aforementioned parameters include all flags currently present in the rule, then the entire rule is deleted; otherwise, the specified flags 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 AccessFlags parameter specifies which access restrictions 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:

The ControlFlags parameter specifies which Control 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:

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 and access 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 (CBFilter Struct)

This method deletes a particular passthrough rule.

Syntax

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

Remarks

This method deletes the specified AccessFlags, ControlFlags, and/or NotifyFlags from the passthrough rule identified by Mask. If the aforementioned parameters include all flags currently present in the rule, then the entire rule is deleted; otherwise, the specified flags 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 AccessFlags parameter specifies which access restrictions 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:

The ControlFlags parameter specifies which Control 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:

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.

delete_reparse_rule Method (CBFilter Struct)

This method deletes a particular reparse rule.

Syntax

fn delete_reparse_rule(&self, mask : &String, product_guid : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method deletes the ReparseRules identified by Mask and associated with the application identified by ProductGUID.

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.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the initialize method. Please refer to the add_reparse_rule method's documentation for more information.

To delete all reparse rules, use the delete_all_reparse_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 (CBFilter 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_driver_status Method (CBFilter 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 (CBFilter 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 (CBFilter 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_handle_creator_process_id Method (CBFilter Struct)

This method retrieves the Id of the process (PID) that opened the file handle.

Syntax

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

Remarks

This method can be called within certain events to retrieve the Id of the process (PID) that opened the file handle. If the query fails, this method returns 0.

Note: PIDs are not unique and may be reused by different processes over time (although 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 the on_after_create_file and on_after_open_file events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the on_after_create_file or on_after_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 through the reference stored in HandleContext.

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

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

get_handle_creator_process_name Method (CBFilter Struct)

This method retrieves the name of the process that opened the file handle.

Syntax

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

Remarks

This method can be called within certain events to retrieve the name of the process that opened the file handle. If the query fails, this method returns an 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 the on_after_create_file and on_after_open_file events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the on_after_create_file or on_after_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 through the reference stored in HandleContext.

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

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

get_handle_creator_thread_id Method (CBFilter Struct)

This method retrieves the Id of the thread that opened the file handle.

Syntax

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

Remarks

This method can be called within certain events to retrieve the Id of the thread that opened the file handle. If the query fails, this method returns 0.

Notes: Thread Ids are not unique and may be reused by different threads over time.

Note: This method can be called only within the on_after_create_file and on_after_open_file events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the on_after_create_file or on_after_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 through the reference stored in HandleContext.

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

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

get_handle_creator_token Method (CBFilter Struct)

This method retrieves the security token associated with the process that opened the file handle.

Syntax

fn get_handle_creator_token(&self) ->  Result<i64, CBFSFilterError>

Remarks

This method can be called within certain events to retrieve the security token associated with the process that opened the file handle. If the query fails, this method returns INVALID_HANDLE_VALUE.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process.

Note: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

Applications monitoring a drive shared on the network may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

• Authenticated mode, in which case the network redirector (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
• Guest mode, in which case the retrievable information is for the system's GUEST account.
• Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

Note: This method can be called only within the on_after_create_file and on_after_open_file events, and must be called in the same thread that the event was originally fired on. Applications that need the information that this method returns during other events can do the following:

1. Call this method within the on_after_create_file or on_after_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 through the reference stored in HandleContext.

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

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

get_operation_time Method (CBFilter 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 (CBFilter 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 (CBFilter 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 (CBFilter 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_originator_token Method (CBFilter Struct)

Retrieves the security token associated with the process that initiated the operation.

Syntax

fn get_originator_token(&self) ->  Result<i64, CBFSFilterError>

Remarks

This method can be called within synchronous, i.e., Before* and After* events fired for filesystem operations to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE. Note: This method will not work properly when called from Notify* event handlers because security tokens are not kept for possible later use. If you need to obtain security information about a request, use corresponding After* events.

The security token returned by this method can be passed to the Windows API's GetTokenInformation function to obtain more information about the process.

Important: When applications are finished using the returned security token, they must close it using the Windows API's CloseHandle function.

Network Access Notes

Applications monitoring a drive shared on the network may wish to obtain information about the network users accessing it (e.g., account names). Drives can be shared in several modes in Windows, which can affect the information retrievable via the security token this method returns:

• Authenticated mode, in which case the network redirector (which, in general, is responsible for relaying remote drive requests to and from the system driver) will impersonate the network user, allowing that account's actual information to be retrieved.
• Guest mode, in which case the retrievable information is for the system's GUEST account.
• Administrative shares (those which exist by default and whose names end with '$'; e.g., C$, ADMIN$, etc.), in which case the retrievable information is for the LOCAL_SYSTEM account.

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 (CBFilter 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_reparse_rule_by_mask Method (CBFilter Struct)

This method retrieves the reparse rule associated with the specified file mask.

Syntax

fn get_reparse_rule_by_mask(&self, mask : &String, product_guid : &String) ->  Result<String, CBFSFilterError>

Remarks

This method retrieves the reparse rule identified by Mask and associated with the application identified by ProductGUID. If such a reparse rule is found, this method returns its reparse mask (see add_reparse_rule); otherwise, it returns empty string.

The Mask parameter must be the file mask of an existing rule.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the initialize method.

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.

get_volume_guid Method (CBFilter 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 (CBFilter 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 (CBFilter 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.

is_file_filtered Method (CBFilter Struct)

This method checks whether a particular file or directory is covered by any filter rules.

Syntax

fn is_file_filtered(&self, file_name : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method checks whether the file or directory specified by FileName is covered by any of the standard filter rules active currently (i.e., whether the struct would fire its events for one or more kinds of filesystem operations performed on it). If the specified file or directory matches any of the active standard filter rules, this method returns true; otherwise, it returns false.

Applications should use this method anytime they want to create/open some file or directory from within an event handler. If this method returns true, then the file or directory must be created/opened using the struct's create_file_direct method rather than the Windows API's CreateFile function, because the latter could trigger recursion and cause a system deadlock.

nt_status_to_win32_error Method (CBFilter 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).

query_file_information_direct Method (CBFilter Struct)

This method returns various kinds of information about a file object.

Syntax

fn query_file_information_direct(&self, file_handle : i64, file_information : &[u8], file_information_class : i32, bytes_transferred : &mut i32) -> Option<CBFSFilterError>

Remarks

Applications may call this method to query various kinds of information about the file or directory using the open handle. The method uses the NtQueryInformationFile Windows API function to retrieve the information.

The FileHandle parameter specifies the file that should be updated. The value passed for this parameter must be a file handle obtained from the create_file_direct method; please refer to its documentation for more information.

The InformationClass parameter specifies the class of information to be query. For the list of supported classes, please refer to the documentation of the Windows API's NtQueryInformationFile function.

FileInformation is a buffer that must contain the information queried. The exact size and format of the information depend on InformationClass and are described in the NtQueryInformationFile help topic.

BytesTrasferredThe actual bytes of information received on completion.

query_file_security_direct Method (CBFilter Struct)

This method retrieves security information of a file.

Syntax

fn query_file_security_direct(&self, file_handle : i64, security_information : i32, security_descriptor : &[u8], length_needed : &mut i32) -> Option<CBFSFilterError>

Remarks

Applications may call this method to query security attributes of the file or directory using the open handle. The method uses the NtQuerySecurityObject Windows API function to change the security attributes.

The FileHandle parameter specifies the file that should be queried. The value passed for this parameter must be a file handle obtained from the create_file_direct method; please refer to its documentation for more information.

The SecurityInformation parameter specifies the information to be queried as a combination of one or more of the following:

• OWNER_SECURITY_INFORMATION
• GROUP_SECURITY_INFORMATION
• DACL_SECURITY_INFORMATION
• SACL_SECURITY_INFORMATION

Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to the memory buffer that receives the requested data. It is available only if the length of the buffer is greater than 0. The data must be formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to these articles for more information about self-relative security descriptors.

The LengthNeeded parameter points to a caller-allocated variable that receives the number of bytes required to store the copied security descriptor.

remove_virtual_file Method (CBFilter Struct)

This method removes a virtual file from the list of virtual entries.

Syntax

fn remove_virtual_file(&self, file_name : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method removes a previously added virtual file identified by FileName from the list of virtual entries, managed by the struct.

The FileName parameter must contain the same value as the one used to add a virtual file earlier.

The method will return true if the file was found and removed from the list and false if the file was not found in the list. An error will be reported if removal of the file failed on the driver side.

reset_timeout Method (CBFilter Struct)

This method resets the timeout duration for the current event handler.

Syntax

fn reset_timeout(&self, timeout : i32) ->  Result<bool, CBFSFilterError>

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the struct that request processing is taking longer than expected.

If called successfully, this method returns true, and the current event handler's timeout timer is immediately reset to 0; when it reaches the number of milliseconds specified by Timeout, the driver will either "release" the underlying request and pass it onwards, or cancel it by reporting an error; whichever is most appropriate for the event in question. Please refer to the Timeouts topic for more information.

Passing 0 for Timeout disables the timeout timer for the current event handler, allowing it to take as long as it needs to complete.

Note: When several events are fired for the same file concurrently (if the SerializeAccess configuration setting is disabled), and reset_timeout is called from one of the handlers of these events, this method will reset the timer for all currently executed event handlers.

Note: This method can be called only within events.

set_file_information_direct Method (CBFilter Struct)

This method sets the file information of a file opened using CreateFileDirect.

Syntax

fn set_file_information_direct(&self, file_handle : i64, information_class : i32, file_information : &[u8]) -> Option<CBFSFilterError>

Remarks

Applications may call this method to change various kinds of information about a file that was opened using the create_file_direct method.

The FileHandle parameter specifies the file that should be updated. The value passed for this parameter must be a file handle obtained from the create_file_direct method; please refer to its documentation for more information.

The InformationClass parameter specifies the class of information to be set. For the list of supported classes, please refer to the documentation of the Windows API's FltSetInformationFile function.

Note: Only a limited subset of classes comparing to similar functions like NtSetInformationFile or NtQueryInformationFile is supported by this function.

FileInformation is a buffer that must contain the information to be set. The exact size and format of the information depend on InformationClass and are described in the FltSetInformationFile help topic.

set_file_security_direct Method (CBFilter Struct)

This method sets security information of a file.

Syntax

fn set_file_security_direct(&self, file_handle : i64, security_information : i32, security_descriptor : &[u8]) -> Option<CBFSFilterError>

Remarks

Applications may call this method to set security attributes of the file or directory using the open handle. The method uses the NtSetSecurityObject Windows API function to query the security attributes.

The FileHandle parameter specifies the file that should be updated. The value passed for this parameter must be a file handle obtained from the create_file_direct method; please refer to its documentation for more information.

The SecurityInformation parameter indicates which pieces of security information must be set. This value is a bitfield; possible flags include (but are not limited to):

• OWNER_SECURITY_INFORMATION
• GROUP_SECURITY_INFORMATION
• DACL_SECURITY_INFORMATION
• SACL_SECURITY_INFORMATION

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 data indicated by SecurityInformation. The data are formatted as a SECURITY_DESCRIPTOR structure in self-relative format. Please refer to those articles for more information about self-relative security descriptors.

set_file_size_direct Method (CBFilter Struct)

This method resizes a file by passing the request directly to the filesystem.

Syntax

fn set_file_size_direct(&self, file_handle : i64, size : i64) ->  Result<bool, CBFSFilterError>

Remarks

Applications can call this method in filesystem-related event handlers to resize a file without sending the request through the filesystem filter driver stack. If the file is resized successfully, this method returns true; otherwise, it returns false.

The FileHandle parameter specifies the file that should be resized. The value passed for this parameter must be a file handle obtained from the create_file_direct method; please refer to its documentation for more information.

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

To set file allocation size or valid file length, you may use the set_file_information_direct method.

Note: This method can be called only within events.

shutdown_system Method (CBFilter 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 (CBFilter Struct)

This method starts filtering filesystem operations.

Syntax

fn start_filter(&self, timeout : i32) -> 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, so 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.
• If an invalid value is passed for Timeout, this method fails with an ERROR_IMPLEMENTATION_LIMIT (1292) error code.

Timeout

Timeout specifies how many milliseconds the driver should wait for events to execute before releasing or cancelling the underlying OS requests; please refer to the Timeouts topic for more information. Valid values are 0, which disables event timeouts, and values greater than or equal to 3000. When event timeouts are in effect, event handlers can call reset_timeout to reset the timer if they require additional time to complete.

stop_filter Method (CBFilter 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.

suspend_default_rules Method (CBFilter Struct)

This method suspends all default rules until the application exits.

Syntax

fn suspend_default_rules(&self, product_guid : &String) ->  Result<bool, CBFSFilterError>

Remarks

This method suspends (i.e., deactivates) all default rules associated with the application identified by ProductGUID until the application exits. If the rules are suspended successfully, this method returns true; otherwise, it returns false.

In most cases, the value passed for the ProductGUID parameter should be the same one that was used to call the initialize method.

When the application exits, the struct's system driver will reactivate the suspended rules and start enforcing them once again.

suspend_file_events Method (CBFilter Struct)

This method suspends all events for a particular file or directory until all of its handles have been closed.

Syntax

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

Remarks

Applications can call this method from an on_after_create_file or on_after_open_file event to suspend all further events for the file or directory that the event fired for. The suspension will remain in effect until all handles to said file or directory have been closed, at which point the struct will once again fire events for it (if it is accessed again).

Typically, this method should be used only as a "last resort"; that is, when the application cannot achieve the same outcome through the use of more granular standard filter rules. Said another way, it is almost always more efficient for an application to exclude files or directories implicitly using standard filter rules, if possible, than it is to exclude them explicitly using this method.

Note: This method can be called only within the on_after_create_file and on_after_open_file events.

toggle_process_protection Method (CBFilter Struct)

This method enables or disables termination protection for the application.

Syntax

fn toggle_process_protection(&self, enabled : bool) ->  Result<bool, CBFSFilterError>

Remarks

This method controls the termination protection mechanism, which applications can enable to prevent their process and threads from being terminated. If successful, this method returns true; otherwise, it returns false.

The Enabled parameter specifies whether termination protection should be enabled (true) or disabled (false); it is disabled by default. If termination protection is enabled, an application must disable it before attempting to exit.

Note: When developing a GUI-based application, please keep in mind that the termination protection mechanism does not intercept Windows' notifications like WM_CLOSE or WM_QUIT; applications must intercept and handle such messages themselves if they wish to protect their UI. Please refer to Microsoft's Window Notifications articles for more information.

uninstall Method (CBFilter 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.

update_virtual_file Method (CBFilter Struct)

This method updates known information about a virtual file .

Syntax

fn update_virtual_file(&self, file_name : &String, creation_time : &chrono::DateTime<Utc>, last_access_time : &chrono::DateTime<Utc>, last_write_time : &chrono::DateTime<Utc>, change_time : &chrono::DateTime<Utc>, size : i64, attributes : i32) ->  Result<bool, CBFSFilterError>

Remarks

This method updates the information about the virtual file identified by FileName.

The FileName parameter must contain the same value as the one used to add a virtual file earlier.

CreationTime, LastAccessTime, LastWriteTime, ChangeTime should contain new time values for the file, specified ; any of the time values may be January 1, 1601 00:00:00 UTC to indicate that the existing value of the corresponding time must remain unchanged.

Size must be set to the new size of the file to update the known file size or to -1 to indicate that the size didn't change.

Attributes must be set to new file's attributes. Set this parameter to 0 to indicate that the existing attributes must remain unchanged.

• FILE_ATTRIBUTE_NORMAL: This attribute is valid only when used alone; it "resets" a file's attributes.
• Please refer to Microsoft's File Attribute Constants article for attribute descriptions.

The method will return true if the file was found and updated and false if the file was not found in the list. An error will be reported if updating the file failed on the driver side.

on_after_can_file_be_deleted Event (CBFilter Struct)

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

Syntax

// CBFilterAfterCanFileBeDeletedEventArgs carries the CBFilter AfterCanFileBeDeleted event's parameters.
pub struct CBFilterAfterCanFileBeDeletedEventArgs {
  fn file_name(&self) -> &String
  fn request_type(&self) -> i32
  fn can_delete(&self) -> bool
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterCanFileBeDeletedEvent defines the signature of the CBFilter AfterCanFileBeDeleted event's handler function.
pub trait CBFilterAfterCanFileBeDeletedEvent {
  fn on_after_can_file_be_deleted(&self, sender : CBFilter, e : &mut CBFilterAfterCanFileBeDeletedEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_can_file_be_deleted(&self) -> &'a dyn CBFilterAfterCanFileBeDeletedEvent;
  pub fn set_on_after_can_file_be_deleted(&mut self, value : &'a dyn CBFilterAfterCanFileBeDeletedEvent);
  ...
}

Remarks

This event fires after 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.

If the file or directory is marked for deletion, they will not be removed immediately but will actually be removed when the last handle is closed. Moreover, it is possible that a future call to a system function will remove the mark, so this event is not a final indicator that the file or directory will be deleted.

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_after_create_file or on_after_open_file event.

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

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

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

The CanDelete parameter reflects whether the file or directory will 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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_cleanup_file Event (CBFilter Struct)

This event fires after a file or directory handle is closed.

Syntax

// CBFilterAfterCleanupFileEventArgs carries the CBFilter AfterCleanupFile event's parameters.
pub struct CBFilterAfterCleanupFileEventArgs {
  fn file_name(&self) -> &String
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterCleanupFileEvent defines the signature of the CBFilter AfterCleanupFile event's handler function.
pub trait CBFilterAfterCleanupFileEvent {
  fn on_after_cleanup_file(&self, sender : CBFilter, e : &mut CBFilterAfterCleanupFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_cleanup_file(&self) -> &'a dyn CBFilterAfterCleanupFileEvent;
  pub fn set_on_after_cleanup_file(&mut self, value : &'a dyn CBFilterAfterCleanupFileEvent);
  ...
}

Remarks

This event fires after a handle to the file or directory specified by FileName is 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_after_close_file in that on_after_cleanup_file fires immediately after an open handle to the specified file or directory is closed by a process, whereas on_after_close_file may be fired much later when the OS 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_after_close_file event fires. For example, system components, such as the memory manager or cache manager, may cause the on_after_read_file and on_after_write_file events to fire.

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_close_enumeration Event (CBFilter Struct)

This event fires after a directory enumeration operation finishes.

Syntax

// CBFilterAfterCloseEnumerationEventArgs carries the CBFilter AfterCloseEnumeration event's parameters.
pub struct CBFilterAfterCloseEnumerationEventArgs {
  fn directory_name(&self) -> &String
  fn directory_context(&self) -> usize
  fn handle_context(&self) -> usize
  fn enumeration_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterCloseEnumerationEvent defines the signature of the CBFilter AfterCloseEnumeration event's handler function.
pub trait CBFilterAfterCloseEnumerationEvent {
  fn on_after_close_enumeration(&self, sender : CBFilter, e : &mut CBFilterAfterCloseEnumerationEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_close_enumeration(&self) -> &'a dyn CBFilterAfterCloseEnumerationEvent;
  pub fn set_on_after_close_enumeration(&mut self, value : &'a dyn CBFilterAfterCloseEnumerationEvent);
  ...
}

Remarks

This event fires after enumeration of the directory specified by DirectoryName finishes. 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_CE_BEFORE_CLOSE flag (directory enumerations are typically closed immediately before a directory is closed).

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

The EnumerationContext parameter is a placeholder for application-defined data associated with the enumeration. Please refer to the Contexts 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_after_close_file Event (CBFilter Struct)

This event fires after a file or directory is closed.

Syntax

// CBFilterAfterCloseFileEventArgs carries the CBFilter AfterCloseFile event's parameters.
pub struct CBFilterAfterCloseFileEventArgs {
  fn file_name(&self) -> &String
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterCloseFileEvent defines the signature of the CBFilter AfterCloseFile event's handler function.
pub trait CBFilterAfterCloseFileEvent {
  fn on_after_close_file(&self, sender : CBFilter, e : &mut CBFilterAfterCloseFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_close_file(&self) -> &'a dyn CBFilterAfterCloseFileEvent;
  pub fn set_on_after_close_file(&mut self, value : &'a dyn CBFilterAfterCloseFileEvent);
  ...
}

Remarks

This event fires after the file or directory specified by FileName is 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_CE_AFTER_CLOSE flag.

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

If the file or directory was marked for deletion earlier, the on_after_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 (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_create_file Event (CBFilter Struct)

This event fires after a file or directory is created.

Syntax

// CBFilterAfterCreateFileEventArgs carries the CBFilter AfterCreateFile event's parameters.
pub struct CBFilterAfterCreateFileEventArgs {
  fn file_name(&self) -> &String
  fn existing_attributes(&self) -> i32
  fn isolate(&self) -> bool
  fn backend_file_name(&self) -> &String
  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 set_status(&self, value : i32)
  fn creation_status(&self) -> i32
  fn set_creation_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterCreateFileEvent defines the signature of the CBFilter AfterCreateFile event's handler function.
pub trait CBFilterAfterCreateFileEvent {
  fn on_after_create_file(&self, sender : CBFilter, e : &mut CBFilterAfterCreateFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_create_file(&self) -> &'a dyn CBFilterAfterCreateFileEvent;
  pub fn set_on_after_create_file(&mut self, value : &'a dyn CBFilterAfterCreateFileEvent);
  ...
}

Remarks

This event fires after the file or directory specified by FileName is 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_after_open_file.

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

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

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

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.

If Isolate was set to true in the on_before_create_file or on_before_open_file events, the value of the Isolate and BackendFileName parameters in this event will contain the values initially set in those events. Additionally, if a file was added using the add_virtual_file method Isolate will be true.

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_after_can_file_be_deleted event will fire after this event.

If the file is created with Extended Attributes passed in the request, the on_after_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. Applications may change this parameter's value if they want a different NT status code to be returned.

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

Applications may change this parameter's value if they want a different creation status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

When the process_failed_requests property is enabled, this event may fire even if the specified file or directory has not been created or opened, in which case the Status parameter will be non-zero. When this occurs, applications must not alter the FileContext and HandleContext parameters.

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_create_hard_link Event (CBFilter Struct)

This event fires after a hard link is created.

Syntax

// CBFilterAfterCreateHardLinkEventArgs carries the CBFilter AfterCreateHardLink event's parameters.
pub struct CBFilterAfterCreateHardLinkEventArgs {
  fn file_name(&self) -> &String
  fn link_name(&self) -> &String
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterCreateHardLinkEvent defines the signature of the CBFilter AfterCreateHardLink event's handler function.
pub trait CBFilterAfterCreateHardLinkEvent {
  fn on_after_create_hard_link(&self, sender : CBFilter, e : &mut CBFilterAfterCreateHardLinkEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_create_hard_link(&self) -> &'a dyn CBFilterAfterCreateHardLinkEvent;
  pub fn set_on_after_create_hard_link(&mut self, value : &'a dyn CBFilterAfterCreateHardLinkEvent);
  ...
}

Remarks

This event fires after a hard link to the file specified by FileName is 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_CE_AFTER_CREATE_HARD_LINK flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_delete_file Event (CBFilter Struct)

This event fires after a file or directory is deleted.

Syntax

// CBFilterAfterDeleteFileEventArgs carries the CBFilter AfterDeleteFile event's parameters.
pub struct CBFilterAfterDeleteFileEventArgs {
  fn file_name(&self) -> &String
  fn request_type(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterDeleteFileEvent defines the signature of the CBFilter AfterDeleteFile event's handler function.
pub trait CBFilterAfterDeleteFileEvent {
  fn on_after_delete_file(&self, sender : CBFilter, e : &mut CBFilterAfterDeleteFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_delete_file(&self) -> &'a dyn CBFilterAfterDeleteFileEvent;
  pub fn set_on_after_delete_file(&mut self, value : &'a dyn CBFilterAfterDeleteFileEvent);
  ...
}

Remarks

This event fires after the file or directory specified by FileName is 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 fired after the final IRP_MJ_CLOSE IRP is 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_after_close_file fires.

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

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_delete_reparse_point Event (CBFilter Struct)

This event fires after the OS deletes a reparse point from a file or directory.

Syntax

// CBFilterAfterDeleteReparsePointEventArgs carries the CBFilter AfterDeleteReparsePoint event's parameters.
pub struct CBFilterAfterDeleteReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterDeleteReparsePointEvent defines the signature of the CBFilter AfterDeleteReparsePoint event's handler function.
pub trait CBFilterAfterDeleteReparsePointEvent {
  fn on_after_delete_reparse_point(&self, sender : CBFilter, e : &mut CBFilterAfterDeleteReparsePointEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_delete_reparse_point(&self) -> &'a dyn CBFilterAfterDeleteReparsePointEvent;
  pub fn set_on_after_delete_reparse_point(&mut self, value : &'a dyn CBFilterAfterDeleteReparsePointEvent);
  ...
}

Remarks

This event fires after the OS deletes a reparse point from 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.

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

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

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

The ReparseBuffer parameter points to a memory buffer that specifies the known reparse point information. This information is provided for convenience. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic 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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_enumerate_directory Event (CBFilter Struct)

This event fires after a directory entry is returned during directory enumeration.

Syntax

// CBFilterAfterEnumerateDirectoryEventArgs carries the CBFilter AfterEnumerateDirectory event's parameters.
pub struct CBFilterAfterEnumerateDirectoryEventArgs {
  fn directory_name(&self) -> &String
  fn flags(&self) -> i32
  fn index(&self) -> i32
  fn file_name(&self) -> &String
  fn set_file_name(&self, value : String)
  fn set_file_name_ref(&self, value : &String)
  fn creation_time(&self) -> &chrono::DateTime<Utc>
  fn set_creation_time(&self, value : chrono::DateTime<Utc>)
  fn set_creation_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_access_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_access_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_access_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_write_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_write_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn change_time(&self) -> &chrono::DateTime<Utc>
  fn set_change_time(&self, value : chrono::DateTime<Utc>)
  fn set_change_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn size(&self) -> i64
  fn set_size(&self, value : i64)
  fn allocation_size(&self) -> i64
  fn set_allocation_size(&self, value : i64)
  fn file_id(&self) -> i64
  fn set_file_id(&self, value : i64)
  fn attributes(&self) -> i32
  fn set_attributes(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn directory_context(&self) -> usize
  fn set_directory_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn enumeration_context(&self) -> usize
  fn set_enumeration_context(&self, value : usize)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterEnumerateDirectoryEvent defines the signature of the CBFilter AfterEnumerateDirectory event's handler function.
pub trait CBFilterAfterEnumerateDirectoryEvent {
  fn on_after_enumerate_directory(&self, sender : CBFilter, e : &mut CBFilterAfterEnumerateDirectoryEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_enumerate_directory(&self) -> &'a dyn CBFilterAfterEnumerateDirectoryEvent;
  pub fn set_on_after_enumerate_directory(&mut self, value : &'a dyn CBFilterAfterEnumerateDirectoryEvent);
  ...
}

Remarks

This event fires after a directory entry (i.e., a file or subdirectory) is 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 may use this event to modify the entry's metadata before it gets reported to the requestor or even to prevent the entry from being reported in the first place.

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

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

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 specify the entry's time values, specified .

The Size parameter specifies the size of the file, in bytes; it must always be 0 for subdirectories.

The AllocationSize parameter specifies the amount of space allocated for the file, in bytes; it must always be 0 for subdirectories.

The FileId parameter specifies the unique Id of the entry, as reported by the filesystem (or, for virtual files, by the application itself). 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 specifies 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. Applications may change this parameter's value if they want a different NT status code to be returned.

The DirectoryContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the directory, specific handle, and enumeration, respectively. (For general-purpose events, the DirectoryContext is called FileContext instead.) DirectoryContext corresponds to the FileContext in the file/directory creation, opening, and closing events. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the directory entry should actually be reported to the requestor; it is true by default. Setting this parameter to false will "hide" the directory entry (i.e., prevent it from being reported).

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_attach_to_volume Event (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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_after_fsctl Event (CBFilter Struct)

This event fires after an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.

Syntax

// CBFilterAfterFsctlEventArgs carries the CBFilter AfterFsctl event's parameters.
pub struct CBFilterAfterFsctlEventArgs {
  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 set_out_buffer_valid_bytes(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterFsctlEvent defines the signature of the CBFilter AfterFsctl event's handler function.
pub trait CBFilterAfterFsctlEvent {
  fn on_after_fsctl(&self, sender : CBFilter, e : &mut CBFilterAfterFsctlEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_fsctl(&self) -> &'a dyn CBFilterAfterFsctlEvent;
  pub fn set_on_after_fsctl(&mut self, value : &'a dyn CBFilterAfterFsctlEvent);
  ...
}

Remarks

This event fires after an IRP_MJ_FILE_SYSTEM_CONTROL (FSCTL) request is processed. 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 may use this event to modify the output data (if there are any) before the response is returned to the requestor. Applications that choose to do this must:

1. copy no more than OutBufferLength bytes into OutBuffer; and
2. update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.

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

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_get_file_security Event (CBFilter Struct)

This event fires after a file or directory's security attributes are retrieved.

Syntax

// CBFilterAfterGetFileSecurityEventArgs carries the CBFilter AfterGetFileSecurity event's parameters.
pub struct CBFilterAfterGetFileSecurityEventArgs {
  fn file_name(&self) -> &String
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn length_needed(&self) -> i32
  fn set_length_needed(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterGetFileSecurityEvent defines the signature of the CBFilter AfterGetFileSecurity event's handler function.
pub trait CBFilterAfterGetFileSecurityEvent {
  fn on_after_get_file_security(&self, sender : CBFilter, e : &mut CBFilterAfterGetFileSecurityEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_get_file_security(&self) -> &'a dyn CBFilterAfterGetFileSecurityEvent;
  pub fn set_on_after_get_file_security(&mut self, value : &'a dyn CBFilterAfterGetFileSecurityEvent);
  ...
}

Remarks

This event fires after security attributes are 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_CE_AFTER_GET_SECURITY flag.

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

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.

Applications that wish to modify the security information may do so by replacing the data in the SecurityDescriptor buffer. If the current Length is too small to accommodate the new security information, set LengthNeeded to the number of bytes necessary to hold the data and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_get_file_sizes Event (CBFilter Struct)

This event fires after a file's size information is retrieved.

Syntax

// CBFilterAfterGetFileSizesEventArgs carries the CBFilter AfterGetFileSizes event's parameters.
pub struct CBFilterAfterGetFileSizesEventArgs {
  fn file_name(&self) -> &String
  fn size(&self) -> i64
  fn set_size(&self, value : i64)
  fn allocation_size(&self) -> i64
  fn set_allocation_size(&self, value : i64)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterGetFileSizesEvent defines the signature of the CBFilter AfterGetFileSizes event's handler function.
pub trait CBFilterAfterGetFileSizesEvent {
  fn on_after_get_file_sizes(&self, sender : CBFilter, e : &mut CBFilterAfterGetFileSizesEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_get_file_sizes(&self) -> &'a dyn CBFilterAfterGetFileSizesEvent;
  pub fn set_on_after_get_file_sizes(&mut self, value : &'a dyn CBFilterAfterGetFileSizesEvent);
  ...
}

Remarks

This event fires after size information is 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 that intend to modify a file's contents should use this event to modify the file's actual size or allocation size as necessary. Applications that make use of virtual files should use this event to report the size of the virtual files.

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

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

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

The AllocationSize parameter specifies 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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_get_reparse_point Event (CBFilter Struct)

This event fires after a file or directory's reparse point information is retrieved.

Syntax

// CBFilterAfterGetReparsePointEventArgs carries the CBFilter AfterGetReparsePoint event's parameters.
pub struct CBFilterAfterGetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn data_length(&self) -> i32
  fn set_data_length(&self, value : i32)
  fn length_needed(&self) -> i32
  fn set_length_needed(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterGetReparsePointEvent defines the signature of the CBFilter AfterGetReparsePoint event's handler function.
pub trait CBFilterAfterGetReparsePointEvent {
  fn on_after_get_reparse_point(&self, sender : CBFilter, e : &mut CBFilterAfterGetReparsePointEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_get_reparse_point(&self) -> &'a dyn CBFilterAfterGetReparsePointEvent;
  pub fn set_on_after_get_reparse_point(&mut self, value : &'a dyn CBFilterAfterGetReparsePointEvent);
  ...
}

Remarks

This event fires after reparse point information is 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_CE_AFTER_GET_REPARSE_POINT flag.

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

The ReparseBuffer parameter points to a memory buffer that, if the request was successful, contains the requested reparse point information. The DataLength 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.

Please refer to the Reparse Points topic for more information.

Applications that wish to modify the reparse point information may do so by replacing the data in the ReparseBuffer buffer. If the current BufferLength is too small to accommodate the new information, the application should write as much data as possible, set LengthNeeded appropriately, and return the STATUS_BUFFER_OVERFLOW status code via Status.

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Depending on how the request originator accessed the specified file or directory, it may or may not currently be open. The FileContext and HandleContext parameters will be absent if it is not open, in which case they will be .

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_ioctl Event (CBFilter Struct)

This event fires after an IRP_MJ_DEVICE_CONTROL request is processed.

Syntax

// CBFilterAfterIoctlEventArgs carries the CBFilter AfterIoctl event's parameters.
pub struct CBFilterAfterIoctlEventArgs {
  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 set_out_buffer_valid_bytes(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterIoctlEvent defines the signature of the CBFilter AfterIoctl event's handler function.
pub trait CBFilterAfterIoctlEvent {
  fn on_after_ioctl(&self, sender : CBFilter, e : &mut CBFilterAfterIoctlEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_ioctl(&self) -> &'a dyn CBFilterAfterIoctlEvent;
  pub fn set_on_after_ioctl(&mut self, value : &'a dyn CBFilterAfterIoctlEvent);
  ...
}

Remarks

This event fires after an IRP_MJ_DEVICE_CONTROL (IOCTL) request is processed. 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 may use this event to modify the output data (if there are any) before the response is returned to the requestor. Applications that choose to do this must:

1. copy no more than OutBufferLength bytes into OutBuffer; and
2. update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.

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

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_lock Event (CBFilter Struct)

This event fires after a range of bytes in a file is locked.

Syntax

// CBFilterAfterLockEventArgs carries the CBFilter AfterLock event's parameters.
pub struct CBFilterAfterLockEventArgs {
  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 set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterLockEvent defines the signature of the CBFilter AfterLock event's handler function.
pub trait CBFilterAfterLockEvent {
  fn on_after_lock(&self, sender : CBFilter, e : &mut CBFilterAfterLockEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_lock(&self) -> &'a dyn CBFilterAfterLockEvent;
  pub fn set_on_after_lock(&mut self, value : &'a dyn CBFilterAfterLockEvent);
  ...
}

Remarks

This event fires after a range of bytes in the file specified by FileName is 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_CE_AFTER_LOCK_CONTROL flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_open_file Event (CBFilter Struct)

This event fires after a file or directory is opened.

Syntax

// CBFilterAfterOpenFileEventArgs carries the CBFilter AfterOpenFile event's parameters.
pub struct CBFilterAfterOpenFileEventArgs {
  fn file_name(&self) -> &String
  fn existing_attributes(&self) -> i32
  fn isolate(&self) -> bool
  fn backend_file_name(&self) -> &String
  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 set_status(&self, value : i32)
  fn creation_status(&self) -> i32
  fn set_creation_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterOpenFileEvent defines the signature of the CBFilter AfterOpenFile event's handler function.
pub trait CBFilterAfterOpenFileEvent {
  fn on_after_open_file(&self, sender : CBFilter, e : &mut CBFilterAfterOpenFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_open_file(&self) -> &'a dyn CBFilterAfterOpenFileEvent;
  pub fn set_on_after_open_file(&mut self, value : &'a dyn CBFilterAfterOpenFileEvent);
  ...
}

Remarks

This event fires after the file or directory specified by FileName is 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_after_create_file.

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

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

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

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.

If Isolate was set to true in the on_before_create_file or on_before_open_file events, the value of the Isolate and BackendFileName parameters in this event will contain the values initially set in those events. Additionally, if a file was added using the add_virtual_file method Isolate will be true.

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_after_can_file_be_deleted event will fire after this event.

If the file is opened with extended attributes passed in the request, the on_after_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. Applications may change this parameter's value if they want a different NT status code to be returned.

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

Applications may change this parameter's value if they want a different creation status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

When the process_failed_requests property is enabled, this event may fire even if the specified file or directory has not been created or opened, in which case the Status parameter will be non-zero. When this occurs, applications must not alter the FileContext and HandleContext parameters.

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_query_ea Event (CBFilter Struct)

This event fires after information about extended attributes of a file is retrieved.

Syntax

// CBFilterAfterQueryEaEventArgs carries the CBFilter AfterQueryEa event's parameters.
pub struct CBFilterAfterQueryEaEventArgs {
  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 set_length_returned(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterQueryEaEvent defines the signature of the CBFilter AfterQueryEa event's handler function.
pub trait CBFilterAfterQueryEaEvent {
  fn on_after_query_ea(&self, sender : CBFilter, e : &mut CBFilterAfterQueryEaEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_query_ea(&self) -> &'a dyn CBFilterAfterQueryEaEvent;
  pub fn set_on_after_query_ea(&mut self, value : &'a dyn CBFilterAfterQueryEaEvent);
  ...
}

Remarks

This event fires after information about extended attributes of the file specified by FileName is retrieved using the ZwQueryEaFile or FltQueryEaFile function of the system API. 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_CE_AFTER_QUERY_EA flag.

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

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.

A handler may modify the contents of the Buffer given that the size of the modified data does not exceed the length of the buffer. When modifying the data, a handler should update LengthReturned accordingly.

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_query_file_info Event (CBFilter Struct)

This event fires after information about a file or directory is retrieved.

Syntax

// CBFilterAfterQueryFileInfoEventArgs carries the CBFilter AfterQueryFileInfo event's parameters.
pub struct CBFilterAfterQueryFileInfoEventArgs {
  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 set_valid_bytes(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterQueryFileInfoEvent defines the signature of the CBFilter AfterQueryFileInfo event's handler function.
pub trait CBFilterAfterQueryFileInfoEvent {
  fn on_after_query_file_info(&self, sender : CBFilter, e : &mut CBFilterAfterQueryFileInfoEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_query_file_info(&self) -> &'a dyn CBFilterAfterQueryFileInfoEvent;
  pub fn set_on_after_query_file_info(&mut self, value : &'a dyn CBFilterAfterQueryFileInfoEvent);
  ...
}

Remarks

This event fires after information about the file or directory specified by FileName is 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 may use this event to modify the output data before the response is returned to the requestor. Applications that choose to do this must:

1. copy no more than BufferLength bytes into Buffer; and
2. update the ValidBytes parameter's value afterward so that it correctly reflects the amount of data in Buffer.

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

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_read_file Event (CBFilter Struct)

This event fires after data are read from a file.

Syntax

// CBFilterAfterReadFileEventArgs carries the CBFilter AfterReadFile event's parameters.
pub struct CBFilterAfterReadFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn bytes_to_read(&self) -> i32
  fn reserved(&self) -> i32
  fn direction(&self) -> i32
  fn bytes_read(&self) -> i32
  fn set_bytes_read(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterReadFileEvent defines the signature of the CBFilter AfterReadFile event's handler function.
pub trait CBFilterAfterReadFileEvent {
  fn on_after_read_file(&self, sender : CBFilter, e : &mut CBFilterAfterReadFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_read_file(&self) -> &'a dyn CBFilterAfterReadFileEvent;
  pub fn set_on_after_read_file(&mut self, value : &'a dyn CBFilterAfterReadFileEvent);
  ...
}

Remarks

This event fires after data are read from 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 may use this event to modify the data that were read from the file before it is returned to the requestor. Applications that choose to do this must:

1. enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires);
2. copy no more than BytesToRead bytes into Buffer; and
3. update the BytesRead parameter's value afterward so that it correctly reflects the amount of data in Buffer.

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

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

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

The Buffer parameter points to a memory buffer that, if the request was successful, contains the data that were read from the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToRead parameter reflects how many bytes were to be read from the file (i.e., how many bytes the requestor expects will be read).

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 specifies how many bytes were actually read from the file, and thus the length of the data in Buffer. This parameter's value must not exceed BufferLength (and should not exceed BytesToRead; please refer to on_before_read_file 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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

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_rename_or_move_file Event (CBFilter Struct)

This event fires after a file or directory is renamed or moved.

Syntax

// CBFilterAfterRenameOrMoveFileEventArgs carries the CBFilter AfterRenameOrMoveFile event's parameters.
pub struct CBFilterAfterRenameOrMoveFileEventArgs {
  fn file_name(&self) -> &String
  fn new_file_name(&self) -> &String
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterRenameOrMoveFileEvent defines the signature of the CBFilter AfterRenameOrMoveFile event's handler function.
pub trait CBFilterAfterRenameOrMoveFileEvent {
  fn on_after_rename_or_move_file(&self, sender : CBFilter, e : &mut CBFilterAfterRenameOrMoveFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_rename_or_move_file(&self) -> &'a dyn CBFilterAfterRenameOrMoveFileEvent;
  pub fn set_on_after_rename_or_move_file(&mut self, value : &'a dyn CBFilterAfterRenameOrMoveFileEvent);
  ...
}

Remarks

This event fires after the file or directory specified by FileName is 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_CE_AFTER_RENAME flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_set_allocation_size Event (CBFilter Struct)

This event fires after a file's allocation size is changed.

Syntax

// CBFilterAfterSetAllocationSizeEventArgs carries the CBFilter AfterSetAllocationSize event's parameters.
pub struct CBFilterAfterSetAllocationSizeEventArgs {
  fn file_name(&self) -> &String
  fn allocation_size(&self) -> i64
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterSetAllocationSizeEvent defines the signature of the CBFilter AfterSetAllocationSize event's handler function.
pub trait CBFilterAfterSetAllocationSizeEvent {
  fn on_after_set_allocation_size(&self, sender : CBFilter, e : &mut CBFilterAfterSetAllocationSizeEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_set_allocation_size(&self) -> &'a dyn CBFilterAfterSetAllocationSizeEvent;
  pub fn set_on_after_set_allocation_size(&mut self, value : &'a dyn CBFilterAfterSetAllocationSizeEvent);
  ...
}

Remarks

This event fires after the allocation size of the file specified by FileName is 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_CE_AFTER_SET_SIZES flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

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_set_ea Event (CBFilter Struct)

This event fires after extended attributes of a file are changed.

Syntax

// CBFilterAfterSetEaEventArgs carries the CBFilter AfterSetEa event's parameters.
pub struct CBFilterAfterSetEaEventArgs {
  fn file_name(&self) -> &String
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterSetEaEvent defines the signature of the CBFilter AfterSetEa event's handler function.
pub trait CBFilterAfterSetEaEvent {
  fn on_after_set_ea(&self, sender : CBFilter, e : &mut CBFilterAfterSetEaEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_set_ea(&self) -> &'a dyn CBFilterAfterSetEaEvent;
  pub fn set_on_after_set_ea(&mut self, value : &'a dyn CBFilterAfterSetEaEvent);
  ...
}

Remarks

This event fires after extended attributes are changed 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.

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

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

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_set_file_attributes Event (CBFilter Struct)

This event fires after a file or directory's attributes or times are changed.

Syntax

// CBFilterAfterSetFileAttributesEventArgs carries the CBFilter AfterSetFileAttributes event's parameters.
pub struct CBFilterAfterSetFileAttributesEventArgs {
  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 set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterSetFileAttributesEvent defines the signature of the CBFilter AfterSetFileAttributes event's handler function.
pub trait CBFilterAfterSetFileAttributesEvent {
  fn on_after_set_file_attributes(&self, sender : CBFilter, e : &mut CBFilterAfterSetFileAttributesEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_set_file_attributes(&self) -> &'a dyn CBFilterAfterSetFileAttributesEvent;
  pub fn set_on_after_set_file_attributes(&mut self, value : &'a dyn CBFilterAfterSetFileAttributesEvent);
  ...
}

Remarks

This event fires after the attributes or times of the file or directory specified by FileName are 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_CE_AFTER_SET_ATTRIBUTES flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_set_file_info Event (CBFilter Struct)

This event fires after information about a file or directory is changed.

Syntax

// CBFilterAfterSetFileInfoEventArgs carries the CBFilter AfterSetFileInfo event's parameters.
pub struct CBFilterAfterSetFileInfoEventArgs {
  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 set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterSetFileInfoEvent defines the signature of the CBFilter AfterSetFileInfo event's handler function.
pub trait CBFilterAfterSetFileInfoEvent {
  fn on_after_set_file_info(&self, sender : CBFilter, e : &mut CBFilterAfterSetFileInfoEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_set_file_info(&self) -> &'a dyn CBFilterAfterSetFileInfoEvent;
  pub fn set_on_after_set_file_info(&mut self, value : &'a dyn CBFilterAfterSetFileInfoEvent);
  ...
}

Remarks

This event fires after information about the file or directory specified by FileName is 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_CE_AFTER_SET_FILE_INFO flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_set_file_security Event (CBFilter Struct)

This event fires after a file or directory's security attributes are changed.

Syntax

// CBFilterAfterSetFileSecurityEventArgs carries the CBFilter AfterSetFileSecurity event's parameters.
pub struct CBFilterAfterSetFileSecurityEventArgs {
  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 set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterSetFileSecurityEvent defines the signature of the CBFilter AfterSetFileSecurity event's handler function.
pub trait CBFilterAfterSetFileSecurityEvent {
  fn on_after_set_file_security(&self, sender : CBFilter, e : &mut CBFilterAfterSetFileSecurityEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_set_file_security(&self) -> &'a dyn CBFilterAfterSetFileSecurityEvent;
  pub fn set_on_after_set_file_security(&mut self, value : &'a dyn CBFilterAfterSetFileSecurityEvent);
  ...
}

Remarks

This event fires after security attributes are changed 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_CE_AFTER_SET_SECURITY flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_set_file_size Event (CBFilter Struct)

This event fires after a file is resized.

Syntax

// CBFilterAfterSetFileSizeEventArgs carries the CBFilter AfterSetFileSize event's parameters.
pub struct CBFilterAfterSetFileSizeEventArgs {
  fn file_name(&self) -> &String
  fn size(&self) -> i64
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterSetFileSizeEvent defines the signature of the CBFilter AfterSetFileSize event's handler function.
pub trait CBFilterAfterSetFileSizeEvent {
  fn on_after_set_file_size(&self, sender : CBFilter, e : &mut CBFilterAfterSetFileSizeEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_set_file_size(&self) -> &'a dyn CBFilterAfterSetFileSizeEvent;
  pub fn set_on_after_set_file_size(&mut self, value : &'a dyn CBFilterAfterSetFileSizeEvent);
  ...
}

Remarks

This event fires after the file specified by FileName is 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_CE_AFTER_SET_SIZES flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

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_set_reparse_point Event (CBFilter Struct)

This event fires after the OS creates or updates a reparse point on a file or directory.

Syntax

// CBFilterAfterSetReparsePointEventArgs carries the CBFilter AfterSetReparsePoint event's parameters.
pub struct CBFilterAfterSetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_tag(&self) -> i64
  fn reparse_buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn data_length(&self) -> i32
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterSetReparsePointEvent defines the signature of the CBFilter AfterSetReparsePoint event's handler function.
pub trait CBFilterAfterSetReparsePointEvent {
  fn on_after_set_reparse_point(&self, sender : CBFilter, e : &mut CBFilterAfterSetReparsePointEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_set_reparse_point(&self) -> &'a dyn CBFilterAfterSetReparsePointEvent;
  pub fn set_on_after_set_reparse_point(&mut self, value : &'a dyn CBFilterAfterSetReparsePointEvent);
  ...
}

Remarks

This event fires after the OS creates or updates a reparse point on 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_CE_AFTER_SET_REPARSE_POINT flag.

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

The ReparseTag parameter contains the reparse tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; the struct extracts it and provides it separately for convenience.

The ReparseBuffer parameter points to a memory buffer that specifies the new reparse point information. The DataLength parameter reflects the length of the data contained in the buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic 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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_unlock_all Event (CBFilter Struct)

This event fires after all locked byte ranges in a file are unlocked.

Syntax

// CBFilterAfterUnlockAllEventArgs carries the CBFilter AfterUnlockAll event's parameters.
pub struct CBFilterAfterUnlockAllEventArgs {
  fn file_name(&self) -> &String
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterUnlockAllEvent defines the signature of the CBFilter AfterUnlockAll event's handler function.
pub trait CBFilterAfterUnlockAllEvent {
  fn on_after_unlock_all(&self, sender : CBFilter, e : &mut CBFilterAfterUnlockAllEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_unlock_all(&self) -> &'a dyn CBFilterAfterUnlockAllEvent;
  pub fn set_on_after_unlock_all(&mut self, value : &'a dyn CBFilterAfterUnlockAllEvent);
  ...
}

Remarks

This event fires after all locked byte ranges in the file specified by FileName are 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_CE_AFTER_LOCK_CONTROL flag.

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

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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_after_unlock_all_by_key Event (CBFilter Struct)

This event fires after all locked byte ranges in a file, associated with a particular key, are unlocked.

Syntax

// CBFilterAfterUnlockAllByKeyEventArgs carries the CBFilter AfterUnlockAllByKey event's parameters.
pub struct CBFilterAfterUnlockAllByKeyEventArgs {
  fn file_name(&self) -> &String
  fn key(&self) -> i64
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterUnlockAllByKeyEvent defines the signature of the CBFilter AfterUnlockAllByKey event's handler function.
pub trait CBFilterAfterUnlockAllByKeyEvent {
  fn on_after_unlock_all_by_key(&self, sender : CBFilter, e : &mut CBFilterAfterUnlockAllByKeyEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_unlock_all_by_key(&self) -> &'a dyn CBFilterAfterUnlockAllByKeyEvent;
  pub fn set_on_after_unlock_all_by_key(&mut self, value : &'a dyn CBFilterAfterUnlockAllByKeyEvent);
  ...
}

Remarks

This event fires after all locked byte ranges in the file specified by FileName, and associated with the specified Key, are 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_CE_AFTER_LOCK_CONTROL flag.

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

The Key parameter contains the key value specified when the byte ranges were locked. Please refer to the on_after_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. Applications may change this parameter's value if they want a different NT status code to be returned.

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_unlock_single Event (CBFilter Struct)

This event fires after a particular locked byte range in a file is unlocked.

Syntax

// CBFilterAfterUnlockSingleEventArgs carries the CBFilter AfterUnlockSingle event's parameters.
pub struct CBFilterAfterUnlockSingleEventArgs {
  fn file_name(&self) -> &String
  fn offset(&self) -> i64
  fn length(&self) -> i64
  fn key(&self) -> i64
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterUnlockSingleEvent defines the signature of the CBFilter AfterUnlockSingle event's handler function.
pub trait CBFilterAfterUnlockSingleEvent {
  fn on_after_unlock_single(&self, sender : CBFilter, e : &mut CBFilterAfterUnlockSingleEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_unlock_single(&self) -> &'a dyn CBFilterAfterUnlockSingleEvent;
  pub fn set_on_after_unlock_single(&mut self, value : &'a dyn CBFilterAfterUnlockSingleEvent);
  ...
}

Remarks

This event fires after a particular locked byte range in the file specified by FileName is 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_CE_AFTER_LOCK_CONTROL flag.

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

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_after_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. Applications may change this parameter's value if they want a different NT status code to be returned.

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_write_file Event (CBFilter Struct)

This event fires after data are written to a file.

Syntax

// CBFilterAfterWriteFileEventArgs carries the CBFilter AfterWriteFile event's parameters.
pub struct CBFilterAfterWriteFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn bytes_to_write(&self) -> i32
  fn direction(&self) -> i32
  fn bytes_written(&self) -> i32
  fn set_bytes_written(&self, value : i32)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterAfterWriteFileEvent defines the signature of the CBFilter AfterWriteFile event's handler function.
pub trait CBFilterAfterWriteFileEvent {
  fn on_after_write_file(&self, sender : CBFilter, e : &mut CBFilterAfterWriteFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_after_write_file(&self) -> &'a dyn CBFilterAfterWriteFileEvent;
  pub fn set_on_after_write_file(&mut self, value : &'a dyn CBFilterAfterWriteFileEvent);
  ...
}

Remarks

This event fires after data are 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 may use this event to inspect the data that were written to the file, but must not attempt to alter said data. If, during on_before_write_file, an application causes less data than requested to be written to the file, it should use this event to set BytesWritten back to the expected value (i.e., BytesToWrite) to prevent the requestor from behaving unexpectedly.

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

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

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 Buffer parameter points to a memory buffer that contains the data that, if the request was successful, were written to the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToWrite parameter reflects how many bytes were to be written to the file (i.e., how many bytes the requestor expects will be written).

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 specifies how many bytes were actually written to the file. This parameter's value must not exceed BufferLength (and should not exceed BytesToWrite; please refer to on_before_write_file 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. Applications may change this parameter's value if they want a different NT status code to be returned.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

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_can_file_be_deleted Event (CBFilter Struct)

This event fires before the OS attempts to mark a file or directory for deletion or remove such a mark.

Syntax

// CBFilterBeforeCanFileBeDeletedEventArgs carries the CBFilter BeforeCanFileBeDeleted event's parameters.
pub struct CBFilterBeforeCanFileBeDeletedEventArgs {
  fn file_name(&self) -> &String
  fn request_type(&self) -> i32
  fn can_delete(&self) -> bool
  fn set_can_delete(&self, value : bool)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeCanFileBeDeletedEvent defines the signature of the CBFilter BeforeCanFileBeDeleted event's handler function.
pub trait CBFilterBeforeCanFileBeDeletedEvent {
  fn on_before_can_file_be_deleted(&self, sender : CBFilter, e : &mut CBFilterBeforeCanFileBeDeletedEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_can_file_be_deleted(&self) -> &'a dyn CBFilterBeforeCanFileBeDeletedEvent;
  pub fn set_on_before_can_file_be_deleted(&mut self, value : &'a dyn CBFilterBeforeCanFileBeDeletedEvent);
  ...
}

Remarks

This event fires before 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 before the on_before_create_file or on_before_open_file event.

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

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

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

The CanDelete parameter specifies whether the file or directory will be deleted. This parameter can be true or false depending on which request the OS has sent. Applications may prevent deletion of the file or directory by setting CanDelete to false. Changing CanDelete from false to true may or may not have the effect on the file being deleted later, so such a change should be avoided.

Note: If the file is opened with FILE_FLAG_DELETE_ON_CLOSE flag set and the event handler permits file deletion, such flag cannot be removed later (even with the call to NtSetInformationFile() API function).

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

The effect of ProcessRequest depends on what operation caused the event to fire:

• If the event fires during the file open operation where the FILE_FLAG_DELETE_ON_CLOSE flag is set,
  • setting CanDelete to false and ProcessRequest to true causes the FILE_FLAG_DELETE_ON_CLOSE flag to be removed and the file open request to be passed further to the filesystem; and
  • setting CanDelete to false and ProcessRequest to false causes the file open request to fail with ACCESS_DENIED error.
• If the event fires in the context of the call to NtSetInformationFile Windows API function, setting CanDelete to false causes the DeleteFlag parameter to be set to false and the request to be passed further to the filesystem. This combination effectively resets the file deletion state, known to the filesystem, to the false ("do not delete") value. The value of ProcessRequest in this case does not matter as the new value must reach the filesystem.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the specified file or directory was not opened before the request, both contexts will be absent, in which case these parameters will be .)

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_cleanup_file Event (CBFilter Struct)

This event fires before a file or directory handle is closed.

Syntax

// CBFilterBeforeCleanupFileEventArgs carries the CBFilter BeforeCleanupFile event's parameters.
pub struct CBFilterBeforeCleanupFileEventArgs {
  fn file_name(&self) -> &String
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeCleanupFileEvent defines the signature of the CBFilter BeforeCleanupFile event's handler function.
pub trait CBFilterBeforeCleanupFileEvent {
  fn on_before_cleanup_file(&self, sender : CBFilter, e : &mut CBFilterBeforeCleanupFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_cleanup_file(&self) -> &'a dyn CBFilterBeforeCleanupFileEvent;
  pub fn set_on_before_cleanup_file(&mut self, value : &'a dyn CBFilterBeforeCleanupFileEvent);
  ...
}

Remarks

This event fires before a handle to the file or directory specified by FileName is 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_before_close_file in that on_before_cleanup_file fires immediately before an open handle to the specified file or directory is closed by a process, whereas on_before_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_before_close_file event fires. For example, system components such as the memory manager or cache manager may cause the on_before_read_file and on_before_write_file events to fire.

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_before_close_file Event (CBFilter Struct)

This event fires before a file or directory is closed.

Syntax

// CBFilterBeforeCloseFileEventArgs carries the CBFilter BeforeCloseFile event's parameters.
pub struct CBFilterBeforeCloseFileEventArgs {
  fn file_name(&self) -> &String
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeCloseFileEvent defines the signature of the CBFilter BeforeCloseFile event's handler function.
pub trait CBFilterBeforeCloseFileEvent {
  fn on_before_close_file(&self, sender : CBFilter, e : &mut CBFilterBeforeCloseFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_close_file(&self) -> &'a dyn CBFilterBeforeCloseFileEvent;
  pub fn set_on_before_close_file(&mut self, value : &'a dyn CBFilterBeforeCloseFileEvent);
  ...
}

Remarks

This event fires before the file or directory specified by FileName is 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_CE_BEFORE_CLOSE flag.

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

If the file or directory was marked for deletion earlier, the on_before_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 (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_create_file Event (CBFilter Struct)

This event fires before a file or directory is created.

Syntax

// CBFilterBeforeCreateFileEventArgs carries the CBFilter BeforeCreateFile event's parameters.
pub struct CBFilterBeforeCreateFileEventArgs {
  fn file_name(&self) -> &String
  fn existing_attributes(&self) -> i32
  fn isolate(&self) -> bool
  fn set_isolate(&self, value : bool)
  fn backend_file_name(&self) -> &String
  fn set_backend_file_name(&self, value : String)
  fn set_backend_file_name_ref(&self, value : &String)
  fn desired_access(&self) -> i32
  fn set_desired_access(&self, value : i32)
  fn attributes(&self) -> i32
  fn set_attributes(&self, value : i32)
  fn share_mode(&self) -> i32
  fn set_share_mode(&self, value : i32)
  fn options(&self) -> i32
  fn set_options(&self, value : i32)
  fn create_disposition(&self) -> i32
  fn set_create_disposition(&self, value : i32)
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeCreateFileEvent defines the signature of the CBFilter BeforeCreateFile event's handler function.
pub trait CBFilterBeforeCreateFileEvent {
  fn on_before_create_file(&self, sender : CBFilter, e : &mut CBFilterBeforeCreateFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_create_file(&self) -> &'a dyn CBFilterBeforeCreateFileEvent;
  pub fn set_on_before_create_file(&mut self, value : &'a dyn CBFilterBeforeCreateFileEvent);
  ...
}

Remarks

This event fires before the file or directory specified by FileName is 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_before_open_file.

Applications may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false; and set Status to the desired NT status (the parameter is set to STATUS_ACCESS_DENIED before the event is fired).

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

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

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

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.

To redirect file access to another location, or to provide custom file content, set Isolate to true. For instance if Process A and Process B both access a file, isolation allows returning different content to each process. When Isolate is set to true the BackendFileName parameter determines if the file is redirected, and to where.

When requests are redirected to an existing file on disk a dedicated cache is created for the isolated file by the CBFilter driver. This cache ensures that the data it holds do not interfere with the data read from or written to the file when it is opened without isolation. Please see the File Isolation topic for further details.

To ensure that isolation works properly, on Windows 11, the on_bypass_io_request event is fired when the OS makes a request to enable BypassIO on this file, giving a way for the application to forbid BypassIO with an application-specific error code and explanation.

Requests may also be redirected to another file or directory via the on_reparse_file_name event which is fired before this event. In order for the on_reparse_file_name event to fire, a standard filter rule must exist that includes the FS_CE_REPARSE_FILENAME flag. For more details, please see the on_reparse_file_name topic.

The initial values of 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 Internet Relay Programming).

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:

When the file being created or opened is virtual, the event handler must inspect and handle the value of the ShareMode parameter as a filesystem would normally do it.

CreateDisposition may contain one of the following values:

When the file being created or opened is virtual, the event handler must inspect and handle the value of the CreateDisposition parameter as a filesystem would normally do it. This includes adjusting the file size and updating the time attributes depending on the flag. For a virtual file, the driver returns the CreationStatus value that is derived from CreateDisposition as follows: If the event handler needs to change the returned CreationStatus, it should change the value of the CreateDisposition to the FILE_DISPOSITION_*** value that leads to the desired CreationStatus value (e.g. set the value to FILE_DISPOSITION_OPEN_EXISTING so that the driver returns CREATION_STATUS_OPENED).

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 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 is 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 only if it was specified by the calling process; its presence or absence does not indicate the real presence of the attribute on the file or directory on disk.

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: Files can be deleted in different ways, so do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

To prevent a file or directory from being opened, set the ResultCode parameter to a non-zero value (typically ERROR_ACCESS_DENIED (5)).

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 an application needs to alter the security information, it can do this by placing up to Length bytes of information into the SecurityDescriptor buffer.

Note: Changing the security data is possible only when the PassSecurityInFileOpenEvents configuration setting is enabled.

If the capacity reflected by the Length parameter is not enough to accommodate the security information, set LengthNeeded to the number of bytes necessary to hold the data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the on_before_can_file_be_deleted event will fire before this event.

If the file is opened with extended attributes passed in the request, the on_before_set_ea event will fire after 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 (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_create_hard_link Event (CBFilter Struct)

This event fires before a hard link is created.

Syntax

// CBFilterBeforeCreateHardLinkEventArgs carries the CBFilter BeforeCreateHardLink event's parameters.
pub struct CBFilterBeforeCreateHardLinkEventArgs {
  fn file_name(&self) -> &String
  fn link_name(&self) -> &String
  fn replace_if_exists(&self) -> bool
  fn set_replace_if_exists(&self, value : bool)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeCreateHardLinkEvent defines the signature of the CBFilter BeforeCreateHardLink event's handler function.
pub trait CBFilterBeforeCreateHardLinkEvent {
  fn on_before_create_hard_link(&self, sender : CBFilter, e : &mut CBFilterBeforeCreateHardLinkEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_create_hard_link(&self) -> &'a dyn CBFilterBeforeCreateHardLinkEvent;
  pub fn set_on_before_create_hard_link(&mut self, value : &'a dyn CBFilterBeforeCreateHardLinkEvent);
  ...
}

Remarks

This event fires before a hard link to the file specified by FileName is 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 may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false.

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

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

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

The ReplaceIfExists parameter specifies what to do if a hard link with the specified LinkName already exists. If this parameter is true, the new hard link will replace the existing hard link; if this parameter is false, the operation will fail.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_delete_file Event (CBFilter Struct)

This event fires before a file or directory is deleted.

Syntax

// CBFilterBeforeDeleteFileEventArgs carries the CBFilter BeforeDeleteFile event's parameters.
pub struct CBFilterBeforeDeleteFileEventArgs {
  fn file_name(&self) -> &String
  fn request_type(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeDeleteFileEvent defines the signature of the CBFilter BeforeDeleteFile event's handler function.
pub trait CBFilterBeforeDeleteFileEvent {
  fn on_before_delete_file(&self, sender : CBFilter, e : &mut CBFilterBeforeDeleteFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_delete_file(&self) -> &'a dyn CBFilterBeforeDeleteFileEvent;
  pub fn set_on_before_delete_file(&mut self, value : &'a dyn CBFilterBeforeDeleteFileEvent);
  ...
}

Remarks

This event fires before the file or directory specified by FileName is 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 fired before the final IRM_MJ_CLOSE Internet Relay Programming (IRP) is processed by the filesystem and before on_before_close_file fires.

Applications may use this event to obtain information about the specified file or directory, which still exists at the time this event fires. This event cannot be used to prevent a deletion; use the on_before_can_file_be_deleted event instead.

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

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_before_delete_reparse_point Event (CBFilter Struct)

This event fires when the OS wants to delete a reparse point from a file or directory.

Syntax

// CBFilterBeforeDeleteReparsePointEventArgs carries the CBFilter BeforeDeleteReparsePoint event's parameters.
pub struct CBFilterBeforeDeleteReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeDeleteReparsePointEvent defines the signature of the CBFilter BeforeDeleteReparsePoint event's handler function.
pub trait CBFilterBeforeDeleteReparsePointEvent {
  fn on_before_delete_reparse_point(&self, sender : CBFilter, e : &mut CBFilterBeforeDeleteReparsePointEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_delete_reparse_point(&self) -> &'a dyn CBFilterBeforeDeleteReparsePointEvent;
  pub fn set_on_before_delete_reparse_point(&mut self, value : &'a dyn CBFilterBeforeDeleteReparsePointEvent);
  ...
}

Remarks

This event fires before the OS deletes a reparse point from 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.

Note: The file or directory is not deleted, only the reparse point is.

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

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

The ReparseBuffer parameter points to a memory buffer that specifies the known reparse point information. This information is provided for convenience. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_enumerate_directory Event (CBFilter Struct)

This event fires when an enumeration request is sent by the OS.

Syntax

// CBFilterBeforeEnumerateDirectoryEventArgs carries the CBFilter BeforeEnumerateDirectory event's parameters.
pub struct CBFilterBeforeEnumerateDirectoryEventArgs {
  fn directory_name(&self) -> &String
  fn flags(&self) -> i32
  fn mask(&self) -> &String
  fn index(&self) -> i32
  fn directory_context(&self) -> usize
  fn set_directory_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn enumeration_context(&self) -> usize
  fn set_enumeration_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeEnumerateDirectoryEvent defines the signature of the CBFilter BeforeEnumerateDirectory event's handler function.
pub trait CBFilterBeforeEnumerateDirectoryEvent {
  fn on_before_enumerate_directory(&self, sender : CBFilter, e : &mut CBFilterBeforeEnumerateDirectoryEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_enumerate_directory(&self) -> &'a dyn CBFilterBeforeEnumerateDirectoryEvent;
  pub fn set_on_before_enumerate_directory(&mut self, value : &'a dyn CBFilterBeforeEnumerateDirectoryEvent);
  ...
}

Remarks

This event fires when the OS sends a request for reading one or more entries 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 may use this event to record the request and optionally block it.

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

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

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 Mask parameter contains the mask for the enumeration. This value may contain any combination of valid file name characters and wildcards (the * and ? characters). Alternatively, it may be an exact file name (i.e., a value without any wildcards), as some applications query file information by specifying an exact file name in an enumeration. When TranslateDOSCharsInEnumMasks is false, this parameter may contain a so-called DOS wildcard (please, refer to the description of this setting for more information). The mask can also be empty in rare cases: this happens when the OS request is a continuation of a previous enumeration with a valid non-zero Index.

The DirectoryContext, HandleContext, and EnumerationContext parameters are placeholders for application-defined data associated with the directory, specific handle, and enumeration, respectively. (For general-purpose events, the DirectoryContext is called FileContext instead.) DirectoryContext corresponds to the FileContext in the file/directory creation, opening, and closing events. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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 (CBFilter Struct)

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

Syntax

// CBFilterBeforeFilterAttachToVolumeEventArgs carries the CBFilter BeforeFilterAttachToVolume event's parameters.
pub struct CBFilterBeforeFilterAttachToVolumeEventArgs {
  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)
}

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

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

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_before_fsctl Event (CBFilter Struct)

This event fires before an IRP_MJ_FILE_SYSTEM_CONTROL request is processed.

Syntax

// CBFilterBeforeFsctlEventArgs carries the CBFilter BeforeFsctl event's parameters.
pub struct CBFilterBeforeFsctlEventArgs {
  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 set_in_buffer_valid_bytes(&self, value : i32)
  fn out_buffer(&self) -> *mut u8
  fn out_buffer_length(&self) -> i32
  fn out_buffer_valid_bytes(&self) -> i32
  fn set_out_buffer_valid_bytes(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeFsctlEvent defines the signature of the CBFilter BeforeFsctl event's handler function.
pub trait CBFilterBeforeFsctlEvent {
  fn on_before_fsctl(&self, sender : CBFilter, e : &mut CBFilterBeforeFsctlEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_fsctl(&self) -> &'a dyn CBFilterBeforeFsctlEvent;
  pub fn set_on_before_fsctl(&mut self, value : &'a dyn CBFilterBeforeFsctlEvent);
  ...
}

Remarks

This event fires before an IRP_MJ_FILE_SYSTEM_CONTROL (FSCTL) request is processed. 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 may use this event to modify the input data (if there are any) before the request continues onward. Applications that choose to do this must do the following:

1. Copy no more than InBufferLength bytes into InBuffer.
2. Update the InBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in InBuffer.

Alternatively, applications may use this event to handle the request (preventing it from continuing onward), in which case they must do the following:

1. Copy no more than OutBufferLength bytes into OutBuffer.
2. Update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.
3. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.

(The first two steps are not applicable if the requested operation is not expected to return data.)

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

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

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 receives 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 is not expected to 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 ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_before_get_file_security Event (CBFilter Struct)

This event fires before a file or directory's security attributes are retrieved.

Syntax

// CBFilterBeforeGetFileSecurityEventArgs carries the CBFilter BeforeGetFileSecurity event's parameters.
pub struct CBFilterBeforeGetFileSecurityEventArgs {
  fn file_name(&self) -> &String
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn length_needed(&self) -> i32
  fn set_length_needed(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeGetFileSecurityEvent defines the signature of the CBFilter BeforeGetFileSecurity event's handler function.
pub trait CBFilterBeforeGetFileSecurityEvent {
  fn on_before_get_file_security(&self, sender : CBFilter, e : &mut CBFilterBeforeGetFileSecurityEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_get_file_security(&self) -> &'a dyn CBFilterBeforeGetFileSecurityEvent;
  pub fn set_on_before_get_file_security(&mut self, value : &'a dyn CBFilterBeforeGetFileSecurityEvent);
  ...
}

Remarks

This event fires before security attributes are 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_CE_BEFORE_GET_SECURITY flag.

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

The SecurityInformation parameter indicates which pieces of security information are 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 receives the requested security information. The buffer referenced by the SecurityDescriptor parameter may be modified by the event handler if the operation is completed without passing it further to other filters and the filesystem driver. The Length parameter reflects the capacity of the SecurityDescriptor buffer, in bytes.

If the capacity reflected by the Length parameter is not sufficient to accommodate the security information, set LengthNeeded to the number of bytes necessary to hold the data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_get_reparse_point Event (CBFilter Struct)

This event fires when the OS wants to read a reparse point for a file or directory.

Syntax

// CBFilterBeforeGetReparsePointEventArgs carries the CBFilter BeforeGetReparsePoint event's parameters.
pub struct CBFilterBeforeGetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_buffer(&self) -> *mut u8
  fn reparse_buffer_length(&self) -> i32
  fn set_reparse_buffer_length(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeGetReparsePointEvent defines the signature of the CBFilter BeforeGetReparsePoint event's handler function.
pub trait CBFilterBeforeGetReparsePointEvent {
  fn on_before_get_reparse_point(&self, sender : CBFilter, e : &mut CBFilterBeforeGetReparsePointEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_get_reparse_point(&self) -> &'a dyn CBFilterBeforeGetReparsePointEvent;
  pub fn set_on_before_get_reparse_point(&mut self, value : &'a dyn CBFilterBeforeGetReparsePointEvent);
  ...
}

Remarks

This event fires when the OS wants to read a reparse point 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_CE_BEFORE_GET_REPARSE_POINT flag.

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

If an application desires to handle the event and does not pass the request further, it needs to fill ReparseBuffer with the reparse point data associated with the specified file or directory and set ReparseBufferLength to the number of bytes written. The ReparseBufferLength parameter's initial value reflects the capacity of the memory buffer pointed to by ReparseBuffer. If the buffer is too small to hold all of the reparse point data, then the application should write as much data to it as possible, set ReparseBufferLength appropriately, and return the ERROR_MORE_DATA error code via ResultCode.

Please refer to the Reparse Points topic for more information.

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

Depending on how the request originator accessed the specified file or directory, it may or may not currently be open. The FileContext and HandleContext parameters will be absent if it is not open, in which case they will be .

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_ioctl Event (CBFilter Struct)

This event fires before an IRP_MJ_DEVICE_CONTROL request is processed.

Syntax

// CBFilterBeforeIoctlEventArgs carries the CBFilter BeforeIoctl event's parameters.
pub struct CBFilterBeforeIoctlEventArgs {
  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 set_in_buffer_valid_bytes(&self, value : i32)
  fn out_buffer(&self) -> *mut u8
  fn out_buffer_length(&self) -> i32
  fn out_buffer_valid_bytes(&self) -> i32
  fn set_out_buffer_valid_bytes(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeIoctlEvent defines the signature of the CBFilter BeforeIoctl event's handler function.
pub trait CBFilterBeforeIoctlEvent {
  fn on_before_ioctl(&self, sender : CBFilter, e : &mut CBFilterBeforeIoctlEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_ioctl(&self) -> &'a dyn CBFilterBeforeIoctlEvent;
  pub fn set_on_before_ioctl(&mut self, value : &'a dyn CBFilterBeforeIoctlEvent);
  ...
}

Remarks

This event fires before an IRP_MJ_DEVICE_CONTROL (IOCTL) request is processed. 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 may use this event to modify the input data (if there are any) before the request continues onward. Applications that choose to do this must do the following:

1. Copy no more than InBufferLength bytes into InBuffer.
2. Update the InBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in InBuffer.

Alternatively, applications may use this event to handle the request (preventing it from continuing onward), in which case they must do the following:

1. Copy no more than OutBufferLength bytes into OutBuffer.
2. Update the OutBufferValidBytes parameter's value afterward so that it correctly reflects the amount of data in OutBuffer.
3. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.

(The first two steps are not applicable if the requested operation is not expected to return data.)

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

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

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 receives 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 is not expected to 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 ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts 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_before_lock Event (CBFilter Struct)

This event fires before a range of bytes in a file is locked.

Syntax

// CBFilterBeforeLockEventArgs carries the CBFilter BeforeLock event's parameters.
pub struct CBFilterBeforeLockEventArgs {
  fn file_name(&self) -> &String
  fn offset(&self) -> i64
  fn set_offset(&self, value : i64)
  fn length(&self) -> i64
  fn set_length(&self, value : i64)
  fn key(&self) -> i64
  fn fail_immediately(&self) -> bool
  fn set_fail_immediately(&self, value : bool)
  fn exclusive_lock(&self) -> bool
  fn set_exclusive_lock(&self, value : bool)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeLockEvent defines the signature of the CBFilter BeforeLock event's handler function.
pub trait CBFilterBeforeLockEvent {
  fn on_before_lock(&self, sender : CBFilter, e : &mut CBFilterBeforeLockEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_lock(&self) -> &'a dyn CBFilterBeforeLockEvent;
  pub fn set_on_before_lock(&mut self, value : &'a dyn CBFilterBeforeLockEvent);
  ...
}

Remarks

This event fires before a range of bytes in the file specified by FileName is 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 may use this event to modify the request's parameters.

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

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

The Offset parameter specifies the byte offset where the byte range lock should start.

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

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

The FailImmediately parameter specifies whether the request should fail if the lock cannot be granted immediately.

The ExclusiveLock parameter specifies whether the byte range lock should be exclusive (true) or shared (false).

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_open_file Event (CBFilter Struct)

This event fires before a file or directory is opened.

Syntax

// CBFilterBeforeOpenFileEventArgs carries the CBFilter BeforeOpenFile event's parameters.
pub struct CBFilterBeforeOpenFileEventArgs {
  fn file_name(&self) -> &String
  fn existing_attributes(&self) -> i32
  fn isolate(&self) -> bool
  fn set_isolate(&self, value : bool)
  fn backend_file_name(&self) -> &String
  fn set_backend_file_name(&self, value : String)
  fn set_backend_file_name_ref(&self, value : &String)
  fn desired_access(&self) -> i32
  fn set_desired_access(&self, value : i32)
  fn attributes(&self) -> i32
  fn set_attributes(&self, value : i32)
  fn share_mode(&self) -> i32
  fn set_share_mode(&self, value : i32)
  fn options(&self) -> i32
  fn set_options(&self, value : i32)
  fn create_disposition(&self) -> i32
  fn set_create_disposition(&self, value : i32)
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeOpenFileEvent defines the signature of the CBFilter BeforeOpenFile event's handler function.
pub trait CBFilterBeforeOpenFileEvent {
  fn on_before_open_file(&self, sender : CBFilter, e : &mut CBFilterBeforeOpenFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_open_file(&self) -> &'a dyn CBFilterBeforeOpenFileEvent;
  pub fn set_on_before_open_file(&mut self, value : &'a dyn CBFilterBeforeOpenFileEvent);
  ...
}

Remarks

This event fires before the file or directory specified by FileName is 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_before_create_file.

Applications may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false; and set Status to the desired NT status (the parameter is set to STATUS_ACCESS_DENIED before the event is fired).

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

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

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

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.

To redirect file access to another location, or to provide custom file content, set Isolate to true. For instance if Process A and Process B both access a file, isolation allows returning different content to each process. When Isolate is set to true the BackendFileName parameter determines if the file is redirected, and to where.

When requests are redirected to an existing file on disk a dedicated cache is created for the isolated file by the CBFilter driver. This cache ensures that the data it holds do not interfere with the data read from or written to the file when it is opened without isolation. Please see the File Isolation topic for further details.

To ensure that isolation works properly, on Windows 11, the on_bypass_io_request event is fired when the OS makes a request to enable BypassIO on this file, giving a way for the application to forbid BypassIO with an application-specific error code and explanation.

Requests may also be redirected to another file or directory via the on_reparse_file_name event which is fired before this event. In order for the on_reparse_file_name event to fire, a standard filter rule must exist that includes the FS_CE_REPARSE_FILENAME flag. For more details, please see the on_reparse_file_name topic.

The initial values of 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 Internet Relay Programming).

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:

When the file being created or opened is virtual, the event handler must inspect and handle the value of the ShareMode parameter as a filesystem would normally do it.

CreateDisposition may contain one of the following values:

When the file being created or opened is virtual, the event handler must inspect and handle the value of the CreateDisposition parameter as a filesystem would normally do it. This includes adjusting the file size and updating the time attributes depending on the flag. For a virtual file, the driver returns the CreationStatus value that is derived from CreateDisposition as follows: If the event handler needs to change the returned CreationStatus, it should change the value of the CreateDisposition to the FILE_DISPOSITION_*** value that leads to the desired CreationStatus value (e.g. set the value to FILE_DISPOSITION_OPEN_EXISTING so that the driver returns CREATION_STATUS_OPENED).

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 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 is 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 only if it was specified by the calling process; its presence or absence does not indicate the real presence of the attribute on the file or directory on disk.

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: Files can be deleted in different ways, so do not use this check to take actions related to tracking file deletion operations. Instead, use the events related to file deletion.

To prevent a file or directory from being opened, set the ResultCode parameter to a non-zero value (typically ERROR_ACCESS_DENIED (5)).

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 an application needs to alter the security information, it can do this by placing up to Length bytes of information into the SecurityDescriptor buffer.

Note: Changing the security data is possible only when the PassSecurityInFileOpenEvents configuration setting is enabled.

If the capacity reflected by the Length parameter is not enough to accommodate the security information, set LengthNeeded to the number of bytes necessary to hold the data, and return the ERROR_INSUFFICIENT_BUFFER error code via ResultCode.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

If the Options contains the FILE_FLAG_DELETE_ON_CLOSE flag, the on_before_can_file_be_deleted event will fire before this event.

If the file is opened with extended attributes passed in the request, the on_before_set_ea event will fire after 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 (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_query_ea Event (CBFilter Struct)

This event fires before information about extended attributes of a file is retrieved.

Syntax

// CBFilterBeforeQueryEaEventArgs carries the CBFilter BeforeQueryEa event's parameters.
pub struct CBFilterBeforeQueryEaEventArgs {
  fn file_name(&self) -> &String
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn return_single_entry(&self) -> bool
  fn set_return_single_entry(&self, value : bool)
  fn ea_list(&self) -> *mut u8
  fn ea_list_length(&self) -> i32
  fn set_ea_list_length(&self, value : i32)
  fn ea_index(&self) -> i32
  fn set_ea_index(&self, value : i32)
  fn restart_scan(&self) -> bool
  fn set_restart_scan(&self, value : bool)
  fn length_returned(&self) -> i32
  fn set_length_returned(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeQueryEaEvent defines the signature of the CBFilter BeforeQueryEa event's handler function.
pub trait CBFilterBeforeQueryEaEvent {
  fn on_before_query_ea(&self, sender : CBFilter, e : &mut CBFilterBeforeQueryEaEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_query_ea(&self) -> &'a dyn CBFilterBeforeQueryEaEvent;
  pub fn set_on_before_query_ea(&mut self, value : &'a dyn CBFilterBeforeQueryEaEvent);
  ...
}

Remarks

This event fires before information about extended attributes of the file specified by FileName is retrieved using the ZwQueryEaFile or FltQueryEaFile function of the system API. 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_CE_BEFORE_QUERY_EA flag.

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

The Buffer parameter points to a memory buffer, into which, if the request is successful, the filesystem will place 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 BufferLength 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. The list may be modified by an event handler, if needed, provided that the size of the new or modified data does not exceed the value of the EaListLength parameter.

EaIndex is an optional parameter that specifies the starting index of the attribute, information about which is 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. The parameter may be modified by an event handler if needed.

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

Applications may use this event to modify the request's data before it continues onward, or to handle the request entirely (preventing it from continuing onward). In these cases, applications must do the following:

1. Copy no more than BufferLength bytes into Buffer.
2. Update the LengthReturned parameter's value afterward so that it correctly reflects the amount of data in Buffer.
3. If the request has been handled and should not continue onward, set ProcessRequest to false.

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_query_file_info Event (CBFilter Struct)

This event fires before information about a file or directory is retrieved.

Syntax

// CBFilterBeforeQueryFileInfoEventArgs carries the CBFilter BeforeQueryFileInfo event's parameters.
pub struct CBFilterBeforeQueryFileInfoEventArgs {
  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 set_valid_bytes(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeQueryFileInfoEvent defines the signature of the CBFilter BeforeQueryFileInfo event's handler function.
pub trait CBFilterBeforeQueryFileInfoEvent {
  fn on_before_query_file_info(&self, sender : CBFilter, e : &mut CBFilterBeforeQueryFileInfoEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_query_file_info(&self) -> &'a dyn CBFilterBeforeQueryFileInfoEvent;
  pub fn set_on_before_query_file_info(&mut self, value : &'a dyn CBFilterBeforeQueryFileInfoEvent);
  ...
}

Remarks

This event fires before information about the file or directory specified by FileName is 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_CE_BEFORE_QUERY_FILE_INFO flag.

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

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

The Buffer parameter points to a memory buffer that receives 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 EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

Applications may use this event to modify the request's data before it continues onward, or to handle the request entirely (preventing it from continuing onward). In these cases, applications must do the following:

1. Copy no more than BufferLength bytes into Buffer.
2. Update the ValidBytes parameter's value afterward so that it correctly reflects the amount of data in Buffer.
3. If the request has been handled and should not continue onward, set ProcessRequest to false.

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_read_file Event (CBFilter Struct)

This event fires before data are read from a file.

Syntax

// CBFilterBeforeReadFileEventArgs carries the CBFilter BeforeReadFile event's parameters.
pub struct CBFilterBeforeReadFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn set_position(&self, value : i64)
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn bytes_to_read(&self) -> i32
  fn set_bytes_to_read(&self, value : i32)
  fn reserved(&self) -> i32
  fn set_reserved(&self, value : i32)
  fn direction(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeReadFileEvent defines the signature of the CBFilter BeforeReadFile event's handler function.
pub trait CBFilterBeforeReadFileEvent {
  fn on_before_read_file(&self, sender : CBFilter, e : &mut CBFilterBeforeReadFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_read_file(&self) -> &'a dyn CBFilterBeforeReadFileEvent;
  pub fn set_on_before_read_file(&mut self, value : &'a dyn CBFilterBeforeReadFileEvent);
  ...
}

Remarks

This event fires before data are read from 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 that intend to modify a file's data after it is read may use this event to modify the request's parameters, if necessary (e.g., to ensure that the correct data are read from the file and made available for postprocessing during the on_after_read_file event). Applications may also use this event to block the request entirely by returning an appropriate error code (e.g., ACCESS_DENIED) via ResultCode.

Alternatively, applications may use this event to handle the underlying request, in which case they must do the following:

1. Enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires).
2. Copy no more than BufferLength bytes into Buffer.
3. Update the BytesToRead parameter's value afterward so that it correctly reflects the amount of data in Buffer.
4. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.

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

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

The Position parameter specifies the byte offset in the file at which reading should start.

The Buffer parameter points to a memory buffer that receives the data read from the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToRead parameter's initial value reflects how many bytes should be read from the file (i.e., how many bytes the requestor expects will be read). This parameter's value may be changed (for either of the reasons discussed above), but it must not exceed BufferLength.

Note: However, reading more or less data than requested is not expected behavior and likely will cause the requestor to misbehave. Applications that change BytesToRead, for any reason, should use the on_after_read_file event to "cover up" such behavior; please refer to its documentation for more information.

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 EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_rename_or_move_file Event (CBFilter Struct)

This event fires before a file or directory is renamed or moved.

Syntax

// CBFilterBeforeRenameOrMoveFileEventArgs carries the CBFilter BeforeRenameOrMoveFile event's parameters.
pub struct CBFilterBeforeRenameOrMoveFileEventArgs {
  fn file_name(&self) -> &String
  fn new_file_name(&self) -> &String
  fn replace_if_exists(&self) -> bool
  fn set_replace_if_exists(&self, value : bool)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeRenameOrMoveFileEvent defines the signature of the CBFilter BeforeRenameOrMoveFile event's handler function.
pub trait CBFilterBeforeRenameOrMoveFileEvent {
  fn on_before_rename_or_move_file(&self, sender : CBFilter, e : &mut CBFilterBeforeRenameOrMoveFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_rename_or_move_file(&self) -> &'a dyn CBFilterBeforeRenameOrMoveFileEvent;
  pub fn set_on_before_rename_or_move_file(&mut self, value : &'a dyn CBFilterBeforeRenameOrMoveFileEvent);
  ...
}

Remarks

This event fires before the file or directory specified by FileName is 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 may use this event to modify the request's parameters, or to block the request entirely. To do the latter, set ProcessRequest to false.

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

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

The ReplaceIfExists parameter specifies what to do if a file with the specified NewFileName already exists. If this parameter is true, the existing file will be overwritten by the file being renamed/moved; if this parameter is false, the operation will fail.

Note: Windows only allows files to be overwritten; if the destination is an existing directory, the request will be denied regardless of this parameter's value.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_set_allocation_size Event (CBFilter Struct)

This event fires before a file's allocation size is changed.

Syntax

// CBFilterBeforeSetAllocationSizeEventArgs carries the CBFilter BeforeSetAllocationSize event's parameters.
pub struct CBFilterBeforeSetAllocationSizeEventArgs {
  fn file_name(&self) -> &String
  fn allocation_size(&self) -> i64
  fn set_allocation_size(&self, value : i64)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeSetAllocationSizeEvent defines the signature of the CBFilter BeforeSetAllocationSize event's handler function.
pub trait CBFilterBeforeSetAllocationSizeEvent {
  fn on_before_set_allocation_size(&self, sender : CBFilter, e : &mut CBFilterBeforeSetAllocationSizeEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_set_allocation_size(&self) -> &'a dyn CBFilterBeforeSetAllocationSizeEvent;
  pub fn set_on_before_set_allocation_size(&mut self, value : &'a dyn CBFilterBeforeSetAllocationSizeEvent);
  ...
}

Remarks

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

Applications may use this event to modify the request's parameters.

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

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

The AllocationSize parameter specifies 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. Applications may track such situations and avoid reallocating disk space where possible to improve performance.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_set_ea Event (CBFilter Struct)

This event fires before extended attributes of a file are changed.

Syntax

// CBFilterBeforeSetEaEventArgs carries the CBFilter BeforeSetEa event's parameters.
pub struct CBFilterBeforeSetEaEventArgs {
  fn file_name(&self) -> &String
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeSetEaEvent defines the signature of the CBFilter BeforeSetEa event's handler function.
pub trait CBFilterBeforeSetEaEvent {
  fn on_before_set_ea(&self, sender : CBFilter, e : &mut CBFilterBeforeSetEaEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_set_ea(&self) -> &'a dyn CBFilterBeforeSetEaEvent;
  pub fn set_on_before_set_ea(&mut self, value : &'a dyn CBFilterBeforeSetEaEvent);
  ...
}

Remarks

This event fires before extended attributes are changed for the file specified by FileName using the ZwSetEaFile or FltSetEaFile function of the system API. 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_before_create_file or on_before_open_file event.

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

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

The Buffer parameter points to a memory buffer that specifies the extended attribute information. The buffer referenced by the Buffer parameter may be modified when needed if the request is to be passed further to other filters and the filesystem driver. 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 Microsoft's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_set_file_attributes Event (CBFilter Struct)

This event fires before a file or directory's attributes or times are changed.

Syntax

// CBFilterBeforeSetFileAttributesEventArgs carries the CBFilter BeforeSetFileAttributes event's parameters.
pub struct CBFilterBeforeSetFileAttributesEventArgs {
  fn file_name(&self) -> &String
  fn creation_time(&self) -> &chrono::DateTime<Utc>
  fn set_creation_time(&self, value : chrono::DateTime<Utc>)
  fn set_creation_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_access_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_access_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_access_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn set_last_write_time(&self, value : chrono::DateTime<Utc>)
  fn set_last_write_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn change_time(&self) -> &chrono::DateTime<Utc>
  fn set_change_time(&self, value : chrono::DateTime<Utc>)
  fn set_change_time_ref(&self, value : &chrono::DateTime<Utc>)
  fn attributes(&self) -> i32
  fn set_attributes(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeSetFileAttributesEvent defines the signature of the CBFilter BeforeSetFileAttributes event's handler function.
pub trait CBFilterBeforeSetFileAttributesEvent {
  fn on_before_set_file_attributes(&self, sender : CBFilter, e : &mut CBFilterBeforeSetFileAttributesEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_set_file_attributes(&self) -> &'a dyn CBFilterBeforeSetFileAttributesEvent;
  pub fn set_on_before_set_file_attributes(&mut self, value : &'a dyn CBFilterBeforeSetFileAttributesEvent);
  ...
}

Remarks

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

Applications may use this event to modify the request's parameters.

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

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

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_set_file_info Event (CBFilter Struct)

This event fires before information about a file or directory is changed.

Syntax

// CBFilterBeforeSetFileInfoEventArgs carries the CBFilter BeforeSetFileInfo event's parameters.
pub struct CBFilterBeforeSetFileInfoEventArgs {
  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 set_valid_bytes(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeSetFileInfoEvent defines the signature of the CBFilter BeforeSetFileInfo event's handler function.
pub trait CBFilterBeforeSetFileInfoEvent {
  fn on_before_set_file_info(&self, sender : CBFilter, e : &mut CBFilterBeforeSetFileInfoEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_set_file_info(&self) -> &'a dyn CBFilterBeforeSetFileInfoEvent;
  pub fn set_on_before_set_file_info(&mut self, value : &'a dyn CBFilterBeforeSetFileInfoEvent);
  ...
}

Remarks

This event fires before information about the file or directory specified by FileName is 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 may use this event to modify the request's data before it continues onward, in which case they must do the following:

1. Copy no more than BufferLength bytes into Buffer.
2. Update the ValidBytes parameter's value afterward so that it correctly reflects the amount of data in Buffer.

Alternatively, applications may use this event to handle the underlying request, preventing it from continuing onward, by setting ProcessRequest to false.

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

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

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

The Buffer parameter points to a memory buffer that specifies 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 EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_set_file_security Event (CBFilter Struct)

This event fires before a file or directory's security attributes are changed.

Syntax

// CBFilterBeforeSetFileSecurityEventArgs carries the CBFilter BeforeSetFileSecurity event's parameters.
pub struct CBFilterBeforeSetFileSecurityEventArgs {
  fn file_name(&self) -> &String
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeSetFileSecurityEvent defines the signature of the CBFilter BeforeSetFileSecurity event's handler function.
pub trait CBFilterBeforeSetFileSecurityEvent {
  fn on_before_set_file_security(&self, sender : CBFilter, e : &mut CBFilterBeforeSetFileSecurityEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_set_file_security(&self) -> &'a dyn CBFilterBeforeSetFileSecurityEvent;
  pub fn set_on_before_set_file_security(&mut self, value : &'a dyn CBFilterBeforeSetFileSecurityEvent);
  ...
}

Remarks

This event fires before security attributes are changed 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_CE_BEFORE_SET_SECURITY flag.

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

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, will 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 specifies the new security information. The buffer referenced by the SecurityDescriptor parameter may be modified when needed if the request is to be passed further to other filters and the filesystem driver. 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 EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_set_file_size Event (CBFilter Struct)

This event fires before a file is resized.

Syntax

// CBFilterBeforeSetFileSizeEventArgs carries the CBFilter BeforeSetFileSize event's parameters.
pub struct CBFilterBeforeSetFileSizeEventArgs {
  fn file_name(&self) -> &String
  fn size(&self) -> i64
  fn set_size(&self, value : i64)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeSetFileSizeEvent defines the signature of the CBFilter BeforeSetFileSize event's handler function.
pub trait CBFilterBeforeSetFileSizeEvent {
  fn on_before_set_file_size(&self, sender : CBFilter, e : &mut CBFilterBeforeSetFileSizeEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_set_file_size(&self) -> &'a dyn CBFilterBeforeSetFileSizeEvent;
  pub fn set_on_before_set_file_size(&mut self, value : &'a dyn CBFilterBeforeSetFileSizeEvent);
  ...
}

Remarks

This event fires before the file specified by FileName is 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 may use this event to modify the request's parameters.

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

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_set_reparse_point Event (CBFilter Struct)

This event fires when the OS wants to create or update a reparse point on a file or directory.

Syntax

// CBFilterBeforeSetReparsePointEventArgs carries the CBFilter BeforeSetReparsePoint event's parameters.
pub struct CBFilterBeforeSetReparsePointEventArgs {
  fn file_name(&self) -> &String
  fn reparse_tag(&self) -> i64
  fn reparse_buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn data_length(&self) -> i32
  fn set_data_length(&self, value : i32)
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeSetReparsePointEvent defines the signature of the CBFilter BeforeSetReparsePoint event's handler function.
pub trait CBFilterBeforeSetReparsePointEvent {
  fn on_before_set_reparse_point(&self, sender : CBFilter, e : &mut CBFilterBeforeSetReparsePointEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_set_reparse_point(&self) -> &'a dyn CBFilterBeforeSetReparsePointEvent;
  pub fn set_on_before_set_reparse_point(&mut self, value : &'a dyn CBFilterBeforeSetReparsePointEvent);
  ...
}

Remarks

This event fires before the OS creates or updates a reparse point on 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_CE_BEFORE_SET_REPARSE_POINT flag.

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

The ReparseTag is the reparse tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; for convenience, the struct extracts it and provides it separately. If the event handler needs to change the reparse tag, it may do so in ReparseBuffer.

The ReparseBuffer parameter points to a memory buffer that specifies the new reparse point information. The buffer referenced by the ReparseBuffer parameter may be modified when needed if the request is to be passed further to other filters and the filesystem driver. The DataLength parameter initially reflects the length of the data contained in the buffer, in bytes. If the event handler updates the data in the ReparseBuffer, it should adjust DataLength to the size of the new data, placed to the buffer. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

Please refer to the Reparse Points topic for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_unlock_all Event (CBFilter Struct)

This event fires before all locked byte ranges in a file are unlocked.

Syntax

// CBFilterBeforeUnlockAllEventArgs carries the CBFilter BeforeUnlockAll event's parameters.
pub struct CBFilterBeforeUnlockAllEventArgs {
  fn file_name(&self) -> &String
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeUnlockAllEvent defines the signature of the CBFilter BeforeUnlockAll event's handler function.
pub trait CBFilterBeforeUnlockAllEvent {
  fn on_before_unlock_all(&self, sender : CBFilter, e : &mut CBFilterBeforeUnlockAllEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_unlock_all(&self) -> &'a dyn CBFilterBeforeUnlockAllEvent;
  pub fn set_on_before_unlock_all(&mut self, value : &'a dyn CBFilterBeforeUnlockAllEvent);
  ...
}

Remarks

This event fires before all locked byte ranges in the file specified by FileName are 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_CE_BEFORE_LOCK_CONTROL flag.

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_unlock_all_by_key Event (CBFilter Struct)

This event fires before all locked byte ranges in a file, associated with a particular key, are unlocked.

Syntax

// CBFilterBeforeUnlockAllByKeyEventArgs carries the CBFilter BeforeUnlockAllByKey event's parameters.
pub struct CBFilterBeforeUnlockAllByKeyEventArgs {
  fn file_name(&self) -> &String
  fn key(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeUnlockAllByKeyEvent defines the signature of the CBFilter BeforeUnlockAllByKey event's handler function.
pub trait CBFilterBeforeUnlockAllByKeyEvent {
  fn on_before_unlock_all_by_key(&self, sender : CBFilter, e : &mut CBFilterBeforeUnlockAllByKeyEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_unlock_all_by_key(&self) -> &'a dyn CBFilterBeforeUnlockAllByKeyEvent;
  pub fn set_on_before_unlock_all_by_key(&mut self, value : &'a dyn CBFilterBeforeUnlockAllByKeyEvent);
  ...
}

Remarks

This event fires before all locked byte ranges in the file specified by FileName, and associated with the specified Key, are 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_CE_BEFORE_LOCK_CONTROL flag.

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

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

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_unlock_single Event (CBFilter Struct)

This event fires before a particular locked byte range in a file is unlocked.

Syntax

// CBFilterBeforeUnlockSingleEventArgs carries the CBFilter BeforeUnlockSingle event's parameters.
pub struct CBFilterBeforeUnlockSingleEventArgs {
  fn file_name(&self) -> &String
  fn offset(&self) -> i64
  fn set_offset(&self, value : i64)
  fn length(&self) -> i64
  fn set_length(&self, value : i64)
  fn key(&self) -> i64
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeUnlockSingleEvent defines the signature of the CBFilter BeforeUnlockSingle event's handler function.
pub trait CBFilterBeforeUnlockSingleEvent {
  fn on_before_unlock_single(&self, sender : CBFilter, e : &mut CBFilterBeforeUnlockSingleEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_unlock_single(&self) -> &'a dyn CBFilterBeforeUnlockSingleEvent;
  pub fn set_on_before_unlock_single(&mut self, value : &'a dyn CBFilterBeforeUnlockSingleEvent);
  ...
}

Remarks

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

Applications may use this event to modify the request's parameters.

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

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

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_before_lock event's documentation for more information.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_write_file Event (CBFilter Struct)

This event fires before data are written to a file.

Syntax

// CBFilterBeforeWriteFileEventArgs carries the CBFilter BeforeWriteFile event's parameters.
pub struct CBFilterBeforeWriteFileEventArgs {
  fn file_name(&self) -> &String
  fn position(&self) -> i64
  fn set_position(&self, value : i64)
  fn buffer(&self) -> *mut u8
  fn buffer_length(&self) -> i32
  fn bytes_to_write(&self) -> i32
  fn set_bytes_to_write(&self, value : i32)
  fn reserved(&self) -> i32
  fn set_reserved(&self, value : i32)
  fn direction(&self) -> i32
  fn file_context(&self) -> usize
  fn set_file_context(&self, value : usize)
  fn handle_context(&self) -> usize
  fn set_handle_context(&self, value : usize)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn process_request(&self) -> bool
  fn set_process_request(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterBeforeWriteFileEvent defines the signature of the CBFilter BeforeWriteFile event's handler function.
pub trait CBFilterBeforeWriteFileEvent {
  fn on_before_write_file(&self, sender : CBFilter, e : &mut CBFilterBeforeWriteFileEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_before_write_file(&self) -> &'a dyn CBFilterBeforeWriteFileEvent;
  pub fn set_on_before_write_file(&mut self, value : &'a dyn CBFilterBeforeWriteFileEvent);
  ...
}

Remarks

This event fires before data are 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 may use this event to modify the request's parameters or data. Applications that choose to modify the request's data must do the following:

1. Enable the ModifiableReadWriteBuffers configuration setting (i.e., before this event fires).
2. Copy no more than BufferLength bytes into Buffer.
3. Update the BytesToWrite parameter's value afterward so that it correctly reflects the amount of data in Buffer.

Applications may also use this event to block the request entirely by returning an appropriate error code (e.g., ACCESS_DENIED) via ResultCode.

Alternatively, applications may use this event to handle the underlying request, in which case they must do the following:

1. Write the data pointed to by Buffer to the desired location (after preprocessing it, if necessary).
2. Update the BytesToWrite parameter's value afterward so that it correctly reflects the amount of data that were written.
3. Set ProcessRequest to false to indicate that the request has been handled and should not continue onward.

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

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

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

The Buffer parameter points to a memory buffer that contains the data to write to the file. The BufferLength parameter reflects the capacity of Buffer, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The BytesToWrite parameter's initial value reflects how many bytes should be written to the file (i.e., how many bytes the requestor expects will be written). This parameter's value may be changed (for either of the reasons discussed above), but it must not exceed BufferLength.

Note: However, writing more or less data than requested is not expected behavior and likely will cause the requestor to misbehave. Applications that change BytesToWrite, for any reason, should use the on_after_write_file event to "cover up" such behavior; please refer to its documentation for more information.

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 EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information. (If the system's cache manager or memory manager initiated the operation, HandleContext may be absent, in which case it will be .)

The ProcessRequest parameter controls whether the request is sent onward for further processing by subsequent filter drivers and the filesystem; it is true by default.

When ProcessRequest to false (which means that the request was handled), the handler may additionally specify the status of the handling by setting the Status parameter to the required NT status code (this is not a Win32 error code!).

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_bypass_io_request Event (CBFilter Struct)

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

Syntax

// CBFilterBypassIORequestEventArgs carries the CBFilter BypassIORequest event's parameters.
pub struct CBFilterBypassIORequestEventArgs {
  fn file_name(&self) -> &String
  fn request_code(&self) -> i32
  fn file_context(&self) -> usize
  fn handle_context(&self) -> usize
  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)
}

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

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

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.

The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

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

on_cleanup_context Event (CBFilter Struct)

This event fires when the application-defined data stored in one or more contexts need to be cleaned up.

Syntax

// CBFilterCleanupContextEventArgs carries the CBFilter CleanupContext event's parameters.
pub struct CBFilterCleanupContextEventArgs {
  fn file_context(&self) -> usize
  fn handle_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterCleanupContextEvent defines the signature of the CBFilter CleanupContext event's handler function.
pub trait CBFilterCleanupContextEvent {
  fn on_cleanup_context(&self, sender : CBFilter, e : &mut CBFilterCleanupContextEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_cleanup_context(&self) -> &'a dyn CBFilterCleanupContextEvent;
  pub fn set_on_cleanup_context(&mut self, value : &'a dyn CBFilterCleanupContextEvent);
  ...
}

Remarks

This event fires after a file or directory is closed, just before any contexts related to it are discarded, giving applications a chance to clean up any information stored in them.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The FileContext and HandleContext parameters are placeholders for application-defined data associated with the file and specific handle, respectively. Please refer to the Contexts topic for more information.

When a handle to some file or directory is closed, this event will fire if the HandleContext associated with that handle is not . When the last handle to the file or directory is closed, this event will fire if the HandleContext associated with that handle or the FileContext associated with that file or directory is not . After this event fires, the applicable contexts are set back to automatically.

Applications that need to know the name of the file or directory this event is firing for should store a copy of that name in the context during an earlier event.

This event is optional; it will fire regardless of whether any filter rules are present, but only if FileContext, HandleContext, or both, are not already . Applications that clean up their contexts (and set them back to ) when a file is being closed, or earlier, do not need to handle 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 (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_error Event (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyCanFileBeDeletedEventArgs carries the CBFilter NotifyCanFileBeDeleted event's parameters.
pub struct CBFilterNotifyCanFileBeDeletedEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyCreateFileEventArgs carries the CBFilter NotifyCreateFile event's parameters.
pub struct CBFilterNotifyCreateFileEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

This event fires when a hard link has been created.

Syntax

// CBFilterNotifyCreateHardLinkEventArgs carries the CBFilter NotifyCreateHardLink event's parameters.
pub struct CBFilterNotifyCreateHardLinkEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyEnumerateDirectoryEventArgs carries the CBFilter NotifyEnumerateDirectory event's parameters.
pub struct CBFilterNotifyEnumerateDirectoryEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

This event fires when an IRP_MJ_FILE_SYSTEM_CONTROL operation has occurred.

Syntax

// CBFilterNotifyFsctlEventArgs carries the CBFilter NotifyFsctl event's parameters.
pub struct CBFilterNotifyFsctlEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyGetFileSecurityEventArgs carries the CBFilter NotifyGetFileSecurity event's parameters.
pub struct CBFilterNotifyGetFileSecurityEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyGetFileSizesEventArgs carries the CBFilter NotifyGetFileSizes event's parameters.
pub struct CBFilterNotifyGetFileSizesEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

This event fires when an IRP_MJ_DEVICE_CONTROL operation has occurred.

Syntax

// CBFilterNotifyIoctlEventArgs carries the CBFilter NotifyIoctl event's parameters.
pub struct CBFilterNotifyIoctlEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyLockEventArgs carries the CBFilter NotifyLock event's parameters.
pub struct CBFilterNotifyLockEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyOpenFileEventArgs carries the CBFilter NotifyOpenFile event's parameters.
pub struct CBFilterNotifyOpenFileEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyQueryEaEventArgs carries the CBFilter NotifyQueryEa event's parameters.
pub struct CBFilterNotifyQueryEaEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyQueryFileInfoEventArgs carries the CBFilter NotifyQueryFileInfo event's parameters.
pub struct CBFilterNotifyQueryFileInfoEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyReadFileEventArgs carries the CBFilter NotifyReadFile event's parameters.
pub struct CBFilterNotifyReadFileEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyRenameOrMoveFileEventArgs carries the CBFilter NotifyRenameOrMoveFile event's parameters.
pub struct CBFilterNotifyRenameOrMoveFileEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifySetAllocationSizeEventArgs carries the CBFilter NotifySetAllocationSize event's parameters.
pub struct CBFilterNotifySetAllocationSizeEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifySetEaEventArgs carries the CBFilter NotifySetEa event's parameters.
pub struct CBFilterNotifySetEaEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifySetFileAttributesEventArgs carries the CBFilter NotifySetFileAttributes event's parameters.
pub struct CBFilterNotifySetFileAttributesEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifySetFileInfoEventArgs carries the CBFilter NotifySetFileInfo event's parameters.
pub struct CBFilterNotifySetFileInfoEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifySetFileSecurityEventArgs carries the CBFilter NotifySetFileSecurity event's parameters.
pub struct CBFilterNotifySetFileSecurityEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

This event fires when a file has been resized.

Syntax

// CBFilterNotifySetFileSizeEventArgs carries the CBFilter NotifySetFileSize event's parameters.
pub struct CBFilterNotifySetFileSizeEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifySetReparsePointEventArgs carries the CBFilter NotifySetReparsePoint event's parameters.
pub struct CBFilterNotifySetReparsePointEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

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

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyUnlockAllByKeyEventArgs carries the CBFilter NotifyUnlockAllByKey event's parameters.
pub struct CBFilterNotifyUnlockAllByKeyEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyUnlockSingleEventArgs carries the CBFilter NotifyUnlockSingle event's parameters.
pub struct CBFilterNotifyUnlockSingleEventArgs {
  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)
}

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

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

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 (CBFilter Struct)

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

Syntax

// CBFilterNotifyWriteFileEventArgs carries the CBFilter NotifyWriteFile event's parameters.
pub struct CBFilterNotifyWriteFileEventArgs {
  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)
}

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

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

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_reparse_file_name Event (CBFilter Struct)

This event fires to allow file access to be dynamically redirected to another location.

Syntax

// CBFilterReparseFileNameEventArgs carries the CBFilter ReparseFileName event's parameters.
pub struct CBFilterReparseFileNameEventArgs {
  fn file_name(&self) -> &String
  fn desired_access(&self) -> i32
  fn reparsed_file_name(&self) -> &String
  fn new_file_name(&self) -> &String
  fn set_new_file_name(&self, value : String)
  fn set_new_file_name_ref(&self, value : &String)
  fn event_context(&self) -> usize
  fn set_event_context(&self, value : usize)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterReparseFileNameEvent defines the signature of the CBFilter ReparseFileName event's handler function.
pub trait CBFilterReparseFileNameEvent {
  fn on_reparse_file_name(&self, sender : CBFilter, e : &mut CBFilterReparseFileNameEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_reparse_file_name(&self) -> &'a dyn CBFilterReparseFileNameEvent;
  pub fn set_on_reparse_file_name(&mut self, value : &'a dyn CBFilterReparseFileNameEvent);
  ...
}

Remarks

Applications can use this event to dynamically redirect access to the file or directory specified by FileName to another location. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

The event fires before a file or directory is created or opened (before the corresponding on_before_create_file or on_before_open_file events fire).

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

The DesiredAccess parameter reflects the value that was passed for the similarly named parameter of the Windows API's CreateFile function. Please refer to Microsoft's documentation for more information.

The ReparsedFileName parameter reflects the default redirection destination. If the specified file or directory matches an existing reparse rule, this parameter's value is generated based on said rule; otherwise, this parameter will reflect the same value as FileName.

The NewFileName parameter specifies an application-defined redirection destination. This parameter's value, if set, must be less than 1024 characters in length.

If the application sets NewFileName to a nonempty value, it will be used as the redirection destination. Otherwise, the value reflected by ReparseFileName will be used as the redirection destination.

The EventContext parameter makes it possible to pass information between Before* and After* events that are related to the same OS request. The value assigned to EventContext by the event handler will reach on_before_create_file/on_before_open_file events and other events involved in the opening of the file.

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_reparse_with_tag Event (CBFilter Struct)

This event fires if an open operation returns STATUS_REPARSE so that the application can respond to the reparse point.

Syntax

// CBFilterReparseWithTagEventArgs carries the CBFilter ReparseWithTag event's parameters.
pub struct CBFilterReparseWithTagEventArgs {
  fn file_name(&self) -> &String
  fn new_file_name(&self) -> &String
  fn reparse_tag(&self) -> i32
  fn reparse_buffer(&self) -> *mut u8
  fn reparse_buffer_length(&self) -> i32
  fn file_context(&self) -> usize
  fn handle_context(&self) -> usize
  fn event_context(&self) -> usize
  fn reissue_io(&self) -> bool
  fn set_reissue_io(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBFilterReparseWithTagEvent defines the signature of the CBFilter ReparseWithTag event's handler function.
pub trait CBFilterReparseWithTagEvent {
  fn on_reparse_with_tag(&self, sender : CBFilter, e : &mut CBFilterReparseWithTagEventArgs);
}

impl <'a> CBFilter<'a> {
  pub fn on_reparse_with_tag(&self) -> &'a dyn CBFilterReparseWithTagEvent;
  pub fn set_on_reparse_with_tag(&mut self, value : &'a dyn CBFilterReparseWithTagEvent);
  ...
}

Remarks

This event fires if a STATUS_REPARSE result is returned when the OS attempts to open the file or directory specified by FileName, which indicates that a reparse point is associated with said file or directory or one of its parents. More specifically, it fires immediately after the open operation returns such a result. For more information about the FileName parameter and what it may contain, please refer to the Filenames In Events topic.

It is possible for applications to add reparse points to specific files/directories so that the filesystem will return STATUS_REPARSE when someone attempts to open them. Such applications can then use this event to perform some operation on the file/directory, assuming that the specified ReparseTag belongs to the application. Please refer to Microsoft's Reparse Point articles for more information.

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

If the reparse tag was recognized by the filesystem or some filesystem filter, NewFileName can contain the new path, to which the request should be sent.

The ReparseTag parameter reflects the reparse point's tag, which is the value the system uses to identify the format of the reparse point data. This value is also present in the ReparseBuffer data; the struct extracts it and provides it separately for convenience.

The ReparseBuffer parameter points to a memory buffer that contains the full reparse point data. The ReparseBufferLength parameter reflects the length of ReparseBuffer. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

The data are formatted using either a REPARSE_GUID_DATA_BUFFER structure or (for certain Microsoft-reserved tags) a REPARSE_DATA_BUFFER structure; please refer to Microsoft's documentation for more information.

If the part of the path contained in FileName constitutes a symbolic link or a junction point (both of which are handled by the filesystem), the structure in ReparseBuffer will contain the new path that is to replace a part of the original path. In such a case, the Reserved field of the REPARSE_DATA_BUFFER structure will contain the length in bytes in the original file name buffer that remains unchanged. This value, divided by 2, is the number of characters at the end of FileName that you must append to the new path, contained in ReparseBuffer.

ReissueIO can be set to true to instruct the OS to resend the original request again from the beginning. This may be necessary if the reparse tag is removed from the file or altered during this event.

Please refer to the Reparse Points 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_creation Event (CBFilter Struct)

Fires just after a new worker thread is created.

Syntax

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

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

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

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 (CBFilter Struct)

Fires just before a worker thread is terminated.

Syntax

// CBFilterWorkerThreadTerminationEventArgs carries the CBFilter WorkerThreadTermination event's parameters.
pub struct CBFilterWorkerThreadTerminationEventArgs {
}

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

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

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.

CBFSFilterStream Struct

Syntax

cbfsfilter::CBFSFilterStream

Remarks

The CBFSFilterStream struct is returned by some of the CBFilter struct's methods. All stream structs in CBFS Filter share a common API, which implements Read, Write, and Seek traits from Rust's io module, documented below.

Properties
Length	Gets or sets the length of the stream, in bytes. fn get_len(&self) -> std::io::Result<u64>; fn set_len(&self, size : u64) -> std::io::Result<()>;
Position	Gets the current position within the stream. fn stream_position(&self) -> std::io::Result<u64>;
Methods
Close	Closes the stream. Has no effect if the stream is already closed. fn close(&mut self);
Flush	Forces all data held by the stream's buffers to be written out to storage. fn flush(&mut self) -> std::io::Result<()>;
Read	Reads a sequence of bytes from the stream and advances the current position within the stream by the number of bytes read. fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize>; The number of bytes to read is determined as buf.len(). Fewer than the size of buf may be read if fewer bytes are available. Returns the number of bytes read, and any error encountered.
Seek	Sets the current position within the stream based on a particular point of origin. fn seek(&mut self, pos: std::io::SeekFrom) -> std::io::Result<u64>; Returns the new offset relative to the start of the stream, and any error encountered.
Write	Writes a sequence of bytes to the stream and advances the current position within the stream by the number of bytes written. fn write(&mut self, buf: &[u8]) -> std::io::Result<usize>; The number of bytes to write is determined as buf.len(). Returns the number of bytes written, and any error encountered.

Config Settings (CBFilter 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.

CBFilter Config Settings

Base Config Settings

Trappable Errors (CBFilter Struct)

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

Special Use Errors