CBProcess Class

Properties Methods Events Config Settings Errors

The CBProcess class enables applications to intercept process manager requests.

Syntax

CBProcess

Remarks

The CBProcess class 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 classs' APIs, it uses simple filter rules; please refer to the File and Registry Filter Rules topic for more information.

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

Getting Started

If the class's system driver has not been installed yet, call the Install method to do so. This needs to be done only once.
- In production, the driver can be installed (or updated) ahead of time by the application's installation script using the Installer DLL. Please refer to the Driver Installation topic for more information.
Call the Initialize method to initialize the CBProcess class. This must be done each time the application starts.
Add one or more filter rules using methods like AddFilteredProcessById and AddFilteredProcessByName. (Rules also can be added or removed after the filter is started.)
Call the StartFilter method to start filtering process manager requests.
When finished, call the StopFilter method to stop filtering process manager requests.
To uninstall the class's system driver, call the Uninstall method. This should not be done as part of the driver upgrade process.
- In production, the driver can be uninstalled by the application's uninstallation script using the Installer DLL. Please refer to the Driver Installation topic for more information.

Property List

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


Active	This property notes whether the class is active and processing requests.
Altitude	This property specifies the altitude that the class's system driver should use.
RunningProcesses	This property includes a collection of running processes' information.
SerializeEvents	Whether events should be fired on a single worker thread, or many.
StrictAltitude	This property specifies how to behave if the specified altitude is already in use.
Tag	This property stores application-defined data specific to a particular instance of the class.
TrackCommandLine	This property specifies whether the driver should store information about processes' command-line arguments.

Method List

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


AddFilteredProcessById	This method adds a process, by process ID (PID), to the list of filtered processes.
AddFilteredProcessByName	This method adds a process, by name, to the list of filtered processes.
AddIgnoredProcessById	This method adds a process, by process ID (PID), to the list of ignored processes.
AddIgnoredProcessByName	This method adds a process, by name, to the list of ignored processes.
CloseRunningProcessesSnapshot	This method closes the previously created snapshot of running processes.
Config	Sets or retrieves a configuration setting.
CreateRunningProcessesSnapshot	This method creates a snapshot of running processes.
GetDriverStatus	This method retrieves the status of the class's system driver.
GetDriverVersion	This method retrieves the version of the class's system driver.
GetOriginatorToken	This method retrieves the security token associated with the process that initiated the operation.
GetProcessName	This method retrieves the name of the process associated with the specified process ID (PID).
Initialize	This method initializes the class.
Install	This method installs (or upgrades) the class's system driver.
RemoveFilteredProcessById	This method removes a process, by process ID (PID), from the list of filtered processes.
RemoveFilteredProcessByName	This method removes a process, by name, from the list of filtered processes.
RemoveIgnoredProcessById	This method removes a process, by process ID (PID), from the list of ignored processes.
RemoveIgnoredProcessByName	This method removes a process, by name, from the list of ignored processes.
ResetTimeout	This method resets the timeout duration for the current event handler.
ShutdownSystem	Shuts down or reboots the operating system.
StartFilter	This method starts the filtering process and thread operations.
StopFilter	This method stops the filtering process and thread operations.
Uninstall	This method uninstalls the class's system driver.

Event List

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


Error	This event fires if an unhandled error occurs during an event.
ProcessCreation	This event fires when a process is being created.
ProcessHandleOperation	This event fires when a process handle is being created or duplicated.
ProcessTermination	This event fires when a process is being terminated.
ThreadCreation	This event fires when a thread is being created.
ThreadHandleOperation	This event fires when a thread handle is being created or duplicated.
ThreadTermination	This event fires when a thread is being terminated.
WorkerThreadCreation	Fires just after a new worker thread is created.
WorkerThreadTermination	Fires just before a worker thread is terminated.

Config Settings

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


FilterOwnRequests	Whether the class's system driver should filter requests made by the application itself.
LoggingEnabled	Whether extended logging is enabled.
MaxWorkerThreadCount	The maximum number of worker threads to use to fire events.
MinWorkerThreadCount	The minimum number of worker threads to use to fire events.
WorkerInitialStackSize	The initial stack size to create worker threads with.
BuildInfo	Information about the product's build.
LicenseInfo	Information about the current license.

