Struct cbfsfilter::CBRegistry

Properties   Methods   Events   Config Settings   Errors  

The CBRegistry struct allows applications to intercept and control registry requests.

Syntax

cbfsfilter::CBRegistry

Remarks

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

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

Getting Started

1. If the struct's system driver has not been installed yet, call the install method to do so. This needs to be done only once.
   • In production, the driver can be installed (or updated) ahead of time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
2. Call the initialize method to initialize the CBRegistry struct. This must be done each time the application starts.
3. Add one or more filter rules using methods like add_filter_rule. (Rules also can 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 CBRegistry struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of CBRegistry 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 (CBRegistry 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 (CBRegistry 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.

Registry filter drivers are not required to specify an altitude; and this property's default empty value is interpreted as "no altitude". However, registry filter drivers that do not specify an altitude will always be attached near the top of the filter driver stack, which may not be desirable. Please refer to the Driver Altitudes topic for more information.

Data Type

String

default_rule_count Property (CBRegistry 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 (CBRegistry 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 (CBRegistry Struct)

This property reflects a registry key mask that determines which registry keys match the rule.

Syntax

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

Default Value

String::default()

Remarks

This property reflects a registry key mask that determines which registry keys match the rule.

This property reflects the registry key mask used to determine whether a registry key 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.

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

filter_rule_count Property (CBRegistry 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_mask

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

This property indicates the access restrictions enforced by the rule.

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.

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:

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

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

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.

This property indicates which registry operations, of those performed on matching registry keys, the struct should fire Control 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

filter_rule_mask Property (CBRegistry Struct)

This property reflects a registry key mask that determines which registry keys match the rule.

Syntax

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

Default Value

String::default()

Remarks

This property reflects a registry key mask that determines which registry keys match the rule.

This property reflects the registry key mask used to determine whether a registry key 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.

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

passthrough_rule_count Property (CBRegistry 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_mask

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

This property indicates the access restrictions lifted by the rule.

Syntax

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

Default Value

0

Remarks

This property indicates the access restrictions lifted by the rule.

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:

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

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

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.

This property indicates which registry operations, of those performed on matching registry keys, 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:

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

This property reflects a registry key mask that determines which registry keys match the rule.

Syntax

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

Default Value

String::default()

Remarks

This property reflects a registry key mask that determines which registry keys match the rule.

This property reflects the registry key mask used to determine whether a registry key 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.

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

serialize_events Property (CBRegistry 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 (CBRegistry Struct)

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

Syntax

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

Default Value

0

Remarks

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

Data Type

i64

add_default_rule Method (CBRegistry 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 registry keys that matches 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 registry keys. 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 or not the application that added them is open.

The Mask parameter must be a valid registry key mask according to the Registry Key Masks topic. Only the registry keys 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 registry keys. 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 are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

add_filtered_process_by_id Method (CBRegistry Struct)

This method adds a process, by process ID (PID), to the list of filtered processes.

Syntax

fn add_filtered_process_by_id(&self, process_id : i32, include_children : bool) -> Option<CBFSFilterError>

Remarks

This method adds the process with the specified ProcessId (PID) to the list of processes whose requests should be filtered (i.e., that the struct should fire events for).

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The ProcessId parameter specifies the PID of the process whose requests should be filtered. The value passed for this parameter must either be the PID of an existing process; or -1, which means "all processes". When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

The IncludeChildren parameter specifies whether requests made by the specified process's children should also be filtered.

Note: This method can be called only when active is true.

add_filtered_process_by_name Method (CBRegistry Struct)

This method adds a process, by name, to the list of filtered processes.

Syntax

fn add_filtered_process_by_name(&self, process_name : &String, include_children : bool) -> Option<CBFSFilterError>

Remarks

This method adds the process with the specified ProcessName to the list of processes whose requests should be filtered (i.e., that the struct should fire events for).

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The ProcessName parameter must be a valid process executable name. It may optionally begin with a path, and both the name and the path (if present) may include wildcards (* and ?). A process with a matching executable name does not actually need to exist when this method is called.

The IncludeChildren parameter specifies whether requests made by the specified process's children should also be filtered.

Note: This method can be called only when active is true.

add_filter_rule Method (CBRegistry 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) ->  Result<bool, CBFSFilterError>

Remarks

This method adds a standard filter rule or access rule for the registry keys that matches 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 registry operations, of those performed on matching registry keys, the struct should fire its events for. Access rules instruct the struct's system driver to apply certain access restrictions to matching registry keys.

The Mask parameter must be a valid registry key mask according to the Registry Key Masks topic. Only the registry keys 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 registry keys. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

The ControlFlags parameter specifies which registry operations the struct should fire Control 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 are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

add_ignored_process_by_id Method (CBRegistry Struct)

This method adds a process, by process Id (PID), to the list of ignored processes.

Syntax

fn add_ignored_process_by_id(&self, process_id : i32, include_children : bool) -> Option<CBFSFilterError>

Remarks

This method adds the process with the specified ProcessId (PID) to the list of processes whose requests should be ignored (i.e., that the struct should not fire events for).

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The ProcessId parameter specifies the PID of the process whose requests should be ignored. The value passed for this parameter must be the PID of an existing process. When adding a PID-based rule, you need to be aware of the PID Reuse behavior of Windows.

The IncludeChildren parameter specifies whether requests made by the specified process's children should also be ignored.

Note: The struct's system driver ignores all processes' requests by default; applications should use this method only to explicitly exclude a process that would otherwise be filtered because of a process filtering rule added with add_filtered_process_by_id or add_filtered_process_by_name.

Note: This method can be called only when active is true.

add_ignored_process_by_name Method (CBRegistry Struct)

This method adds a process, by name, to the list of ignored processes.

Syntax

fn add_ignored_process_by_name(&self, process_name : &String, include_children : bool) -> Option<CBFSFilterError>

Remarks

This method adds the process with the specified ProcessName to the list of processes whose requests should be ignored (i.e., that the struct should not fire events for).

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The ProcessName parameter must be a valid process executable name. It may optionally begin with a path, and both the name and the path (if present) may include wildcards (* and ?). A process with a matching executable name does not actually need to exist when this method is called.

The IncludeChildren parameter specifies whether requests made by the specified process's children should also be ignored.

Note: The struct's system driver ignores all processes' requests by default; applications should use this method only to explicitly exclude a process that would otherwise be filtered because of a process filtering rule added with add_filtered_process_by_id or add_filtered_process_by_name.

Note: This method can be called only when active is true.

add_passthrough_rule Method (CBRegistry Struct)

This method adds a passthrough rule.

Syntax

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

Remarks

This method adds a passthrough rule for the registry keys that matches 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 registry keys from being processed by other filter rules.

The Mask parameter must be a valid registry key mask according to the Registry Key Masks topic. Only the registry keys 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 registry keys. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

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

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 are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

close_default_rules_snapshot Method (CBRegistry 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.

config Method (CBRegistry 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 (CBRegistry 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.

delete_all_filter_rules Method (CBRegistry Struct)

This method deletes all standard filter rules.

Syntax

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

Remarks

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

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

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

Note: The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

delete_all_passthrough_rules Method (CBRegistry 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 are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

delete_default_rule Method (CBRegistry 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 registry key 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 are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

delete_filter_rule Method (CBRegistry 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) ->  Result<bool, CBFSFilterError>

Remarks

This method deletes the specified AccessFlags or ControlFlags from the standard filter rule 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 registry key 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:

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 are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

delete_passthrough_rule Method (CBRegistry Struct)

This method deletes a particular passthrough rule.

Syntax

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

Remarks

This method deletes the specified AccessFlags or ControlFlags 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 registry key 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:

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 are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists occurs in a thread-safe manner.

get_driver_status Method (CBRegistry 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 (CBRegistry 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_originator_process_id Method (CBRegistry Struct)

This method retrieves the process Id (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 registry operations to retrieve the process Id (PID) that initiated the operation. 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).

Note: This method can be called only within events.

get_originator_process_name Method (CBRegistry Struct)

This method 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 registry operations to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

Note: This method can be called only within events.

get_originator_thread_id Method (CBRegistry Struct)

This method retrieves the thread Id that initiated the operation.

Syntax

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

Remarks

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

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

Note: This method can be called only within events.

get_originator_token Method (CBRegistry Struct)

This method 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 events fired for registry operations to retrieve the security token associated with the process that initiated the operation. 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.

Note: This method can be called only within events.

initialize Method (CBRegistry 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 (CBRegistry 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, 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 .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, because 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 the driver to the appropriate Windows system directory.

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

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.

remove_filtered_process_by_id Method (CBRegistry Struct)

This method removes a process, by process Id (PID), from the list of filtered processes.

Syntax

fn remove_filtered_process_by_id(&self, process_id : i32) -> Option<CBFSFilterError>

Remarks

This method removes the process with the specified ProcessId (PID) from the list of processes whose requests should be filtered.

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The value passed for ProcessId must be one that was previously used to call add_filtered_process_by_id; please refer to its documentation for more information.

Note: This method can be called only when active is true.

remove_filtered_process_by_name Method (CBRegistry Struct)

This method removes a process, by name, from the list of filtered processes.

Syntax

fn remove_filtered_process_by_name(&self, process_name : &String) -> Option<CBFSFilterError>

Remarks

This method removes the process with the specified ProcessName from the list of processes whose requests should be filtered.

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The value passed for ProcessName must be one that was previously used to call add_filtered_process_by_name; please refer to its documentation for more information.

Note: This method can be called only when active is true.

remove_ignored_process_by_id Method (CBRegistry Struct)

This method removes a process, by process Id (PID), from the list of ignored processes.

Syntax

fn remove_ignored_process_by_id(&self, process_id : i32) -> Option<CBFSFilterError>

Remarks

This method removes the process with the specified ProcessId (PID) from the list of processes whose requests should be ignored.

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The value passed for ProcessId must be one that was previously used to call add_ignored_process_by_id; please refer to its documentation for more information.

Note: This method can be called only when active is true.

remove_ignored_process_by_name Method (CBRegistry Struct)

This method removes a process, by name, from the list of ignored processes.

Syntax

fn remove_ignored_process_by_name(&self, process_name : &String) -> Option<CBFSFilterError>

Remarks

This method removes the process with the specified ProcessName from the list of processes whose requests should be ignored.

This method is provided for compatibility with CBFS Registry 2017. Use of the new add_filter_rule, delete_filter_rule, and related methods is recommended instead.

The value passed for ProcessName must be one that was previously used to call add_ignored_process_by_name; please refer to its documentation for more information.

Note: This method can be called only when active is true.

reset_timeout Method (CBRegistry 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: This method can be called only within events.

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

This method starts filtering registry operations.

Syntax

fn start_filter(&self, timeout : i32) -> Option<CBFSFilterError>

Remarks

This method attaches the filter, causing the struct's driver to start filtering registry 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 (CBRegistry Struct)

This method stops filtering registry operations.

Syntax

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

Remarks

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

suspend_default_rules Method (CBRegistry 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.

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

This method uninstalls the struct's system driver.

Syntax

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

Remarks

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

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

Please refer to the Driver Installation topic for more information.

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

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

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

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

Note: This method cannot be called within events.

on_after_close_key Event (CBRegistry Struct)

This event fires after a registry key is closed.

Syntax

// CBRegistryAfterCloseKeyEventArgs carries the CBRegistry AfterCloseKey event's parameters.
pub struct CBRegistryAfterCloseKeyEventArgs {
  fn key_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterCloseKeyEvent defines the signature of the CBRegistry AfterCloseKey event's handler function.
pub trait CBRegistryAfterCloseKeyEvent {
  fn on_after_close_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterCloseKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_close_key(&self) -> &'a dyn CBRegistryAfterCloseKeyEvent;
  pub fn set_on_after_close_key(&mut self, value : &'a dyn CBRegistryAfterCloseKeyEvent);
  ...
}

Remarks

This event fires after a registry key is closed.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

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_key Event (CBRegistry Struct)

This event fires after a registry key is created.

Syntax

// CBRegistryAfterCreateKeyEventArgs carries the CBRegistry AfterCreateKey event's parameters.
pub struct CBRegistryAfterCreateKeyEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn key_handle(&self) -> i64
  fn set_key_handle(&self, value : i64)
  fn key_handle_context(&self) -> usize
  fn set_key_handle_context(&self, value : usize)
  fn granted_access(&self) -> i32
  fn set_granted_access(&self, value : i32)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterCreateKeyEvent defines the signature of the CBRegistry AfterCreateKey event's handler function.
pub trait CBRegistryAfterCreateKeyEvent {
  fn on_after_create_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterCreateKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_create_key(&self) -> &'a dyn CBRegistryAfterCreateKeyEvent;
  pub fn set_on_after_create_key(&mut self, value : &'a dyn CBRegistryAfterCreateKeyEvent);
  ...
}

Remarks

This event fires after a registry key is created.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The KeyHandle parameter specifies a handle to a registry key that should be opened instead of the one this event fired for. Applications can set this parameter to redirect access to the registry key associated with the specified handle.

The KeyHandleContext parameter is a placeholder for application-defined data associated with the application-provided registry key handle. Please refer to the Contexts topic for more information.

The GrantedAccess parameter specifies the granted access rights for an application-provided registry key handle. Applications that set KeyHandle must also set this parameter. Please refer to Microsoft's Registry Key Security and Access Rights article for more information about possible values.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires after a registry key is deleted.

Syntax

// CBRegistryAfterDeleteKeyEventArgs carries the CBRegistry AfterDeleteKey event's parameters.
pub struct CBRegistryAfterDeleteKeyEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterDeleteKeyEvent defines the signature of the CBRegistry AfterDeleteKey event's handler function.
pub trait CBRegistryAfterDeleteKeyEvent {
  fn on_after_delete_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterDeleteKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_delete_key(&self) -> &'a dyn CBRegistryAfterDeleteKeyEvent;
  pub fn set_on_after_delete_key(&mut self, value : &'a dyn CBRegistryAfterDeleteKeyEvent);
  ...
}

Remarks

This event fires after a registry key is deleted.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_value Event (CBRegistry Struct)

This event fires after a registry value is deleted.

Syntax

// CBRegistryAfterDeleteValueEventArgs carries the CBRegistry AfterDeleteValue event's parameters.
pub struct CBRegistryAfterDeleteValueEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterDeleteValueEvent defines the signature of the CBRegistry AfterDeleteValue event's handler function.
pub trait CBRegistryAfterDeleteValueEvent {
  fn on_after_delete_value(&self, sender : CBRegistry, e : &mut CBRegistryAfterDeleteValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_delete_value(&self) -> &'a dyn CBRegistryAfterDeleteValueEvent;
  pub fn set_on_after_delete_value(&mut self, value : &'a dyn CBRegistryAfterDeleteValueEvent);
  ...
}

Remarks

This event fires after a registry value is deleted.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires. A similar strategy can be applied if the application needs the registry value's name, which can be stored in KeyContext during the corresponding Before* event.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires after a subkey's information is retrieved during key enumeration.

Syntax

// CBRegistryAfterEnumerateKeyEventArgs carries the CBRegistry AfterEnumerateKey event's parameters.
pub struct CBRegistryAfterEnumerateKeyEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn index(&self) -> i32
  fn valid_fields(&self) -> i32
  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 name(&self) -> &String
  fn set_name(&self, value : String)
  fn set_name_ref(&self, value : &String)
  fn class_name(&self) -> &String
  fn set_class_name(&self, value : String)
  fn set_class_name_ref(&self, value : &String)
  fn sub_keys(&self) -> i32
  fn set_sub_keys(&self, value : i32)
  fn max_name_length(&self) -> i32
  fn set_max_name_length(&self, value : i32)
  fn max_class_name_length(&self) -> i32
  fn set_max_class_name_length(&self, value : i32)
  fn values(&self) -> i32
  fn set_values(&self, value : i32)
  fn max_value_name_length(&self) -> i32
  fn set_max_value_name_length(&self, value : i32)
  fn max_value_data_size(&self) -> i32
  fn set_max_value_data_size(&self, value : i32)
  fn virtualization_candidate(&self) -> bool
  fn set_virtualization_candidate(&self, value : bool)
  fn virtualization_enabled(&self) -> bool
  fn set_virtualization_enabled(&self, value : bool)
  fn virtual_target(&self) -> bool
  fn set_virtual_target(&self, value : bool)
  fn virtual_store(&self) -> bool
  fn set_virtual_store(&self, value : bool)
  fn virtual_source(&self) -> bool
  fn set_virtual_source(&self, value : bool)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterEnumerateKeyEvent defines the signature of the CBRegistry AfterEnumerateKey event's handler function.
pub trait CBRegistryAfterEnumerateKeyEvent {
  fn on_after_enumerate_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterEnumerateKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_enumerate_key(&self) -> &'a dyn CBRegistryAfterEnumerateKeyEvent;
  pub fn set_on_after_enumerate_key(&mut self, value : &'a dyn CBRegistryAfterEnumerateKeyEvent);
  ...
}

Remarks

This event fires after a subkey's information is retrieved during enumeration of a registry key's subkeys.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The Index parameter reflects the zero-based index of the key (within the registry key being enumerated).

The ValidFields parameter indicates which pieces of information about the key were retrieved. The value of this parameter is a combination of one or more of the following:

The LastWriteTime parameter specifies when the key was last changed, specified .

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters.

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters.

The SubKeys parameter specifies the number of subkeys that the key has.

The MaxNameLength parameter specifies the length, in bytes, of the key's longest subkey name.

The MaxClassNameLength parameter specifies the length, in bytes, of the key's longest subkey class name.

The Values parameter specifies the number of values the key has.

The MaxValueNameLength parameter specifies the length, in bytes, of the key's longest value name.

The MaxValueDataSize parameter specifies the length, in bytes, of the subkey's largest value data size.

The VirtualizationCandidate parameter specifies whether the key is part of the virtualization namespace scope.

The VirtualizationEnabled parameter specifies whether virtualization is enabled on the key. This parameter can only be true if VirtualizationCandidate is true.

The VirtualTarget parameter specifies whether the key is a virtual key. This parameter can only be true if both VirtualizationCandidate and VirtualizationEnabled are both false. Its value is only valid on virtual store key handles.

The VirtualStore parameter specifies whether the key is part of the virtual store path.

The VirtualSource parameter specifies whether the key has ever been virtualized. This parameter can only be true if VirtualizationCandidate is true.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_value Event (CBRegistry Struct)

This event fires after a registry value's information is retrieved during key value enumeration.

Syntax

// CBRegistryAfterEnumerateValueEventArgs carries the CBRegistry AfterEnumerateValue event's parameters.
pub struct CBRegistryAfterEnumerateValueEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn index(&self) -> i32
  fn valid_fields(&self) -> i32
  fn value_name(&self) -> &String
  fn set_value_name(&self, value : String)
  fn set_value_name_ref(&self, value : &String)
  fn value_type(&self) -> i32
  fn set_value_type(&self, value : i32)
  fn integer_value(&self) -> i64
  fn set_integer_value(&self, value : i64)
  fn string_value(&self) -> &String
  fn set_string_value(&self, value : String)
  fn set_string_value_ref(&self, value : &String)
  fn binary_value(&self) -> *mut u8
  fn max_binary_value_size(&self) -> i32
  fn binary_value_size(&self) -> i32
  fn set_binary_value_size(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterEnumerateValueEvent defines the signature of the CBRegistry AfterEnumerateValue event's handler function.
pub trait CBRegistryAfterEnumerateValueEvent {
  fn on_after_enumerate_value(&self, sender : CBRegistry, e : &mut CBRegistryAfterEnumerateValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_enumerate_value(&self) -> &'a dyn CBRegistryAfterEnumerateValueEvent;
  pub fn set_on_after_enumerate_value(&mut self, value : &'a dyn CBRegistryAfterEnumerateValueEvent);
  ...
}

Remarks

This event fires after a registry value's information is retrieved during enumeration of a registry key's values.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The Index parameter reflects the zero-based index of the registry value (within the registry key being enumerated).

The ValidFields parameter indicates which pieces of information about the registry value were retrieved. The value of this parameter is a combination of one or more of the following:

The ValueName parameter specifies the registry value's name.

The ValueType parameter specifies the registry value's type and determines which of the other parameters holds the registry value's data (please refer to their descriptions for more information). Possible values are as follows:

The IntegerValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_DWORD or REG_VALUETYPE_QWORD.

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ.

For REG_VALUETYPE_MULTI_SZ, data are formatted as multiple individual ETB-terminated strings concatenated together into a single null-terminated string (where ETB is the End-of-Transmission-Block character; 23/0x17). For example, the strings This is, a multistring, and value. would be encoded as This is[ETB]a multistring[ETB]value.[ETB][NUL].

Note: As Microsoft's Registry Value Types article describes, the native multistring data format uses null terminators for the individual strings (e.g., This is[NUL]a multistring[NUL]value.[NUL][NUL]); CBRegistry converts the individual null terminators to/from ETB characters internally for applications' convenience.

The BinaryValue parameter points to a memory buffer that holds the registry value's data if ValueType is REG_VALUETYPE_BINARY. The MaxBinaryValueSize and BinaryValueSize parameter specify the capacity of the BinaryValue buffer and the length of the data it contains, respectively, in bytes.

Always check MaxBinaryValueSize before copying any data into the BinaryValue buffer. If the buffer is large enough to hold all of the data, copy the data into it, and then update BinaryValueSize accordingly. If the buffer is not large enough, do not copy any data into it; instead, set BinaryValueSize to the required buffer size (i.e., the size of the data) and return the ERROR_MORE_DATA (234) error code via ResultCode.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key_security Event (CBRegistry Struct)

This event fires after a registry key's security attributes are changed.

Syntax

// CBRegistryAfterGetKeySecurityEventArgs carries the CBRegistry AfterGetKeySecurity event's parameters.
pub struct CBRegistryAfterGetKeySecurityEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  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 processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterGetKeySecurityEvent defines the signature of the CBRegistry AfterGetKeySecurity event's handler function.
pub trait CBRegistryAfterGetKeySecurityEvent {
  fn on_after_get_key_security(&self, sender : CBRegistry, e : &mut CBRegistryAfterGetKeySecurityEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_get_key_security(&self) -> &'a dyn CBRegistryAfterGetKeySecurityEvent;
  pub fn set_on_after_get_key_security(&mut self, value : &'a dyn CBRegistryAfterGetKeySecurityEvent);
  ...
}

Remarks

This event fires after security attributes are changed for the registry key specified by KeyContext.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

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 the 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 Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires after a registry key is opened.

Syntax

// CBRegistryAfterOpenKeyEventArgs carries the CBRegistry AfterOpenKey event's parameters.
pub struct CBRegistryAfterOpenKeyEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn key_handle(&self) -> i64
  fn set_key_handle(&self, value : i64)
  fn key_handle_context(&self) -> usize
  fn set_key_handle_context(&self, value : usize)
  fn granted_access(&self) -> i32
  fn set_granted_access(&self, value : i32)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterOpenKeyEvent defines the signature of the CBRegistry AfterOpenKey event's handler function.
pub trait CBRegistryAfterOpenKeyEvent {
  fn on_after_open_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterOpenKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_open_key(&self) -> &'a dyn CBRegistryAfterOpenKeyEvent;
  pub fn set_on_after_open_key(&mut self, value : &'a dyn CBRegistryAfterOpenKeyEvent);
  ...
}

Remarks

This event fires after a registry key is opened.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The KeyHandle parameter specifies a handle to a registry key that should be opened instead of the one this event fired for. Applications can set this parameter to redirect access to the registry key associated with the specified handle.

The KeyHandleContext parameter is a placeholder for application-defined data associated with the application-provided registry key handle. Please refer to the Contexts topic for more information.

The GrantedAccess parameter specifies the granted access rights for an application-provided registry key handle. Applications that set KeyHandle must also set this parameter. Please refer to Microsoft's Registry Key Security and Access Rights article for more information about possible values.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires after a registry key's information is retrieved.

Syntax

// CBRegistryAfterQueryKeyEventArgs carries the CBRegistry AfterQueryKey event's parameters.
pub struct CBRegistryAfterQueryKeyEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn valid_fields(&self) -> i32
  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 name(&self) -> &String
  fn set_name(&self, value : String)
  fn set_name_ref(&self, value : &String)
  fn class_name(&self) -> &String
  fn set_class_name(&self, value : String)
  fn set_class_name_ref(&self, value : &String)
  fn sub_keys(&self) -> i32
  fn set_sub_keys(&self, value : i32)
  fn max_name_length(&self) -> i32
  fn set_max_name_length(&self, value : i32)
  fn max_class_name_length(&self) -> i32
  fn set_max_class_name_length(&self, value : i32)
  fn values(&self) -> i32
  fn set_values(&self, value : i32)
  fn max_value_name_length(&self) -> i32
  fn set_max_value_name_length(&self, value : i32)
  fn max_value_data_size(&self) -> i32
  fn set_max_value_data_size(&self, value : i32)
  fn virtualization_candidate(&self) -> bool
  fn set_virtualization_candidate(&self, value : bool)
  fn virtualization_enabled(&self) -> bool
  fn set_virtualization_enabled(&self, value : bool)
  fn virtual_target(&self) -> bool
  fn set_virtual_target(&self, value : bool)
  fn virtual_store(&self) -> bool
  fn set_virtual_store(&self, value : bool)
  fn virtual_source(&self) -> bool
  fn set_virtual_source(&self, value : bool)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterQueryKeyEvent defines the signature of the CBRegistry AfterQueryKey event's handler function.
pub trait CBRegistryAfterQueryKeyEvent {
  fn on_after_query_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterQueryKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_query_key(&self) -> &'a dyn CBRegistryAfterQueryKeyEvent;
  pub fn set_on_after_query_key(&mut self, value : &'a dyn CBRegistryAfterQueryKeyEvent);
  ...
}

Remarks

This event fires after a registry key's information is retrieved.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The ValidFields parameter indicates which pieces of information about the key were retrieved. The value of this parameter is a combination of one or more of the following:

The LastWriteTime parameter specifies when the key was last changed, specified .

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters.

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters.

The SubKeys parameter specifies the number of subkeys that the key has.

The MaxNameLength parameter specifies the length, in bytes, of the key's longest subkey name.

The MaxClassNameLength parameter specifies the length, in bytes, of the key's longest subkey class name.

The Values parameter specifies the number of values the key has.

The MaxValueNameLength parameter specifies the length, in bytes, of the key's longest value name.

The MaxValueDataSize parameter specifies the length, in bytes, of the subkey's largest value data size.

The VirtualizationCandidate parameter specifies whether the key is part of the virtualization namespace scope.

The VirtualizationEnabled parameter specifies whether virtualization is enabled on the key. This parameter can only be true if VirtualizationCandidate is true.

The VirtualTarget parameter specifies whether the key is a virtual key. This parameter can only be true if both VirtualizationCandidate and VirtualizationEnabled are both false. Its value is only valid on virtual store key handles.

The VirtualStore parameter specifies whether the key is part of the virtual store path.

The VirtualSource parameter specifies whether the key has ever been virtualized. This parameter can only be true if VirtualizationCandidate is true.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_value Event (CBRegistry Struct)

This event fires after a registry value's information is retrieved.

Syntax

// CBRegistryAfterQueryValueEventArgs carries the CBRegistry AfterQueryValue event's parameters.
pub struct CBRegistryAfterQueryValueEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn value_name(&self) -> &String
  fn valid_fields(&self) -> i32
  fn value_type(&self) -> i32
  fn set_value_type(&self, value : i32)
  fn integer_value(&self) -> i64
  fn set_integer_value(&self, value : i64)
  fn string_value(&self) -> &String
  fn set_string_value(&self, value : String)
  fn set_string_value_ref(&self, value : &String)
  fn binary_value(&self) -> *mut u8
  fn max_binary_value_size(&self) -> i32
  fn binary_value_size(&self) -> i32
  fn set_binary_value_size(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterQueryValueEvent defines the signature of the CBRegistry AfterQueryValue event's handler function.
pub trait CBRegistryAfterQueryValueEvent {
  fn on_after_query_value(&self, sender : CBRegistry, e : &mut CBRegistryAfterQueryValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_query_value(&self) -> &'a dyn CBRegistryAfterQueryValueEvent;
  pub fn set_on_after_query_value(&mut self, value : &'a dyn CBRegistryAfterQueryValueEvent);
  ...
}

Remarks

This event fires after a registry value's information is retrieved.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The ValueName parameter reflects the name of the registry value.

The ValidFields parameter indicates which pieces of information about the registry value were retrieved. The value of this parameter is a combination of one or more of the following:

The ValueType parameter specifies the registry value's type and determines which of the other parameters holds the registry value's data (please refer to their descriptions for more information). Possible values are as follows:

The IntegerValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_DWORD or REG_VALUETYPE_QWORD.

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ.

For REG_VALUETYPE_MULTI_SZ, data are formatted as multiple individual ETB-terminated strings concatenated together into a single null-terminated string (where ETB is the End-of-Transmission-Block character; 23/0x17). For example, the strings This is, a multistring, and value. would be encoded as This is[ETB]a multistring[ETB]value.[ETB][NUL].

Note: As Microsoft's Registry Value Types article describes, the native multistring data format uses null terminators for the individual strings (e.g., This is[NUL]a multistring[NUL]value.[NUL][NUL]); CBRegistry converts the individual null terminators to/from ETB characters internally for applications' convenience.

The BinaryValue parameter points to a memory buffer that holds the registry value's data if ValueType is REG_VALUETYPE_BINARY. The MaxBinaryValueSize and BinaryValueSize parameter specify the capacity of the BinaryValue buffer and the length of the data it contains, respectively, in bytes.

Always check MaxBinaryValueSize before copying any data into the BinaryValue buffer. If the buffer is large enough to hold all of the data, copy the data into it, and then update BinaryValueSize accordingly. If the buffer is not large enough, do not copy any data into it; instead, set BinaryValueSize to the required buffer size (i.e., the size of the data) and return the ERROR_MORE_DATA (234) error code via ResultCode.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires after a registry key is renamed.

Syntax

// CBRegistryAfterRenameKeyEventArgs carries the CBRegistry AfterRenameKey event's parameters.
pub struct CBRegistryAfterRenameKeyEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterRenameKeyEvent defines the signature of the CBRegistry AfterRenameKey event's handler function.
pub trait CBRegistryAfterRenameKeyEvent {
  fn on_after_rename_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterRenameKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_rename_key(&self) -> &'a dyn CBRegistryAfterRenameKeyEvent;
  pub fn set_on_after_rename_key(&mut self, value : &'a dyn CBRegistryAfterRenameKeyEvent);
  ...
}

Remarks

This event fires after a registry key is renamed.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's old or new names for performance reasons; applications that need them should store them in KeyContext during the on_before_create_key/on_before_open_key and on_before_rename_key events so that they can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires after a registry key's information is updated.

Syntax

// CBRegistryAfterSetKeyEventArgs carries the CBRegistry AfterSetKey event's parameters.
pub struct CBRegistryAfterSetKeyEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterSetKeyEvent defines the signature of the CBRegistry AfterSetKey event's handler function.
pub trait CBRegistryAfterSetKeyEvent {
  fn on_after_set_key(&self, sender : CBRegistry, e : &mut CBRegistryAfterSetKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_set_key(&self) -> &'a dyn CBRegistryAfterSetKeyEvent;
  pub fn set_on_after_set_key(&mut self, value : &'a dyn CBRegistryAfterSetKeyEvent);
  ...
}

Remarks

This event fires after a registry key's information is updated.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key_security Event (CBRegistry Struct)

This event fires after a registry key's security attributes are changed.

Syntax

// CBRegistryAfterSetKeySecurityEventArgs carries the CBRegistry AfterSetKeySecurity event's parameters.
pub struct CBRegistryAfterSetKeySecurityEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterSetKeySecurityEvent defines the signature of the CBRegistry AfterSetKeySecurity event's handler function.
pub trait CBRegistryAfterSetKeySecurityEvent {
  fn on_after_set_key_security(&self, sender : CBRegistry, e : &mut CBRegistryAfterSetKeySecurityEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_set_key_security(&self) -> &'a dyn CBRegistryAfterSetKeySecurityEvent;
  pub fn set_on_after_set_key_security(&mut self, value : &'a dyn CBRegistryAfterSetKeySecurityEvent);
  ...
}

Remarks

This event fires after security attributes are changed for the registry key specified by KeyContext.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

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 Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_value Event (CBRegistry Struct)

This event fires after a registry value is set or updated.

Syntax

// CBRegistryAfterSetValueEventArgs carries the CBRegistry AfterSetValue event's parameters.
pub struct CBRegistryAfterSetValueEventArgs {
  fn key_context(&self) -> usize
  fn status(&self) -> i32
  fn set_status(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryAfterSetValueEvent defines the signature of the CBRegistry AfterSetValue event's handler function.
pub trait CBRegistryAfterSetValueEvent {
  fn on_after_set_value(&self, sender : CBRegistry, e : &mut CBRegistryAfterSetValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_after_set_value(&self) -> &'a dyn CBRegistryAfterSetValueEvent;
  pub fn set_on_after_set_value(&mut self, value : &'a dyn CBRegistryAfterSetValueEvent);
  ...
}

Remarks

This event fires after a registry value is set or updated.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires. A similar strategy can be applied if the application needs the registry value's name, which can be stored in KeyContext during the corresponding Before* event.

The Status parameter contains a Win32 error code that indicates the outcome of the operation; 0 indicates success. This value is returned to the request originator if no other status is returned from this event. Applications may change this parameter's value if they want a different Win32 error code to be returned.

The Processed parameter indicates whether the response values have been modified. Applications must set this parameter to true if they have altered any of the parameters related to the response values.

Note: This parameter's value is ignored if an error is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires before a registry key is closed.

Syntax

// CBRegistryBeforeCloseKeyEventArgs carries the CBRegistry BeforeCloseKey event's parameters.
pub struct CBRegistryBeforeCloseKeyEventArgs {
  fn key_context(&self) -> usize
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeCloseKeyEvent defines the signature of the CBRegistry BeforeCloseKey event's handler function.
pub trait CBRegistryBeforeCloseKeyEvent {
  fn on_before_close_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeCloseKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_close_key(&self) -> &'a dyn CBRegistryBeforeCloseKeyEvent;
  pub fn set_on_before_close_key(&mut self, value : &'a dyn CBRegistryBeforeCloseKeyEvent);
  ...
}

Remarks

This event fires before a registry key is closed.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires before a registry key is created.

Syntax

// CBRegistryBeforeCreateKeyEventArgs carries the CBRegistry BeforeCreateKey event's parameters.
pub struct CBRegistryBeforeCreateKeyEventArgs {
  fn full_name(&self) -> &String
  fn desired_access(&self) -> i32
  fn key_handle(&self) -> i64
  fn set_key_handle(&self, value : i64)
  fn key_handle_context(&self) -> usize
  fn set_key_handle_context(&self, value : usize)
  fn granted_access(&self) -> i64
  fn set_granted_access(&self, value : i64)
  fn key_context(&self) -> usize
  fn set_key_context(&self, value : usize)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeCreateKeyEvent defines the signature of the CBRegistry BeforeCreateKey event's handler function.
pub trait CBRegistryBeforeCreateKeyEvent {
  fn on_before_create_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeCreateKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_create_key(&self) -> &'a dyn CBRegistryBeforeCreateKeyEvent;
  pub fn set_on_before_create_key(&mut self, value : &'a dyn CBRegistryBeforeCreateKeyEvent);
  ...
}

Remarks

This event fires before a registry key is created.

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

The FullName parameter reflects the "full" name of the registry key being created, specified, by default, in system format (e.g., HKEY_LOCAL_MACHINE\System\... will be \Registry\Machine\System\...). If the ResolveNtNameToWin32Name configuration setting is enabled, the name will be converted to the more common Win32 format. Applications that intend to use the registry key's name during later events should store it in KeyContext during this event. Please refer to the Contexts topic for more information.

The DesiredAccess parameter reflects the access rights specified by the requestor. Please refer to Microsoft's Registry Key Security and Access Rights article for more information about possible values.

The KeyHandle parameter specifies a handle to a registry key that should be opened instead of the one this event fired for. Applications can set this parameter to redirect access to the registry key associated with the specified handle.

The KeyHandleContext parameter is a placeholder for application-defined data associated with the application-provided registry key handle. Please refer to the Contexts topic for more information.

The GrantedAccess parameter specifies the granted access rights for an application-provided registry key handle. Applications that set KeyHandle must also set this parameter. Please refer to Microsoft's Registry Key Security and Access Rights article for more information about possible values.

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires before a registry key is deleted.

Syntax

// CBRegistryBeforeDeleteKeyEventArgs carries the CBRegistry BeforeDeleteKey event's parameters.
pub struct CBRegistryBeforeDeleteKeyEventArgs {
  fn key_context(&self) -> usize
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeDeleteKeyEvent defines the signature of the CBRegistry BeforeDeleteKey event's handler function.
pub trait CBRegistryBeforeDeleteKeyEvent {
  fn on_before_delete_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeDeleteKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_delete_key(&self) -> &'a dyn CBRegistryBeforeDeleteKeyEvent;
  pub fn set_on_before_delete_key(&mut self, value : &'a dyn CBRegistryBeforeDeleteKeyEvent);
  ...
}

Remarks

This event fires before a registry key is deleted.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_value Event (CBRegistry Struct)

This event fires before a registry value is deleted.

Syntax

// CBRegistryBeforeDeleteValueEventArgs carries the CBRegistry BeforeDeleteValue event's parameters.
pub struct CBRegistryBeforeDeleteValueEventArgs {
  fn key_context(&self) -> usize
  fn value_name(&self) -> &String
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeDeleteValueEvent defines the signature of the CBRegistry BeforeDeleteValue event's handler function.
pub trait CBRegistryBeforeDeleteValueEvent {
  fn on_before_delete_value(&self, sender : CBRegistry, e : &mut CBRegistryBeforeDeleteValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_delete_value(&self) -> &'a dyn CBRegistryBeforeDeleteValueEvent;
  pub fn set_on_before_delete_value(&mut self, value : &'a dyn CBRegistryBeforeDeleteValueEvent);
  ...
}

Remarks

This event fires before a registry value is deleted.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The ValueName parameter reflects the name of the registry value. Applications that intend to use the registry value's name during later events should store it in KeyContext during this event. Please refer to the Contexts topic for more information.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires before a subkey's information is retrieved during key enumeration.

Syntax

// CBRegistryBeforeEnumerateKeyEventArgs carries the CBRegistry BeforeEnumerateKey event's parameters.
pub struct CBRegistryBeforeEnumerateKeyEventArgs {
  fn key_context(&self) -> usize
  fn index(&self) -> i32
  fn requested_fields(&self) -> i32
  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 name(&self) -> &String
  fn set_name(&self, value : String)
  fn set_name_ref(&self, value : &String)
  fn class_name(&self) -> &String
  fn set_class_name(&self, value : String)
  fn set_class_name_ref(&self, value : &String)
  fn sub_keys(&self) -> i32
  fn set_sub_keys(&self, value : i32)
  fn max_name_length(&self) -> i32
  fn set_max_name_length(&self, value : i32)
  fn max_class_name_length(&self) -> i32
  fn set_max_class_name_length(&self, value : i32)
  fn values(&self) -> i32
  fn set_values(&self, value : i32)
  fn max_value_name_length(&self) -> i32
  fn set_max_value_name_length(&self, value : i32)
  fn max_value_data_size(&self) -> i32
  fn set_max_value_data_size(&self, value : i32)
  fn virtualization_candidate(&self) -> bool
  fn set_virtualization_candidate(&self, value : bool)
  fn virtualization_enabled(&self) -> bool
  fn set_virtualization_enabled(&self, value : bool)
  fn virtual_target(&self) -> bool
  fn set_virtual_target(&self, value : bool)
  fn virtual_store(&self) -> bool
  fn set_virtual_store(&self, value : bool)
  fn virtual_source(&self) -> bool
  fn set_virtual_source(&self, value : bool)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeEnumerateKeyEvent defines the signature of the CBRegistry BeforeEnumerateKey event's handler function.
pub trait CBRegistryBeforeEnumerateKeyEvent {
  fn on_before_enumerate_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeEnumerateKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_enumerate_key(&self) -> &'a dyn CBRegistryBeforeEnumerateKeyEvent;
  pub fn set_on_before_enumerate_key(&mut self, value : &'a dyn CBRegistryBeforeEnumerateKeyEvent);
  ...
}

Remarks

This event fires before a subkey's information is retrieved during enumeration of a registry key's subkeys.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Index parameter reflects the zero-based index of the key (within the registry key being enumerated).

The RequestedFields parameter indicates which pieces of information about the key were requested. The value of this parameter is a combination of one or more of the following:

The LastWriteTime parameter specifies when the key was last changed, specified .

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters.

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters.

The SubKeys parameter specifies the number of subkeys that the key has.

The MaxNameLength parameter specifies the length, in bytes, of the key's longest subkey name.

The MaxClassNameLength parameter specifies the length, in bytes, of the key's longest subkey class name.

The Values parameter specifies the number of values the key has.

The MaxValueNameLength parameter specifies the length, in bytes, of the key's longest value name.

The MaxValueDataSize parameter specifies the length, in bytes, of the subkey's largest value data size.

The VirtualizationCandidate parameter specifies whether the key is part of the virtualization namespace scope.

The VirtualizationEnabled parameter specifies whether virtualization is enabled on the key. This parameter can only be true if VirtualizationCandidate is true.

The VirtualTarget parameter specifies whether the key is a virtual key. This parameter can only be true if both VirtualizationCandidate and VirtualizationEnabled are both false. Its value is only valid on virtual store key handles.

The VirtualStore parameter specifies whether the key is part of the virtual store path.

The VirtualSource parameter specifies whether the key has ever been virtualized. This parameter can only be true if VirtualizationCandidate is true.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_value Event (CBRegistry Struct)

This event fires before a registry value's information is retrieved during key value enumeration.

Syntax

// CBRegistryBeforeEnumerateValueEventArgs carries the CBRegistry BeforeEnumerateValue event's parameters.
pub struct CBRegistryBeforeEnumerateValueEventArgs {
  fn key_context(&self) -> usize
  fn index(&self) -> i32
  fn requested_fields(&self) -> i32
  fn value_name(&self) -> &String
  fn set_value_name(&self, value : String)
  fn set_value_name_ref(&self, value : &String)
  fn value_type(&self) -> i32
  fn set_value_type(&self, value : i32)
  fn integer_value(&self) -> i64
  fn set_integer_value(&self, value : i64)
  fn string_value(&self) -> &String
  fn set_string_value(&self, value : String)
  fn set_string_value_ref(&self, value : &String)
  fn binary_value(&self) -> *mut u8
  fn max_binary_value_size(&self) -> i32
  fn binary_value_size(&self) -> i32
  fn set_binary_value_size(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeEnumerateValueEvent defines the signature of the CBRegistry BeforeEnumerateValue event's handler function.
pub trait CBRegistryBeforeEnumerateValueEvent {
  fn on_before_enumerate_value(&self, sender : CBRegistry, e : &mut CBRegistryBeforeEnumerateValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_enumerate_value(&self) -> &'a dyn CBRegistryBeforeEnumerateValueEvent;
  pub fn set_on_before_enumerate_value(&mut self, value : &'a dyn CBRegistryBeforeEnumerateValueEvent);
  ...
}

Remarks

This event fires before a registry value's information is retrieved during enumeration of a registry key's values.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The Index parameter reflects the zero-based index of the registry value (within the registry key being enumerated).

The RequestedFields parameter indicates which pieces of information about the registry value were requested. The value of this parameter is a combination of one or more of the following:

The ValueName parameter specifies the registry value's name.

The ValueType parameter specifies the registry value's type and determines which of the other parameters holds the registry value's data (please refer to their descriptions for more information). Possible values are as follows:

The IntegerValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_DWORD or REG_VALUETYPE_QWORD.

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ.

For REG_VALUETYPE_MULTI_SZ, data are formatted as multiple individual ETB-terminated strings concatenated together into a single null-terminated string (where ETB is the End-of-Transmission-Block character; 23/0x17). For example, the strings This is, a multistring, and value. would be encoded as This is[ETB]a multistring[ETB]value.[ETB][NUL].

Note: As Microsoft's Registry Value Types article describes, the native multistring data format uses null terminators for the individual strings (e.g., This is[NUL]a multistring[NUL]value.[NUL][NUL]); CBRegistry converts the individual null terminators to/from ETB characters internally for applications' convenience.

The BinaryValue parameter points to a memory buffer that holds the registry value's data if ValueType is REG_VALUETYPE_BINARY. The MaxBinaryValueSize and BinaryValueSize parameter specify the capacity of the BinaryValue buffer and the length of the data it contains, respectively, in bytes.

Always check MaxBinaryValueSize before copying any data into the BinaryValue buffer. If the buffer is large enough to hold all of the data, copy the data into it, and then update BinaryValueSize accordingly. If the buffer is not large enough, do not copy any data into it; instead, set BinaryValueSize to the required buffer size (i.e., the size of the data) and return the ERROR_MORE_DATA (234) error code via ResultCode.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key_security Event (CBRegistry Struct)

This event fires before a registry key's security attributes are retrieved.

Syntax

// CBRegistryBeforeGetKeySecurityEventArgs carries the CBRegistry BeforeGetKeySecurity event's parameters.
pub struct CBRegistryBeforeGetKeySecurityEventArgs {
  fn key_context(&self) -> usize
  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 processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeGetKeySecurityEvent defines the signature of the CBRegistry BeforeGetKeySecurity event's handler function.
pub trait CBRegistryBeforeGetKeySecurityEvent {
  fn on_before_get_key_security(&self, sender : CBRegistry, e : &mut CBRegistryBeforeGetKeySecurityEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_get_key_security(&self) -> &'a dyn CBRegistryBeforeGetKeySecurityEvent;
  pub fn set_on_before_get_key_security(&mut self, value : &'a dyn CBRegistryBeforeGetKeySecurityEvent);
  ...
}

Remarks

This event fires before security attributes are retrieved for the registry key specified by KeyContext.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

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 Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

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_key Event (CBRegistry Struct)

This event fires before a registry key is opened.

Syntax

// CBRegistryBeforeOpenKeyEventArgs carries the CBRegistry BeforeOpenKey event's parameters.
pub struct CBRegistryBeforeOpenKeyEventArgs {
  fn full_name(&self) -> &String
  fn desired_access(&self) -> i32
  fn key_handle(&self) -> i64
  fn set_key_handle(&self, value : i64)
  fn key_handle_context(&self) -> usize
  fn set_key_handle_context(&self, value : usize)
  fn granted_access(&self) -> i32
  fn set_granted_access(&self, value : i32)
  fn key_context(&self) -> usize
  fn set_key_context(&self, value : usize)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeOpenKeyEvent defines the signature of the CBRegistry BeforeOpenKey event's handler function.
pub trait CBRegistryBeforeOpenKeyEvent {
  fn on_before_open_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeOpenKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_open_key(&self) -> &'a dyn CBRegistryBeforeOpenKeyEvent;
  pub fn set_on_before_open_key(&mut self, value : &'a dyn CBRegistryBeforeOpenKeyEvent);
  ...
}

Remarks

This event fires before a registry key is opened.

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

The FullName parameter reflects the "full" name of the registry key being opened, specified, by default, in system format (e.g., HKEY_LOCAL_MACHINE\System\... will be \Registry\Machine\System\...). If the ResolveNtNameToWin32Name configuration setting is enabled, the name will be converted to the more common Win32 format. Applications that intend to use the registry key's name during later events should store it in KeyContext during this event. Please refer to the Contexts topic for more information.

The DesiredAccess parameter reflects the access rights specified by the requestor. Please refer to Microsoft's Registry Key Security and Access Rights article for more information about possible values.

The KeyHandle parameter specifies a handle to a registry key that should be opened instead of the one this event fired for. Applications can set this parameter to redirect access to the registry key associated with the specified handle.

The KeyHandleContext parameter is a placeholder for application-defined data associated with the application-provided registry key handle. Please refer to the Contexts topic for more information.

The GrantedAccess parameter specifies the granted access rights for an application-provided registry key handle. Applications that set KeyHandle must also set this parameter. Please refer to Microsoft's Registry Key Security and Access Rights article for more information about possible values.

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires before a registry key's information is retrieved.

Syntax

// CBRegistryBeforeQueryKeyEventArgs carries the CBRegistry BeforeQueryKey event's parameters.
pub struct CBRegistryBeforeQueryKeyEventArgs {
  fn key_context(&self) -> usize
  fn requested_fields(&self) -> i32
  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 name(&self) -> &String
  fn set_name(&self, value : String)
  fn set_name_ref(&self, value : &String)
  fn class_name(&self) -> &String
  fn set_class_name(&self, value : String)
  fn set_class_name_ref(&self, value : &String)
  fn sub_keys(&self) -> i32
  fn set_sub_keys(&self, value : i32)
  fn max_name_length(&self) -> i32
  fn set_max_name_length(&self, value : i32)
  fn max_class_name_length(&self) -> i32
  fn set_max_class_name_length(&self, value : i32)
  fn values(&self) -> i32
  fn set_values(&self, value : i32)
  fn max_value_name_length(&self) -> i32
  fn set_max_value_name_length(&self, value : i32)
  fn max_value_data_size(&self) -> i32
  fn set_max_value_data_size(&self, value : i32)
  fn virtualization_candidate(&self) -> bool
  fn set_virtualization_candidate(&self, value : bool)
  fn virtualization_enabled(&self) -> bool
  fn set_virtualization_enabled(&self, value : bool)
  fn virtual_target(&self) -> bool
  fn set_virtual_target(&self, value : bool)
  fn virtual_store(&self) -> bool
  fn set_virtual_store(&self, value : bool)
  fn virtual_source(&self) -> bool
  fn set_virtual_source(&self, value : bool)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeQueryKeyEvent defines the signature of the CBRegistry BeforeQueryKey event's handler function.
pub trait CBRegistryBeforeQueryKeyEvent {
  fn on_before_query_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeQueryKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_query_key(&self) -> &'a dyn CBRegistryBeforeQueryKeyEvent;
  pub fn set_on_before_query_key(&mut self, value : &'a dyn CBRegistryBeforeQueryKeyEvent);
  ...
}

Remarks

This event fires before a registry key's information is retrieved.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The RequestedFields parameter indicates which pieces of information about the key were requested. The value of this parameter is a combination of one or more of the following:

The LastWriteTime parameter specifies when the key was last changed, specified .

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters.

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters.

The SubKeys parameter specifies the number of subkeys that the key has.

The MaxNameLength parameter specifies the length, in bytes, of the key's longest subkey name.

The MaxClassNameLength parameter specifies the length, in bytes, of the key's longest subkey class name.

The Values parameter specifies the number of values the key has.

The MaxValueNameLength parameter specifies the length, in bytes, of the key's longest value name.

The MaxValueDataSize parameter specifies the length, in bytes, of the subkey's largest value data size.

The VirtualizationCandidate parameter specifies whether the key is part of the virtualization namespace scope.

The VirtualizationEnabled parameter specifies whether virtualization is enabled on the key. This parameter can only be true if VirtualizationCandidate is true.

The VirtualTarget parameter specifies whether the key is a virtual key. This parameter can only be true if both VirtualizationCandidate and VirtualizationEnabled are both false. Its value is only valid on virtual store key handles.

The VirtualStore parameter specifies whether the key is part of the virtual store path.

The VirtualSource parameter specifies whether the key has ever been virtualized. This parameter can only be true if VirtualizationCandidate is true.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_value Event (CBRegistry Struct)

This event fires before a registry value's information is retrieved.

Syntax

// CBRegistryBeforeQueryValueEventArgs carries the CBRegistry BeforeQueryValue event's parameters.
pub struct CBRegistryBeforeQueryValueEventArgs {
  fn key_context(&self) -> usize
  fn value_name(&self) -> &String
  fn requested_fields(&self) -> i32
  fn value_type(&self) -> i32
  fn set_value_type(&self, value : i32)
  fn integer_value(&self) -> i64
  fn set_integer_value(&self, value : i64)
  fn string_value(&self) -> &String
  fn set_string_value(&self, value : String)
  fn set_string_value_ref(&self, value : &String)
  fn binary_value(&self) -> *mut u8
  fn max_binary_value_size(&self) -> i32
  fn binary_value_size(&self) -> i32
  fn set_binary_value_size(&self, value : i32)
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeQueryValueEvent defines the signature of the CBRegistry BeforeQueryValue event's handler function.
pub trait CBRegistryBeforeQueryValueEvent {
  fn on_before_query_value(&self, sender : CBRegistry, e : &mut CBRegistryBeforeQueryValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_query_value(&self) -> &'a dyn CBRegistryBeforeQueryValueEvent;
  pub fn set_on_before_query_value(&mut self, value : &'a dyn CBRegistryBeforeQueryValueEvent);
  ...
}

Remarks

This event fires before a registry value's information is retrieved.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The ValueName parameter reflects the name of the registry value.

The RequestedFields parameter indicates which pieces of information about the registry value were requested. The value of this parameter is a combination of one or more of the following:

The ValueType parameter specifies the registry value's type and determines which of the other parameters holds the registry value's data (please refer to their descriptions for more information). Possible values are as follows:

The IntegerValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_DWORD or REG_VALUETYPE_QWORD.

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ.

For REG_VALUETYPE_MULTI_SZ, data are formatted as multiple individual ETB-terminated strings concatenated together into a single null-terminated string (where ETB is the End-of-Transmission-Block character; 23/0x17). For example, the strings This is, a multistring, and value. would be encoded as This is[ETB]a multistring[ETB]value.[ETB][NUL].

Note: As Microsoft's Registry Value Types article describes, the native multistring data format uses null terminators for the individual strings (e.g., This is[NUL]a multistring[NUL]value.[NUL][NUL]); CBRegistry converts the individual null terminators to/from ETB characters internally for applications' convenience.

The BinaryValue parameter points to a memory buffer that holds the registry value's data if ValueType is REG_VALUETYPE_BINARY. The MaxBinaryValueSize and BinaryValueSize parameter specify the capacity of the BinaryValue buffer and the length of the data it contains, respectively, in bytes.

Always check MaxBinaryValueSize before copying any data into the BinaryValue buffer. If the buffer is large enough to hold all of the data, copy the data into it, and then update BinaryValueSize accordingly. If the buffer is not large enough, do not copy any data into it; instead, set BinaryValueSize to the required buffer size (i.e., the size of the data) and return the ERROR_MORE_DATA (234) error code via ResultCode.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires before a registry key is renamed.

Syntax

// CBRegistryBeforeRenameKeyEventArgs carries the CBRegistry BeforeRenameKey event's parameters.
pub struct CBRegistryBeforeRenameKeyEventArgs {
  fn key_context(&self) -> usize
  fn new_name(&self) -> &String
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeRenameKeyEvent defines the signature of the CBRegistry BeforeRenameKey event's handler function.
pub trait CBRegistryBeforeRenameKeyEvent {
  fn on_before_rename_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeRenameKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_rename_key(&self) -> &'a dyn CBRegistryBeforeRenameKeyEvent;
  pub fn set_on_before_rename_key(&mut self, value : &'a dyn CBRegistryBeforeRenameKeyEvent);
  ...
}

Remarks

This event fires before a registry key is renamed.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The NewName parameter reflects the new name of the registry key. Applications that intend to use the new name during later events should store it in KeyContext during this event; please refer to the Contexts topic for more information.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key Event (CBRegistry Struct)

This event fires before a registry key's information is updated.

Syntax

// CBRegistryBeforeSetKeyEventArgs carries the CBRegistry BeforeSetKey event's parameters.
pub struct CBRegistryBeforeSetKeyEventArgs {
  fn key_context(&self) -> usize
  fn last_write_time(&self) -> &chrono::DateTime<Utc>
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeSetKeyEvent defines the signature of the CBRegistry BeforeSetKey event's handler function.
pub trait CBRegistryBeforeSetKeyEvent {
  fn on_before_set_key(&self, sender : CBRegistry, e : &mut CBRegistryBeforeSetKeyEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_set_key(&self) -> &'a dyn CBRegistryBeforeSetKeyEvent;
  pub fn set_on_before_set_key(&mut self, value : &'a dyn CBRegistryBeforeSetKeyEvent);
  ...
}

Remarks

This event fires before a registry key's information is updated.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The LastWriteTime parameter reflects when the key was last changed, specified .

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_key_security Event (CBRegistry Struct)

This event fires before a registry key's security attributes are changed.

Syntax

// CBRegistryBeforeSetKeySecurityEventArgs carries the CBRegistry BeforeSetKeySecurity event's parameters.
pub struct CBRegistryBeforeSetKeySecurityEventArgs {
  fn key_context(&self) -> usize
  fn security_information(&self) -> i32
  fn security_descriptor(&self) -> *mut u8
  fn length(&self) -> i32
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeSetKeySecurityEvent defines the signature of the CBRegistry BeforeSetKeySecurity event's handler function.
pub trait CBRegistryBeforeSetKeySecurityEvent {
  fn on_before_set_key_security(&self, sender : CBRegistry, e : &mut CBRegistryBeforeSetKeySecurityEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_set_key_security(&self) -> &'a dyn CBRegistryBeforeSetKeySecurityEvent;
  pub fn set_on_before_set_key_security(&mut self, value : &'a dyn CBRegistryBeforeSetKeySecurityEvent);
  ...
}

Remarks

This event fires before security attributes are changed for the registry key specified by KeyContext.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

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

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 Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

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_value Event (CBRegistry Struct)

This event fires before a registry value is set or updated.

Syntax

// CBRegistryBeforeSetValueEventArgs carries the CBRegistry BeforeSetValue event's parameters.
pub struct CBRegistryBeforeSetValueEventArgs {
  fn key_context(&self) -> usize
  fn value_name(&self) -> &String
  fn value_type(&self) -> i32
  fn integer_value(&self) -> i64
  fn string_value(&self) -> &String
  fn binary_value(&self) -> *mut u8
  fn binary_value_size(&self) -> i32
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn fire_after_event(&self) -> bool
  fn set_fire_after_event(&self, value : bool)
  fn stop_filtering(&self) -> bool
  fn set_stop_filtering(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryBeforeSetValueEvent defines the signature of the CBRegistry BeforeSetValue event's handler function.
pub trait CBRegistryBeforeSetValueEvent {
  fn on_before_set_value(&self, sender : CBRegistry, e : &mut CBRegistryBeforeSetValueEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_before_set_value(&self) -> &'a dyn CBRegistryBeforeSetValueEvent;
  pub fn set_on_before_set_value(&mut self, value : &'a dyn CBRegistryBeforeSetValueEvent);
  ...
}

Remarks

This event fires before a registry value is set or updated.

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

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

Note: This event does not expose the registry key's name for performance reasons; applications that need it should store it in KeyContext during the on_before_create_key/on_before_open_key event so that it can be retrieved when this event fires.

The ValueName parameter reflects the name of the registry value. Applications that intend to use the registry value's name during later events should store it in KeyContext during this event. Please refer to the Contexts topic for more information.

The ValueType parameter reflects the registry value's type and determines which of the other parameters holds the registry value's data; please refer to their descriptions for more information. Possible values are as follows:

The IntegerValue parameter reflects the registry value's data if ValueType is REG_VALUETYPE_DWORD or REG_VALUETYPE_QWORD.

The StringValue parameter reflects the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ.

For REG_VALUETYPE_MULTI_SZ, data are formatted as multiple individual ETB-terminated strings concatenated together into a single null-terminated string (where ETB is the End-of-Transmission-Block character; 23/0x17). For example, the strings This is, a multistring, and value. would be encoded as This is[ETB]a multistring[ETB]value.[ETB][NUL].

Note: As Microsoft's Registry Value Types article describes, the native multistring data format uses null terminators for the individual strings (e.g., This is[NUL]a multistring[NUL]value.[NUL][NUL]); CBRegistry converts the individual null terminators to/from ETB characters internally for applications' convenience.

The BinaryValue parameter points to a memory buffer that holds the registry value's data if ValueType is REG_VALUETYPE_BINARY. The BinaryValueSize parameter reflects the length of the data, in bytes.

The Processed parameter indicates whether the underlying request has been handled successfully. Applications should set this parameter to true if they have handled the request themselves (this will prevent the corresponding After* event from being called).

Note: This parameter's value is ignored if an error is returned via ResultCode.

The FireAfterEvent parameter specifies whether the corresponding After* event should be fired; it is true by default.

Note: Regardless of how this parameter is set, the corresponding After* event will not fire if Processed is true, or if an error code is returned via ResultCode.

The StopFiltering parameter specifies whether the struct's system driver should ignore all further operations for the registry key; it is false by default. Applications may set this parameter to true to prevent any further events from firing for the registry key.

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_cleanup_key_context Event (CBRegistry Struct)

This event fires when the application-defined data stored in a registry key context need to be cleaned up.

Syntax

// CBRegistryCleanupKeyContextEventArgs carries the CBRegistry CleanupKeyContext event's parameters.
pub struct CBRegistryCleanupKeyContextEventArgs {
  fn key_context(&self) -> usize
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryCleanupKeyContextEvent defines the signature of the CBRegistry CleanupKeyContext event's handler function.
pub trait CBRegistryCleanupKeyContextEvent {
  fn on_cleanup_key_context(&self, sender : CBRegistry, e : &mut CBRegistryCleanupKeyContextEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_cleanup_key_context(&self) -> &'a dyn CBRegistryCleanupKeyContextEvent;
  pub fn set_on_cleanup_key_context(&mut self, value : &'a dyn CBRegistryCleanupKeyContextEvent);
  ...
}

Remarks

This event fires when the specified KeyContext is about to be discarded, giving applications a chance to clean up any information stored in it. 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_close_key_handle Event (CBRegistry Struct)

This event fires when an application-provided registry key handle should be closed.

Syntax

// CBRegistryCloseKeyHandleEventArgs carries the CBRegistry CloseKeyHandle event's parameters.
pub struct CBRegistryCloseKeyHandleEventArgs {
  fn key_context(&self) -> usize
  fn key_handle(&self) -> i64
  fn key_handle_context(&self) -> usize
  fn error(&self) -> i32
  fn processed(&self) -> bool
  fn set_processed(&self, value : bool)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBRegistryCloseKeyHandleEvent defines the signature of the CBRegistry CloseKeyHandle event's handler function.
pub trait CBRegistryCloseKeyHandleEvent {
  fn on_close_key_handle(&self, sender : CBRegistry, e : &mut CBRegistryCloseKeyHandleEventArgs);
}

impl <'a> CBRegistry<'a> {
  pub fn on_close_key_handle(&self) -> &'a dyn CBRegistryCloseKeyHandleEvent;
  pub fn set_on_close_key_handle(&mut self, value : &'a dyn CBRegistryCloseKeyHandleEvent);
  ...
}

Remarks

This event fires when the application-provided registry key handle, specified by KeyHandle, should be closed and the associated KeyHandleContext should be cleaned up.

The KeyContext parameter is a placeholder for application-defined data associated with the registry key. Please refer to the Contexts topic for more information.

The Error parameter reflects the error code of any error that occurred while using the application-provided key handle.

The Processed parameter indicates whether the application has processed the event and closed the key handle; it is false by default. If the application does not set this parameter to true, then the struct will close the KeyHandle with the Windows API's RegCloseKey function when the event handler returns (unless an error code is returned via ResultCode).

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

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

Syntax

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

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

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

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_worker_thread_creation Event (CBRegistry Struct)

Fires just after a new worker thread is created.

Syntax

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

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

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

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

Fires just before a worker thread is terminated.

Syntax

// CBRegistryWorkerThreadTerminationEventArgs carries the CBRegistry WorkerThreadTermination event's parameters.
pub struct CBRegistryWorkerThreadTerminationEventArgs {
}

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

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

Remarks

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

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

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

Any errors that occur during this event are ignored.

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

Config Settings (CBRegistry 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.

CBRegistry Config Settings

Base Config Settings

Trappable Errors (CBRegistry Struct)

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

Special Use Errors