Struct cbfsfilter::CBProcess

Properties   Methods   Events   Config Settings   Errors  

The CBProcess struct enables applications to intercept process manager requests.

Syntax

cbfsfilter::CBProcess

Remarks

The CBProcess struct gives applications the ability to monitor and (in some cases) control process- and thread-related requests. Because the CBProcess API is far less complex than other structs' APIs, it uses simple filter rules; please refer to the File and Registry Filter Rules topic for more information.

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 CBProcess struct. This must be done each time the application starts.
3. Add one or more filter rules using methods like add_filtered_process_by_id and add_filtered_process_by_name. (Rules also can be added or removed after the filter is started.)
4. Call the start_filter method to start filtering process manager requests.
5. When finished, call the stop_filter method to stop filtering process manager 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 CBProcess struct cannot be disposed of automatically. Please, call the dispose(&mut self) method of CBProcess 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 (CBProcess 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 (CBProcess Struct)

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

Syntax

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

Default Value

String::default()

Remarks

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

Microsoft's documentation is unclear about how altitudes should be chosen for process manager filter drivers; please refer to the Driver Altitudes topic for more information. The default value of this property is 400055 (which is not registered with Microsoft), but applications can likely choose any value they desire. If the specified altitude is already in use by another driver, the struct's driver will behave in the manner specified by the strict_altitude property.

Data Type

String

running_process_count Property (CBProcess Struct)

The number of records in the RunningProcess arrays.

Syntax

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

Default Value

0

Remarks

This property controls the size of the following arrays:

• running_process_command_line
• running_process_process_id
• running_process_process_name

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

This property is read-only.

Data Type

i32

running_process_command_line Property (CBProcess Struct)

This property reflects the command-line arguments of the process.

Syntax

fn running_process_command_line(&self , RunningProcessIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

Remarks

This property reflects the command-line arguments of the process.

This property reflects the command-line arguments, with which the process has been started.

By default, the driver does not store command-line arguments and this property is empty. To enable collection and retrieval of the command-line arguments, set the track_command_line property to true.

The RunningProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RunningProcessCount property.

This property is read-only.

Data Type

String

running_process_process_id Property (CBProcess Struct)

This property reflects the process Id (PID).

Syntax

fn running_process_process_id(&self , RunningProcessIndex : i32) -> Result<i32, CBFSFilterError> 

Default Value

0

Remarks

This property reflects the process Id (PID).

This property reflects the Id of the running process (i.e., the PID).

The RunningProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RunningProcessCount property.

This property is read-only.

Data Type

i32

running_process_process_name Property (CBProcess Struct)

This property reflects the name of the process.

Syntax

fn running_process_process_name(&self , RunningProcessIndex : i32) -> Result<String, CBFSFilterError> 

Default Value

String::default()

Remarks

This property reflects the name of the process.

This property reflects the name of the running process.

The RunningProcessIndex parameter specifies the index of the item in the array. The size of the array is controlled by the RunningProcessCount property.

This property is read-only.

Data Type

String

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

strict_altitude Property (CBProcess Struct)

This property specifies how to behave if the specified altitude is already in use.

Syntax

fn strict_altitude(&self ) -> Result<bool, CBFSFilterError> 
fn set_strict_altitude(&self, value : bool) ->  Option<CBFSFilterError> 

Default Value

false

Remarks

This property specifies how the struct's system driver should behave if the specified altitude is already in use when the start_filter method is called.

If this property is enabled, the filter will fail to attach. If this property is disabled (default), the driver will attempt to use an adjacent altitude value to attach the filter.

Data Type

bool

tag Property (CBProcess 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

track_command_line Property (CBProcess Struct)

This property specifies whether the driver should store information about processes' command-line arguments.

Syntax

fn track_command_line(&self ) -> Result<bool, CBFSFilterError> 
fn set_track_command_line(&self, value : bool) ->  Option<CBFSFilterError> 

Default Value

false

Remarks

This property specifies whether the struct should store command-line parameters for all processes that are running. Set this property to true if you want to receive command lines for each process during enumeration that is created with create_running_processes_snapshot.

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

Data Type

bool

add_filtered_process_by_id Method (CBProcess 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).

The ProcessId parameter specifies the PID of the process whose requests should be filtered. The value passed for this parameter must be either the PID of an existing process or -1, which means "all processes".

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

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_ignored_process_by_id Method (CBProcess 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).

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.

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 otherwise would 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 (CBProcess 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).

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 otherwise would 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.

close_running_processes_snapshot Method (CBProcess Struct)

This method closes the previously created snapshot of running processes.

Syntax

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

Remarks

This method closes the snapshot previously created by create_running_processes_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.

config Method (CBProcess 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_running_processes_snapshot Method (CBProcess Struct)

This method creates a snapshot of running processes.

Syntax

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

Remarks

This method creates a snapshot of information about processes that are running in the system. This information is then used to populate the RunningProcesses* properties.

When the application is finished working with the default rules snapshot, it must close it by calling the close_running_processes_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.

get_driver_status Method (CBProcess 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 (CBProcess 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_token Method (CBProcess 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 process and thread 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.

get_process_name Method (CBProcess Struct)

This method retrieves the name of the process associated with the specified process ID (PID).

Syntax

fn get_process_name(&self, process_id : i32) ->  Result<String, CBFSFilterError>

Remarks

This method retrieves the name of the process with the specified ProcessId (PID). If such a process currently exists, this method returns the fully qualified name of its executable; otherwise, it returns an empty string.

Note: The System process does not technically have a name; passing its PID to this method will cause empty string to be returned.

initialize Method (CBProcess 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 (CBProcess 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 (CBProcess 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.

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

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

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

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

This method starts the filtering process and thread operations.

Syntax

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

Remarks

This method attaches the filter, causing the struct's system driver to start the filtering process and thread 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.

EventsToFire

EventsToFire specifies the event types that must be fired by the struct. The setting should be set by ORing together zero or more flags. Possible values are as follows:

stop_filter Method (CBProcess Struct)

This method stops the filtering process and thread operations.

Syntax

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

Remarks

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

uninstall Method (CBProcess 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_error Event (CBProcess Struct)

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

Syntax

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

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

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

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_process_creation Event (CBProcess Struct)

This event fires when a process is being created.

Syntax

// CBProcessProcessCreationEventArgs carries the CBProcess ProcessCreation event's parameters.
pub struct CBProcessProcessCreationEventArgs {
  fn process_id(&self) -> i32
  fn parent_process_id(&self) -> i32
  fn creating_process_id(&self) -> i32
  fn creating_thread_id(&self) -> i32
  fn process_name(&self) -> &String
  fn image_file_name(&self) -> &String
  fn file_open_name_available(&self) -> bool
  fn command_line(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBProcessProcessCreationEvent defines the signature of the CBProcess ProcessCreation event's handler function.
pub trait CBProcessProcessCreationEvent {
  fn on_process_creation(&self, sender : CBProcess, e : &mut CBProcessProcessCreationEventArgs);
}

impl <'a> CBProcess<'a> {
  pub fn on_process_creation(&self) -> &'a dyn CBProcessProcessCreationEvent;
  pub fn set_on_process_creation(&mut self, value : &'a dyn CBProcessProcessCreationEvent);
  ...
}

Remarks

This event fires when a process is being created, after its first thread is created but before it begins running.

Applications may use this event to cancel the process creation by returning an appropriate error code (e.g., ACCESS_DENIED) via ResultCode.

The ProcessId parameter reflects the Id of the process being created.

The ParentProcessId parameter reflects the Id of the new process's parent process, from which it may inherit certain resources (e.g., handles, shared memory).

The CreatingProcessId parameter reflects the Id of the process that created the new process (which is not always the same as its parent process).

The CreatingThreadId parameter reflects the Id of the thread that created the new process.

The ProcessName parameter reflects the name of the new process. This parameter's value is the same one that the get_process_name method would return for ProcessId.

The ImageFileName parameter reflects the name of the new process's executable file, as either a partial or a fully qualified file path.

The FileOpenNameAvailable parameter indicates whether the ImageFileName parameter's contains a fully qualified file path (true) or a partial one (false).

The CommandLine parameter reflects the command line used to start the new process.

Note: To use the event, enable it via the rcfgEventsToFire; configuration setting. For this event to fire, the creating process must match the rules that were added using add_filtered_process_by_id or add_filtered_process_by_name. Additionally, if the creating process is the same process that controls the instance of the struct, the FilterOwnRequests configuration setting must be set to true.

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_process_handle_operation Event (CBProcess Struct)

This event fires when a process handle is being created or duplicated.

Syntax

// CBProcessProcessHandleOperationEventArgs carries the CBProcess ProcessHandleOperation event's parameters.
pub struct CBProcessProcessHandleOperationEventArgs {
  fn duplication(&self) -> bool
  fn process_id(&self) -> i32
  fn originator_process_id(&self) -> i32
  fn originator_thread_id(&self) -> i32
  fn source_process_id(&self) -> i32
  fn target_process_id(&self) -> i32
  fn original_desired_access(&self) -> i32
  fn desired_access(&self) -> i32
  fn set_desired_access(&self, value : i32)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBProcessProcessHandleOperationEvent defines the signature of the CBProcess ProcessHandleOperation event's handler function.
pub trait CBProcessProcessHandleOperationEvent {
  fn on_process_handle_operation(&self, sender : CBProcess, e : &mut CBProcessProcessHandleOperationEventArgs);
}

impl <'a> CBProcess<'a> {
  pub fn on_process_handle_operation(&self) -> &'a dyn CBProcessProcessHandleOperationEvent;
  pub fn set_on_process_handle_operation(&mut self, value : &'a dyn CBProcessProcessHandleOperationEvent);
  ...
}

Remarks

This event fires when a process handle is being created or duplicated. The new handle allows operations to be performed on the associated process.

Applications may use this event to restrict the access rights that will be granted to the new process handle. For example, to prevent process termination, the application could remove the PROCESS_TERMINATE flag.

The Duplication parameter indicates whether a new process handle is being create (false) or an existing one is being duplicated (true).

The ProcessId parameter reflects the Id of the process whose handle is being created or duplicated.

The OriginatorProcessId parameter reflects the Id of the process that requested a handle be created or duplicated.

The OriginatorThreadId parameter reflects the Id of the thread that requested a handle be created or duplicated.

The SourceProcessId and TargetProcessId parameters reflect the Id of the process that is the source of the handle, and the Id of the process that receives the duplicated handle, respectively. (These parameters' values are valid only if Duplication is true.)

The OriginalDesiredAccess parameter reflects the access rights originally requested for the new handle.

The DesiredAccess parameter specifies the access rights that should be granted to the new handle; it will match OriginalDesiredAccess initially. Applications can remove access flags from this value, but they cannot add additional flags.

Please refer to Microsoft's OB_PRE_CREATE_HANDLE_INFORMATION structure documentation for more information about possible access flags.

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.

Note: To use the event, enable it via the rcfgEventsToFire; configuration setting.

Note: The system APIs offer no way to report errors that occur during the processing of this request. Therefore, exceptional ResultCode values are largely ignored.

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

on_process_termination Event (CBProcess Struct)

This event fires when a process is being terminated.

Syntax

// CBProcessProcessTerminationEventArgs carries the CBProcess ProcessTermination event's parameters.
pub struct CBProcessProcessTerminationEventArgs {
  fn process_id(&self) -> i32
  fn process_name(&self) -> &String
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBProcessProcessTerminationEvent defines the signature of the CBProcess ProcessTermination event's handler function.
pub trait CBProcessProcessTerminationEvent {
  fn on_process_termination(&self, sender : CBProcess, e : &mut CBProcessProcessTerminationEventArgs);
}

impl <'a> CBProcess<'a> {
  pub fn on_process_termination(&self) -> &'a dyn CBProcessProcessTerminationEvent;
  pub fn set_on_process_termination(&mut self, value : &'a dyn CBProcessProcessTerminationEvent);
  ...
}

Remarks

This event fires when a process is being terminated, just before its last thread is destroyed.

Applications cannot prevent a process from being terminated using this event; use the on_process_handle_operation event instead.

The ProcessId parameter reflects the Id of the terminating process.

The ProcessName parameter reflects the name of the terminating process. This parameter's value is the same one that the get_process_name method would return for ProcessId.

Note: To use the event, enable it via the rcfgEventsToFire; configuration setting.

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.

Note: The system APIs offer no way to report errors that occur during the processing of this request. Therefore, exceptional ResultCode values are largely ignored.

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

on_thread_creation Event (CBProcess Struct)

This event fires when a thread is being created.

Syntax

// CBProcessThreadCreationEventArgs carries the CBProcess ThreadCreation event's parameters.
pub struct CBProcessThreadCreationEventArgs {
  fn process_id(&self) -> i32
  fn thread_id(&self) -> i32
  fn creating_process_id(&self) -> i32
  fn creating_thread_id(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBProcessThreadCreationEvent defines the signature of the CBProcess ThreadCreation event's handler function.
pub trait CBProcessThreadCreationEvent {
  fn on_thread_creation(&self, sender : CBProcess, e : &mut CBProcessThreadCreationEventArgs);
}

impl <'a> CBProcess<'a> {
  pub fn on_thread_creation(&self) -> &'a dyn CBProcessThreadCreationEvent;
  pub fn set_on_thread_creation(&mut self, value : &'a dyn CBProcessThreadCreationEvent);
  ...
}

Remarks

This event fires when a thread is being created, before it is started.

Applications cannot cancel thread creation; any errors returned during this event are ignored.

The ProcessId parameter reflects the Id of the process to which the new thread belongs.

The ThreadId parameter reflects the Id of the new thread.

The CreatingProcessId parameter reflects the Id of the process that created the new thread.

The CreatingThreadId parameter reflects the Id of the thread that created the new thread.

Note: To use the event, enable it via the rcfgEventsToFire; configuration setting.

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.

Note: The system APIs offer no way to report errors that occur during the processing of this request. Therefore, exceptional ResultCode values are largely ignored.

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

on_thread_handle_operation Event (CBProcess Struct)

This event fires when a thread handle is being created or duplicated.

Syntax

// CBProcessThreadHandleOperationEventArgs carries the CBProcess ThreadHandleOperation event's parameters.
pub struct CBProcessThreadHandleOperationEventArgs {
  fn duplication(&self) -> bool
  fn process_id(&self) -> i32
  fn thread_id(&self) -> i32
  fn originator_process_id(&self) -> i32
  fn originator_thread_id(&self) -> i32
  fn source_process_id(&self) -> i32
  fn target_process_id(&self) -> i32
  fn original_desired_access(&self) -> i32
  fn desired_access(&self) -> i32
  fn set_desired_access(&self, value : i32)
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBProcessThreadHandleOperationEvent defines the signature of the CBProcess ThreadHandleOperation event's handler function.
pub trait CBProcessThreadHandleOperationEvent {
  fn on_thread_handle_operation(&self, sender : CBProcess, e : &mut CBProcessThreadHandleOperationEventArgs);
}

impl <'a> CBProcess<'a> {
  pub fn on_thread_handle_operation(&self) -> &'a dyn CBProcessThreadHandleOperationEvent;
  pub fn set_on_thread_handle_operation(&mut self, value : &'a dyn CBProcessThreadHandleOperationEvent);
  ...
}

Remarks

This event fires when a thread handle is being created or duplicated. The new handle allows operations to be performed on the associated thread.

Applications may use this event to restrict the access rights that will be granted to the new thread handle. For example, to prevent thread termination, the application could remove the THREAD_TERMINATE flag.

The Duplication parameter indicates whether a new thread handle is being created (false), or an existing one is being duplicated (true).

The ProcessId parameter reflects the Id of the process whose thread's handle is being created or duplicated.

The ThreadId parameter reflects the Id of the thread whose handle is being created or duplicated.

Note: To use the event, enable it via the rcfgEventsToFire; configuration setting.

The OriginatorProcessId parameter reflects the Id of the process that requested a handle be created or duplicated.

The OriginatorThreadId parameter reflects the Id of the thread that requested a handle be created or duplicated.

The SourceProcessId and TargetProcessId parameters reflect the Id of the process that is the source of the handle, and the Id of the process that receives the duplicated handle, respectively. (These parameters' values are valid only if Duplication is true.)

The OriginalDesiredAccess parameter reflects the access rights originally requested for the new handle.

The DesiredAccess parameter specifies the access rights that should be granted to the new handle; it will match OriginalDesiredAccess initially. Applications can remove access flags from this value, but they cannot add additional flags.

Please refer to Microsoft's OB_PRE_CREATE_HANDLE_INFORMATION structure documentation for more information about possible access flags.

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.

Note: The system APIs offer no way to report errors that occur during the processing of this request. Therefore, exceptional ResultCode values are largely ignored.

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

on_thread_termination Event (CBProcess Struct)

This event fires when a thread is being terminated.

Syntax

// CBProcessThreadTerminationEventArgs carries the CBProcess ThreadTermination event's parameters.
pub struct CBProcessThreadTerminationEventArgs {
  fn process_id(&self) -> i32
  fn thread_id(&self) -> i32
  fn result_code(&self) -> i32
  fn set_result_code(&self, value : i32)
}

// CBProcessThreadTerminationEvent defines the signature of the CBProcess ThreadTermination event's handler function.
pub trait CBProcessThreadTerminationEvent {
  fn on_thread_termination(&self, sender : CBProcess, e : &mut CBProcessThreadTerminationEventArgs);
}

impl <'a> CBProcess<'a> {
  pub fn on_thread_termination(&self) -> &'a dyn CBProcessThreadTerminationEvent;
  pub fn set_on_thread_termination(&mut self, value : &'a dyn CBProcessThreadTerminationEvent);
  ...
}

Remarks

This event fires when a thread is being terminated.

Applications cannot prevent a thread from being terminated using this event; use the on_thread_handle_operation event instead.

The ProcessId parameter reflects the Id of process whose thread is being terminated.

The ThreadId parameter reflects the Id of the terminating thread.

Note: To use the event, enable it via the rcfgEventsToFire; configuration setting.

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.

Note: The system APIs offer no way to report errors that occur during the processing of this request. Therefore, exceptional ResultCode values are largely ignored.

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

on_worker_thread_creation Event (CBProcess Struct)

Fires just after a new worker thread is created.

Syntax

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

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

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

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

Fires just before a worker thread is terminated.

Syntax

// CBProcessWorkerThreadTerminationEventArgs carries the CBProcess WorkerThreadTermination event's parameters.
pub struct CBProcessWorkerThreadTerminationEventArgs {
}

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

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

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

CBProcess Config Settings

Base Config Settings

Trappable Errors (CBProcess Struct)

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

Special Use Errors