Active Property (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();

int cbfsfilter_cbprocess_getactive(void* lpObj);

bool GetActive();

Default Value

FALSE

Remarks

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

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

Data Type

Boolean

Altitude Property (CBProcess Class)

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

Syntax

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

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

char* cbfsfilter_cbprocess_getaltitude(void* lpObj);
int cbfsfilter_cbprocess_setaltitude(void* lpObj, const char* lpszAltitude);

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

Default Value

"400055"

Remarks

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

Microsoft'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 class's driver will behave in the manner specified by the StrictAltitude property.

Data Type

String

RunningProcesses Property (CBProcess Class)

This property includes a collection of running processes' information.

Syntax

CBFSFilterList<CBFSFilterRunningProcess>* GetRunningProcesses();

int cbfsfilter_cbprocess_getrunningprocesscount(void* lpObj);

char* cbfsfilter_cbprocess_getrunningprocesscommandline(void* lpObj, int runningprocessindex);

int cbfsfilter_cbprocess_getrunningprocessprocessid(void* lpObj, int runningprocessindex);

char* cbfsfilter_cbprocess_getrunningprocessprocessname(void* lpObj, int runningprocessindex);

int GetRunningProcessCount();

QString GetRunningProcessCommandLine(int iRunningProcessIndex);

int GetRunningProcessProcessId(int iRunningProcessIndex);

QString GetRunningProcessProcessName(int iRunningProcessIndex);

Remarks

This property holds a collection of RunningProcess objects, each of which represents a running process.

Note: This collection is not populated or updated by default. Applications can call the CreateRunningProcessesSnapshot method to populate this collection; and must call the CloseRunningProcessesSnapshot method when finished working with it to release the associated memory.

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

Data Type

CBFSFilterRunningProcess

SerializeEvents Property (CBProcess Class)

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

Syntax

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

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

Possible Values

SE_ON_MULTIPLE_THREADS(0), 
SE_ON_ONE_WORKER_THREAD(1)

int cbfsfilter_cbprocess_getserializeevents(void* lpObj);
int cbfsfilter_cbprocess_setserializeevents(void* lpObj, int iSerializeEvents);

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

Default Value

Remarks

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


0 (seOnMultipleThreads)	The class fires events in the context of multiple worker threads. The MinWorkerThreadCount and MaxWorkerThreadCount configuration settings control how many worker threads are used for this.
1 (seOnOneWorkerThread)	The class fires events in the context of one background worker thread.

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

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

Data Type

Integer

StrictAltitude Property (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int GetStrictAltitude();
int SetStrictAltitude(int bStrictAltitude);

Unicode (Windows)
BOOL GetStrictAltitude();
INT SetStrictAltitude(BOOL bStrictAltitude);

int cbfsfilter_cbprocess_getstrictaltitude(void* lpObj);
int cbfsfilter_cbprocess_setstrictaltitude(void* lpObj, int bStrictAltitude);

bool GetStrictAltitude();
int SetStrictAltitude(bool bStrictAltitude);

Default Value

FALSE

Remarks

This property specifies how the class's system driver should behave if the specified Altitude is already in use when the StartFilter 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

Boolean

Tag Property (CBProcess Class)

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

Syntax

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

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

int64 cbfsfilter_cbprocess_gettag(void* lpObj);
int cbfsfilter_cbprocess_settag(void* lpObj, int64 lTag);

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

Default Value

Remarks

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

Data Type

Long64

TrackCommandLine Property (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int GetTrackCommandLine();
int SetTrackCommandLine(int bTrackCommandLine);

Unicode (Windows)
BOOL GetTrackCommandLine();
INT SetTrackCommandLine(BOOL bTrackCommandLine);

int cbfsfilter_cbprocess_gettrackcommandline(void* lpObj);
int cbfsfilter_cbprocess_settrackcommandline(void* lpObj, int bTrackCommandLine);

bool GetTrackCommandLine();
int SetTrackCommandLine(bool bTrackCommandLine);

Default Value

FALSE

Remarks

This property specifies whether the class 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 CreateRunningProcessesSnapshot.

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

Data Type

Boolean

AddFilteredProcessById Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int AddFilteredProcessById(int iProcessId, int bIncludeChildren);

Unicode (Windows)
INT AddFilteredProcessById(INT iProcessId, BOOL bIncludeChildren);

int cbfsfilter_cbprocess_addfilteredprocessbyid(void* lpObj, int iProcessId, int bIncludeChildren);

int AddFilteredProcessById(int iProcessId, bool bIncludeChildren);

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

Error Handling (C++)

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

AddFilteredProcessByName Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int AddFilteredProcessByName(const char* lpszProcessName, int bIncludeChildren);

Unicode (Windows)
INT AddFilteredProcessByName(LPCWSTR lpszProcessName, BOOL bIncludeChildren);

int cbfsfilter_cbprocess_addfilteredprocessbyname(void* lpObj, const char* lpszProcessName, int bIncludeChildren);

int AddFilteredProcessByName(const QString& qsProcessName, bool bIncludeChildren);

Remarks

This method adds the process with the specified ProcessName to the list of processes whose requests should be filtered (i.e., that the class 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.

Error Handling (C++)

AddIgnoredProcessById Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int AddIgnoredProcessById(int iProcessId, int bIncludeChildren);

Unicode (Windows)
INT AddIgnoredProcessById(INT iProcessId, BOOL bIncludeChildren);

int cbfsfilter_cbprocess_addignoredprocessbyid(void* lpObj, int iProcessId, int bIncludeChildren);

int AddIgnoredProcessById(int iProcessId, bool bIncludeChildren);

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 class 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 class'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 AddFilteredProcessById or AddFilteredProcessByName.

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

Error Handling (C++)

AddIgnoredProcessByName Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int AddIgnoredProcessByName(const char* lpszProcessName, int bIncludeChildren);

Unicode (Windows)
INT AddIgnoredProcessByName(LPCWSTR lpszProcessName, BOOL bIncludeChildren);

int cbfsfilter_cbprocess_addignoredprocessbyname(void* lpObj, const char* lpszProcessName, int bIncludeChildren);

int AddIgnoredProcessByName(const QString& qsProcessName, bool bIncludeChildren);

Remarks

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

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

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

Error Handling (C++)

CloseRunningProcessesSnapshot Method (CBProcess Class)

This method closes the previously created snapshot of running processes.

Syntax

ANSI (Cross Platform)
int CloseRunningProcessesSnapshot();

Unicode (Windows)
INT CloseRunningProcessesSnapshot();

int cbfsfilter_cbprocess_closerunningprocessessnapshot(void* lpObj);

int CloseRunningProcessesSnapshot();

Remarks

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

Note: This method cannot be called within events.

Error Handling (C++)

Config Method (CBProcess Class)

Sets or retrieves a configuration setting.

Syntax

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

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);

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

QString Config(const QString& qsConfigurationString);

Remarks

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

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

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

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

Error Handling (C++)

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

CreateRunningProcessesSnapshot Method (CBProcess Class)

This method creates a snapshot of running processes.

Syntax

ANSI (Cross Platform)
int CreateRunningProcessesSnapshot();

Unicode (Windows)
INT CreateRunningProcessesSnapshot();

int cbfsfilter_cbprocess_createrunningprocessessnapshot(void* lpObj);

int CreateRunningProcessesSnapshot();

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 CloseRunningProcessesSnapshot method to release the associated memory. If this method is called again before an existing snapshot is closed, the class will attempt to close it before creating a new one.

Note: This method cannot be called within events.

Error Handling (C++)

GetDriverStatus Method (CBProcess Class)

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

Syntax

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

Unicode (Windows)
INT GetDriverStatus(LPCWSTR lpszProductGUID);

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

int GetDriverStatus(const QString& qsProductGUID);

Remarks

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

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


MODULE_STATUS_NOT_PRESENT	`0x00000000`	The specified module is not present on the system. Note: This functionality is only available in Windows.
MODULE_STATUS_STOPPED	`0x00000001`	The specified module is in the Stopped state. Note: This functionality is only available in Windows.
MODULE_STATUS_RUNNING	`0x00000004`	The specified module is loaded and running. Note: This functionality is only available in Windows.

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

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

Install
Uninstall
GetDriverStatus
GetDriverVersion
Initialize

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

Note: This method cannot be called within events.

Error Handling (C++)

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

GetDriverVersion Method (CBProcess Class)

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

Syntax

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

Unicode (Windows)
LONG64 GetDriverVersion(LPCWSTR lpszProductGUID);

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

qint64 GetDriverVersion(const QString& qsProductGUID);

Remarks

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

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

Install
Uninstall
GetDriverStatus
GetDriverVersion
Initialize

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

Note: This method cannot be called within events.

Error Handling (C++)

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

GetOriginatorToken Method (CBProcess Class)

This method retrieves the security token associated with the process that initiated the operation.

Syntax

ANSI (Cross Platform)
int64 GetOriginatorToken();

Unicode (Windows)
LONG64 GetOriginatorToken();

int64 cbfsfilter_cbprocess_getoriginatortoken(void* lpObj);

qint64 GetOriginatorToken();

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.

Error Handling (C++)

GetProcessName Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
char* GetProcessName(int iProcessId);

Unicode (Windows)
LPWSTR GetProcessName(INT iProcessId);

char* cbfsfilter_cbprocess_getprocessname(void* lpObj, int iProcessId);

QString GetProcessName(int iProcessId);

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.

Error Handling (C++)

Initialize Method (CBProcess Class)

This method initializes the class.

Syntax

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

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);

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

int Initialize(const QString& qsProductGUID);

Remarks

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

Install
Uninstall
GetDriverStatus
GetDriverVersion
Initialize

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

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

Error Handling (C++)

Install Method (CBProcess Class)

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

Syntax

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

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

bool cbfsfilter_cbprocess_install(void* lpObj, const char* lpszCabFileName, const char* lpszProductGUID, const char* lpszPathToInstall, int iFlags, const char* lpszAllowedControllers);

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

Remarks

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

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

Please refer to the Driver Installation topic for more information.

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

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

Install
Uninstall
GetDriverStatus
GetDriverVersion
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:


INSTALL_REMOVE_OLD_VERSIONS	`0x00000001`	Uninstall drivers from previous class versions (e.g., 2017).
INSTALL_KEEP_START_TYPE	`0x00000002`	Keep the driver's current start type setting in the registry. If this flag is not set (default), the installation logic will reset the driver's start type setting in the Windows registry to the default value. Setting this flag causes the installation logic to preserve the current value, which may be necessary if the user (or the application) set it previously.
INSTALL_OVERWRITE_SAME_VERSION	`0x00000004`	Install the driver file when its version and build number is the same as the version of the already installed driver.
INSTALL_REQUESTS_VIA_DRIVER_STACK	`0x00001000`	Whether internal requests to the filesystem are sent directly to the filesystem driver or through the stack of filesystem filter drivers. This flag is applicable only for CBFilter and CBMonitor. After installation, the effects of this flag can be changed using the SendRequestsViaDriverStack configuration setting.
INSTALL_ALWAYS_PREPARE_FILES	`0x00010000`	Whether the driver should keep track of information for files that are already open when (i.e., were opened before) the class is initialized. This flag is applicable only for CBFilter and CBMonitor. If this flag is set, the driver will prepare information about each file as it is opened, regardless of whether a CBFilter/CBMonitor-based application is actually running at the time. This information then allows applications to receive events for any files that are already open when the CBFilter/CBMonitor class is initialized. Note: These preparations will slow down all file open operations; do not enable this feature unless it is actually necessary. After installation, the effects of this flag can be changed using the AlwaysPrepareFiles configuration setting.
INSTALL_FORCE_APP_PERMISSION_CHECK	`0x00020000`	Whether the driver should require the controller process to have elevated or system privileges. This flag is not applicable for CBProcess. If this flag is set, the driver will verify that the controller process is a system service (or is executing with elevated privileges) anytime a file is opened. If the controller process does not meet these requirements, the file will be skipped (i.e., not filtered in any way). Note: This additional verification will slow down all file open operations. After installation, the effects of this flag can be changed using the ForceAppPermissionCheck configuration setting.
INSTALL_FORCE_SECURITY_CHECKS	`0x00040000`	Whether the driver should prevent the controller process from filtering files that it would not normally have access to. This flag is not applicable for CBProcess. If this flag is set, the driver will check the security permissions of the controller process anytime a file is opened to verify that the process has access to the file. If the controller process does not have access to the file, the file will be skipped (i.e., not filtered in any way). For example, if this flag is set and the controller process is running with limited privileges, then the driver will not allow it to filter files that require greater privileges to access. Note: This additional verification will slow down all file open operations. After installation, the effects of this flag can be changed using the ForceSecurityChecks configuration setting.

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 StartFilter 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 class API and the Installer DLL included with the product; please refer to the Driver Installation topic for more information about the latter.

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

Note: This method cannot be called within events.

Error Handling (C++)

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

RemoveFilteredProcessById Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int RemoveFilteredProcessById(int iProcessId);

Unicode (Windows)
INT RemoveFilteredProcessById(INT iProcessId);

int cbfsfilter_cbprocess_removefilteredprocessbyid(void* lpObj, int iProcessId);

int RemoveFilteredProcessById(int iProcessId);

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 AddFilteredProcessById; please refer to its documentation for more information.

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

Error Handling (C++)

RemoveFilteredProcessByName Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int RemoveFilteredProcessByName(const char* lpszProcessName);

Unicode (Windows)
INT RemoveFilteredProcessByName(LPCWSTR lpszProcessName);

int cbfsfilter_cbprocess_removefilteredprocessbyname(void* lpObj, const char* lpszProcessName);

int RemoveFilteredProcessByName(const QString& qsProcessName);

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 AddFilteredProcessByName; please refer to its documentation for more information.

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

Error Handling (C++)

RemoveIgnoredProcessById Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int RemoveIgnoredProcessById(int iProcessId);

Unicode (Windows)
INT RemoveIgnoredProcessById(INT iProcessId);

int cbfsfilter_cbprocess_removeignoredprocessbyid(void* lpObj, int iProcessId);

int RemoveIgnoredProcessById(int iProcessId);

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 AddIgnoredProcessById; please refer to its documentation for more information.

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

Error Handling (C++)

RemoveIgnoredProcessByName Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
int RemoveIgnoredProcessByName(const char* lpszProcessName);

Unicode (Windows)
INT RemoveIgnoredProcessByName(LPCWSTR lpszProcessName);

int cbfsfilter_cbprocess_removeignoredprocessbyname(void* lpObj, const char* lpszProcessName);

int RemoveIgnoredProcessByName(const QString& qsProcessName);

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 AddIgnoredProcessByName; please refer to its documentation for more information.

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

Error Handling (C++)

ResetTimeout Method (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
bool ResetTimeout(int iTimeout);

Unicode (Windows)
INT ResetTimeout(INT iTimeout);

bool cbfsfilter_cbprocess_resettimeout(void* lpObj, int iTimeout);

bool ResetTimeout(int iTimeout);

Remarks

When event timeouts are being enforced, this method can be called within an event handler to inform the class 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.

Error Handling (C++)

ShutdownSystem Method (CBProcess Class)

Shuts down or reboots the operating system.

Syntax

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

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

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

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

Remarks

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

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

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

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

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

Note: This method cannot be called within events.

Error Handling (C++)

StartFilter Method (CBProcess Class)

This method starts the filtering process and thread operations.

Syntax

ANSI (Cross Platform)
int StartFilter(int iTimeout, int iEventsToFire);

Unicode (Windows)
INT StartFilter(INT iTimeout, INT iEventsToFire);

int cbfsfilter_cbprocess_startfilter(void* lpObj, int iTimeout, int iEventsToFire);

int StartFilter(int iTimeout, int iEventsToFire);

Remarks

This method attaches the filter, causing the class'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 class's system driver has not been properly installed, or is awaiting a system reboot (as indicated by the return value of Install), this method fails with an ERROR_FILE_NOT_FOUND (2) error code.
If the Initialize method has not been called yet, this method fails with an ERROR_NOT_READY (21) error code.
If the filter is already Active, this method fails with an ERROR_CONNECTION_ACTIVE (1230) error code.
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 ResetTimeout to reset the timer if they require additional time to complete.

EventsToFire

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


PROC_EVT_NONE	`0`	Don't fire for any process operations. Events will not fire for any process operations.
PROC_EVT_PROCESS_CREATION	`1`	Fire during process creation operations. The ProcessCreation event will fire anytime the OS attempts to create a process.
PROC_EVT_PROCESS_TERMINATION	`2`	Fire during process closing/termination. The ProcessTermination event will fire when a process is being terminated.
PROC_EVT_PROCESS_HANDLE_OPERATION	`4`	Fire during process handle creation or duplication. The ProcessHandleOperation event will fire when a process handle is being created or duplicated.
PROC_EVT_THREAD_CREATION	`8`	Fire during thread creation operations. The ThreadCreation event will fire when a thread is being created, before it is started.
PROC_EVT_THREAD_TERMINATION	`0x10`	Fire during thread termination operations. The ThreadTermination event will fire when a thread is being terminated.
PROC_EVT_THREAD_HANDLE_OPERATION	`0x20`	Fire during thread handle creation or duplication. The ThreadHandleOperation event will fire when a thread handle is being created or duplicated.
PROC_EVT_ALL	`-1`	Fire for all process and thread operations. Events will fire for all thread operations.

Error Handling (C++)

StopFilter Method (CBProcess Class)

This method stops the filtering process and thread operations.

Syntax

ANSI (Cross Platform)
int StopFilter();

Unicode (Windows)
INT StopFilter();

int cbfsfilter_cbprocess_stopfilter(void* lpObj);

int StopFilter();

Remarks

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

Error Handling (C++)

Uninstall Method (CBProcess Class)

This method uninstalls the class's system driver.

Syntax

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

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

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

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

Remarks

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

Please refer to the Driver Installation topic for more information.

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

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


UNINSTALL_VERSION_PREVIOUS	`0x00000001`	Uninstall modules from previous product versions. Note: This functionality is only available in Windows.
UNINSTALL_VERSION_CURRENT	`0x00000002`	Uninstall modules from the current product version. Note: This functionality is only available in Windows.
UNINSTALL_VERSION_ALL	`0x00000003`	Uninstall modules from all product versions. Note: This functionality is only available in Windows.

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

Note: This method cannot be called within events.

Error Handling (C++)

Error Event (CBProcess Class)

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

Syntax

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

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


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

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

#define EID_CBPROCESS_ERROR 1

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

class CBProcessErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

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

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

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

Remarks

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

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

ProcessCreation Event (CBProcess Class)

This event fires when a process is being created.

Syntax

ANSI (Cross Platform)
virtual int FireProcessCreation(CBProcessProcessCreationEventParams *e);

typedef struct {
  int ProcessId;
  int ParentProcessId;
  int CreatingProcessId;
  int CreatingThreadId;
  const char *ProcessName;
  const char *ImageFileName;
  int FileOpenNameAvailable;
  const char *CommandLine;
  int ResultCode;
  int reserved;
} CBProcessProcessCreationEventParams;


Unicode (Windows)
virtual INT FireProcessCreation(CBProcessProcessCreationEventParams *e);

typedef struct {
  INT ProcessId;
  INT ParentProcessId;
  INT CreatingProcessId;
  INT CreatingThreadId;
  LPCWSTR ProcessName;
  LPCWSTR ImageFileName;
  BOOL FileOpenNameAvailable;
  LPCWSTR CommandLine;
  INT ResultCode;
  INT reserved;
} CBProcessProcessCreationEventParams;

#define EID_CBPROCESS_PROCESSCREATION 2

virtual INT CBFSFILTER_CALL FireProcessCreation(INT &iProcessId, INT &iParentProcessId, INT &iCreatingProcessId, INT &iCreatingThreadId, LPWSTR &lpszProcessName, LPWSTR &lpszImageFileName, BOOL &bFileOpenNameAvailable, LPWSTR &lpszCommandLine, INT &iResultCode);

class CBProcessProcessCreationEventParams {
public:
  int ProcessId();

  int ParentProcessId();

  int CreatingProcessId();

  int CreatingThreadId();

  const QString &ProcessName();

  const QString &ImageFileName();

  bool FileOpenNameAvailable();

  const QString &CommandLine();

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

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

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireProcessCreation(CBProcessProcessCreationEventParams *e) {...}

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 GetProcessName 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 AddFilteredProcessById or AddFilteredProcessByName. Additionally, if the creating process is the same process that controls the instance of the class, 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.

ProcessHandleOperation Event (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireProcessHandleOperation(CBProcessProcessHandleOperationEventParams *e);

typedef struct {
  int Duplication;
  int ProcessId;
  int OriginatorProcessId;
  int OriginatorThreadId;
  int SourceProcessId;
  int TargetProcessId;
  int OriginalDesiredAccess;
  int DesiredAccess;
  int ResultCode;
  int reserved;
} CBProcessProcessHandleOperationEventParams;


Unicode (Windows)
virtual INT FireProcessHandleOperation(CBProcessProcessHandleOperationEventParams *e);

typedef struct {
  BOOL Duplication;
  INT ProcessId;
  INT OriginatorProcessId;
  INT OriginatorThreadId;
  INT SourceProcessId;
  INT TargetProcessId;
  INT OriginalDesiredAccess;
  INT DesiredAccess;
  INT ResultCode;
  INT reserved;
} CBProcessProcessHandleOperationEventParams;

#define EID_CBPROCESS_PROCESSHANDLEOPERATION 3

virtual INT CBFSFILTER_CALL FireProcessHandleOperation(BOOL &bDuplication, INT &iProcessId, INT &iOriginatorProcessId, INT &iOriginatorThreadId, INT &iSourceProcessId, INT &iTargetProcessId, INT &iOriginalDesiredAccess, INT &iDesiredAccess, INT &iResultCode);

class CBProcessProcessHandleOperationEventParams {
public:
  bool Duplication();

  int ProcessId();

  int OriginatorProcessId();

  int OriginatorThreadId();

  int SourceProcessId();

  int TargetProcessId();

  int OriginalDesiredAccess();

  int DesiredAccess();
  void SetDesiredAccess(int iDesiredAccess);

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

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

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireProcessHandleOperation(CBProcessProcessHandleOperationEventParams *e) {...}

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.

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.

ProcessTermination Event (CBProcess Class)

This event fires when a process is being terminated.

Syntax

ANSI (Cross Platform)
virtual int FireProcessTermination(CBProcessProcessTerminationEventParams *e);

typedef struct {
  int ProcessId;
  const char *ProcessName;
  int ResultCode;
  int reserved;
} CBProcessProcessTerminationEventParams;


Unicode (Windows)
virtual INT FireProcessTermination(CBProcessProcessTerminationEventParams *e);

typedef struct {
  INT ProcessId;
  LPCWSTR ProcessName;
  INT ResultCode;
  INT reserved;
} CBProcessProcessTerminationEventParams;

#define EID_CBPROCESS_PROCESSTERMINATION 4

virtual INT CBFSFILTER_CALL FireProcessTermination(INT &iProcessId, LPWSTR &lpszProcessName, INT &iResultCode);

class CBProcessProcessTerminationEventParams {
public:
  int ProcessId();

  const QString &ProcessName();

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

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

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireProcessTermination(CBProcessProcessTerminationEventParams *e) {...}

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 ProcessHandleOperation 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 GetProcessName method would return for ProcessId.

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.

ThreadCreation Event (CBProcess Class)

This event fires when a thread is being created.

Syntax

ANSI (Cross Platform)
virtual int FireThreadCreation(CBProcessThreadCreationEventParams *e);

typedef struct {
  int ProcessId;
  int ThreadId;
  int CreatingProcessId;
  int CreatingThreadId;
  int ResultCode;
  int reserved;
} CBProcessThreadCreationEventParams;


Unicode (Windows)
virtual INT FireThreadCreation(CBProcessThreadCreationEventParams *e);

typedef struct {
  INT ProcessId;
  INT ThreadId;
  INT CreatingProcessId;
  INT CreatingThreadId;
  INT ResultCode;
  INT reserved;
} CBProcessThreadCreationEventParams;

#define EID_CBPROCESS_THREADCREATION 5

virtual INT CBFSFILTER_CALL FireThreadCreation(INT &iProcessId, INT &iThreadId, INT &iCreatingProcessId, INT &iCreatingThreadId, INT &iResultCode);

class CBProcessThreadCreationEventParams {
public:
  int ProcessId();

  int ThreadId();

  int CreatingProcessId();

  int CreatingThreadId();

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

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

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireThreadCreation(CBProcessThreadCreationEventParams *e) {...}

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.

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.

ThreadHandleOperation Event (CBProcess Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireThreadHandleOperation(CBProcessThreadHandleOperationEventParams *e);

typedef struct {
  int Duplication;
  int ProcessId;
  int ThreadId;
  int OriginatorProcessId;
  int OriginatorThreadId;
  int SourceProcessId;
  int TargetProcessId;
  int OriginalDesiredAccess;
  int DesiredAccess;
  int ResultCode;
  int reserved;
} CBProcessThreadHandleOperationEventParams;


Unicode (Windows)
virtual INT FireThreadHandleOperation(CBProcessThreadHandleOperationEventParams *e);

typedef struct {
  BOOL Duplication;
  INT ProcessId;
  INT ThreadId;
  INT OriginatorProcessId;
  INT OriginatorThreadId;
  INT SourceProcessId;
  INT TargetProcessId;
  INT OriginalDesiredAccess;
  INT DesiredAccess;
  INT ResultCode;
  INT reserved;
} CBProcessThreadHandleOperationEventParams;

#define EID_CBPROCESS_THREADHANDLEOPERATION 6

virtual INT CBFSFILTER_CALL FireThreadHandleOperation(BOOL &bDuplication, INT &iProcessId, INT &iThreadId, INT &iOriginatorProcessId, INT &iOriginatorThreadId, INT &iSourceProcessId, INT &iTargetProcessId, INT &iOriginalDesiredAccess, INT &iDesiredAccess, INT &iResultCode);

class CBProcessThreadHandleOperationEventParams {
public:
  bool Duplication();

  int ProcessId();

  int ThreadId();

  int OriginatorProcessId();

  int OriginatorThreadId();

  int SourceProcessId();

  int TargetProcessId();

  int OriginalDesiredAccess();

  int DesiredAccess();
  void SetDesiredAccess(int iDesiredAccess);

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

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

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireThreadHandleOperation(CBProcessThreadHandleOperationEventParams *e) {...}

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 OriginalDesiredAccess parameter reflects the access rights originally requested for the new handle.

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

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.

ThreadTermination Event (CBProcess Class)

This event fires when a thread is being terminated.

Syntax

ANSI (Cross Platform)
virtual int FireThreadTermination(CBProcessThreadTerminationEventParams *e);

typedef struct {
  int ProcessId;
  int ThreadId;
  int ResultCode;
  int reserved;
} CBProcessThreadTerminationEventParams;


Unicode (Windows)
virtual INT FireThreadTermination(CBProcessThreadTerminationEventParams *e);

typedef struct {
  INT ProcessId;
  INT ThreadId;
  INT ResultCode;
  INT reserved;
} CBProcessThreadTerminationEventParams;

#define EID_CBPROCESS_THREADTERMINATION 7

virtual INT CBFSFILTER_CALL FireThreadTermination(INT &iProcessId, INT &iThreadId, INT &iResultCode);

class CBProcessThreadTerminationEventParams {
public:
  int ProcessId();

  int ThreadId();

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

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

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireThreadTermination(CBProcessThreadTerminationEventParams *e) {...}

Remarks

This event fires when a thread is being terminated.

Applications cannot prevent a thread from being terminated using this event; use the ThreadHandleOperation 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.

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.

WorkerThreadCreation Event (CBProcess Class)

Fires just after a new worker thread is created.

Syntax

ANSI (Cross Platform)
virtual int FireWorkerThreadCreation(CBProcessWorkerThreadCreationEventParams *e);

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


Unicode (Windows)
virtual INT FireWorkerThreadCreation(CBProcessWorkerThreadCreationEventParams *e);

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

#define EID_CBPROCESS_WORKERTHREADCREATION 8

virtual INT CBFSFILTER_CALL FireWorkerThreadCreation(INT &iResultCode);

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

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

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireWorkerThreadCreation(CBProcessWorkerThreadCreationEventParams *e) {...}

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

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

WorkerThreadTermination Event (CBProcess Class)

Fires just before a worker thread is terminated.

Syntax

ANSI (Cross Platform)
virtual int FireWorkerThreadTermination(CBProcessWorkerThreadTerminationEventParams *e);

typedef struct {
  int reserved;
} CBProcessWorkerThreadTerminationEventParams;


Unicode (Windows)
virtual INT FireWorkerThreadTermination(CBProcessWorkerThreadTerminationEventParams *e);

typedef struct {
  INT reserved;
} CBProcessWorkerThreadTerminationEventParams;

#define EID_CBPROCESS_WORKERTHREADTERMINATION 9

virtual INT CBFSFILTER_CALL FireWorkerThreadTermination();

class CBProcessWorkerThreadTerminationEventParams {
public:
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};

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

// Or, subclass CBProcess and override this emitter function.
virtual int FireWorkerThreadTermination(CBProcessWorkerThreadTerminationEventParams *e) {...}

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

RunningProcess Type

The type represents a running process.

Syntax

CBFSFilterRunningProcess (declared in cbfsfilter.h)

Remarks

This type represents a process that is running in the system. The process list is taken from the running CBProcess driver.

The following fields are available:

CommandLine

ProcessId

ProcessName

Fields

CommandLine
char* (read-only)
Default Value: ""

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

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

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

ProcessId
int (read-only)
Default Value: 0

This field reflects the process Id (PID).

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

ProcessName
char* (read-only)
Default Value: ""

This field reflects the name of the process.

This field reflects the name of the running process.

CBFSFilterList Type

Syntax

CBFSFilterList<T> (declared in cbfsfilter.h)

Remarks

CBFSFilterList is a generic class that is used to hold a collection of objects of type T, where T is one of the custom types supported by the CBProcess class.

Methods

GetCount	This method returns the current size of the collection. int GetCount() {}
SetCount	This method sets the size of the collection. This method returns `0` if setting the size was successful; or `-1` if the collection is `ReadOnly`. When adding additional objects to a collection call this method to specify the new size. Increasing the size of the collection preserves existing objects in the collection. int SetCount(int count) {}
Get	This method gets the item at the specified position. The `index` parameter specifies the index of the item in the collection. This method returns `NULL` if an invalid `index` is specified. T* Get(int index) {}
Set	This method sets the item at the specified position. The `index` parameter specifies the index of the item in the collection that is being set. This method returns `-1` if an invalid `index` is specified. Note: Objects created using the `new` operator must be freed using the `delete` operator; they will not be automatically freed by the class. T* Set(int index, T* value) {}

Config Settings (CBProcess Class)

The class 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 class, access to these internal properties is provided through the Config method.

CBProcess Config Settings

FilterOwnRequests: Whether the class's system driver should filter requests made by the application itself.

This configuration setting specifies whether requests made by the application should be filtered through the class's system driver (assuming that they match one of the rules present at the time). When this setting is disabled (default), and the application performs some operation that would match an existing rule, the driver will explicitly ignore it.

Normally, this setting should remain disabled (especially in production) to reduce the possibility of system deadlocks occurring. Certain situations, however, do require it to be enabled, such as for testing purposes (so that event handlers can be tested with single-process tests).

LoggingEnabled: Whether extended logging is enabled.

This setting specifies whether extended logging is enabled for this class; it is disabled by default. Please refer to the Error Handling topic for more information.

This setting's value is stored in the registry and is persistent; it requires administrative rights to be changed.

MaxWorkerThreadCount: The maximum number of worker threads to use to fire events.

This setting specifies the maximum number of worker threads the class may create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (If other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: 4 * number_of_processors.

MinWorkerThreadCount: The minimum number of worker threads to use to fire events.

This setting specifies the minimum number of worker threads the class should create to fire events on when the SerializeEvents property is set to seOnMultipleThreads. (In other cases, this setting does not apply.)

By default, this setting is set to 0, and the driver automatically chooses an optimal number of threads using this equation: max(number_of_processors, 4). If this setting's value exceeds the MaxWorkerThreadCount value, the latter is used instead.

WorkerInitialStackSize: The initial stack size to create worker threads with.

This setting specifies the initial size of the stack each worker thread is created with. The system rounds this value to the nearest page.

By default, this setting is set to 0, and the driver uses a default stack size (currently, 1 MB).

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

Base Config Settings

BuildInfo: Information about the product's build.

When queried, this setting will return a string containing information about the product's build.

LicenseInfo: Information about the current license.

When queried, this setting will return a string containing information about the license this instance of a class is using. It will return the following information:

Product: The product the license is for.
Product Key: The key the license was generated from.
License Source: Where the license was found (e.g., RuntimeLicense, License File).
License Type: The type of license installed (e.g., Royalty Free, Single Server).

Trappable Errors (CBProcess Class)

Error Handling (C++)

Call the GetLastErrorCode() method to obtain the last called method's result code; 0 indicates success, while a non-zero error code indicates that this method encountered an error during its execution. Known error codes are listed below. If an error occurs, the GetLastError() method can be called to retrieve the associated error message.

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

Special Use Errors

21	ERROR_NOT_READY: Reported by the methods of the class if Initialize has not been called or did not succeed.
191	ERROR_INVALID_EXE_SIGNATURE: Reported by the Install method when the CAB file signature cannot be validated.
575	ERROR_APP_INIT_FAILURE: Reported by the methods of the class if Initialize has not been called or did not succeed. Differs from ERROR_NOT_READY (21) in that it indicates a specific situation in the internal code.
588	ERROR_FS_DRIVER_REQUIRED: Reported if the required system module was not correctly installed for the given `ProductGUID`.
614	ERROR_NO_CALLBACK_ACTIVE: Reported by any method that can only be called within event handlers if it is called outside an event handler.
1292	ERROR_IMPLEMENTATION_LIMIT: Reported when the timeout value provided is less than 3 seconds.
1314	ERROR_PRIVILEGE_NOT_HELD: Reported by any method that requires elevated permissions if it is called without such permissions.