CBRegistry Class

Properties   Methods   Events   Config Settings   Errors  

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

Syntax

CBRegistry

Remarks

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

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

Getting Started

  1. 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.
  2. Call the Initialize method to initialize the CBRegistry class. This must be done each time the application starts.
  3. Add one or more filter rules using methods like AddFilterRule. (Rules also can be added or removed after the filter is started.)
  4. Call the StartFilter method to start filtering filesystem requests.
  5. When finished, call the StopFilter method to stop filtering filesystem requests.
  6. 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.

ActiveThis property notes whether the class is active and processing requests.
AltitudeThis property specifies the altitude the class's system driver should use.
DefaultRulesThis property includes a collection of default rules.
FilterRulesThis property includes a collection of filter rules.
PassthroughRulesThis properly includes a collection of passthrough rules.
SerializeEventsWhether events should be fired on a single worker thread, or many.
TagThis property stores application-defined data specific to a particular instance of the class.

Method List


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

AddDefaultRuleThis method adds a default rule.
AddFilteredProcessByIdThis method adds a process, by process ID (PID), to the list of filtered processes.
AddFilteredProcessByNameThis method adds a process, by name, to the list of filtered processes.
AddFilterRuleThis method adds a standard filter rule or access rule.
AddIgnoredProcessByIdThis method adds a process, by process Id (PID), to the list of ignored processes.
AddIgnoredProcessByNameThis method adds a process, by name, to the list of ignored processes.
AddPassthroughRuleThis method adds a passthrough rule.
CloseDefaultRulesSnapshotThis method closes the previously created default rules snapshot.
ConfigSets or retrieves a configuration setting.
CreateDefaultRulesSnapshotThis method creates a snapshot of information about the default rules that have been added.
DeleteAllFilterRulesThis method deletes all standard filter rules.
DeleteAllPassthroughRulesThis method deletes all passthrough rules.
DeleteDefaultRuleThis method deletes a particular default rule.
DeleteFilterRuleThis method deletes a particular standard filter rule or access rule.
DeletePassthroughRuleThis method deletes a particular passthrough rule.
GetDriverStatusThis method retrieves the status of the class's system driver.
GetDriverVersionThis method retrieves the version of the class's system driver.
GetOriginatorProcessIdThis method retrieves the process Id (PID) that initiated the operation.
GetOriginatorProcessNameThis method retrieves the name of the process that initiated the operation.
GetOriginatorThreadIdThis method retrieves the thread Id that initiated the operation.
GetOriginatorTokenThis method retrieves the security token associated with the process that initiated the operation.
InitializeThis method initializes the class.
InstallThis method installs (or upgrades) the class's system driver.
RemoveFilteredProcessByIdThis method removes a process, by process Id (PID), from the list of filtered processes.
RemoveFilteredProcessByNameThis method removes a process, by name, from the list of filtered processes.
RemoveIgnoredProcessByIdThis method removes a process, by process Id (PID), from the list of ignored processes.
RemoveIgnoredProcessByNameThis method removes a process, by name, from the list of ignored processes.
ResetTimeoutThis method resets the timeout duration for the current event handler.
ShutdownSystemShuts down or reboots the operating system.
StartFilterThis method starts filtering registry operations.
StopFilterThis method stops filtering registry operations.
SuspendDefaultRulesThis method suspends all default rules until the application exits.
ToggleProcessProtectionThis method enables or disables termination protection for the application.
UninstallThis 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.

AfterCloseKeyThis event fires after a registry key is closed.
AfterCreateKeyThis event fires after a registry key is created.
AfterDeleteKeyThis event fires after a registry key is deleted.
AfterDeleteValueThis event fires after a registry value is deleted.
AfterEnumerateKeyThis event fires after a subkey's information is retrieved during key enumeration.
AfterEnumerateValueThis event fires after a registry value's information is retrieved during key value enumeration.
AfterGetKeySecurityThis event fires after a registry key's security attributes are changed.
AfterOpenKeyThis event fires after a registry key is opened.
AfterQueryKeyThis event fires after a registry key's information is retrieved.
AfterQueryValueThis event fires after a registry value's information is retrieved.
AfterRenameKeyThis event fires after a registry key is renamed.
AfterSetKeyThis event fires after a registry key's information is updated.
AfterSetKeySecurityThis event fires after a registry key's security attributes are changed.
AfterSetValueThis event fires after a registry value is set or updated.
BeforeCloseKeyThis event fires before a registry key is closed.
BeforeCreateKeyThis event fires before a registry key is created.
BeforeDeleteKeyThis event fires before a registry key is deleted.
BeforeDeleteValueThis event fires before a registry value is deleted.
BeforeEnumerateKeyThis event fires before a subkey's information is retrieved during key enumeration.
BeforeEnumerateValueThis event fires before a registry value's information is retrieved during key value enumeration.
BeforeGetKeySecurityThis event fires before a registry key's security attributes are retrieved.
BeforeOpenKeyThis event fires before a registry key is opened.
BeforeQueryKeyThis event fires before a registry key's information is retrieved.
BeforeQueryValueThis event fires before a registry value's information is retrieved.
BeforeRenameKeyThis event fires before a registry key is renamed.
BeforeSetKeyThis event fires before a registry key's information is updated.
BeforeSetKeySecurityThis event fires before a registry key's security attributes are changed.
BeforeSetValueThis event fires before a registry value is set or updated.
CleanupKeyContextThis event fires when the application-defined data stored in a registry key context need to be cleaned up.
CloseKeyHandleThis event fires when an application-provided registry key handle should be closed.
ErrorThis event fires if an unhandled error occurs during an event.
WorkerThreadCreationFires just after a new worker thread is created.
WorkerThreadTerminationFires 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.

FilterOwnRequestsWhether the class's system driver should filter requests made by the application itself.
ForceAdminRightsForDefaultRulesSpecifies whether default rules can be added or deleted only by administrators.
ForceAppPermissionCheckWhether the driver should require the controller process to have elevated or system privileges.
ForceSecurityChecksWhether the driver should prevent the controller process from filtering files that it would not normally have access to.
LoggingEnabledWhether extended logging is enabled.
MaxWorkerThreadCountThe maximum number of worker threads to use to fire events.
MinWorkerThreadCountThe minimum number of worker threads to use to fire events.
ResolveNtNameToWin32NameWhether key names in NT native format are translated to common Win32 format.
WorkerInitialStackSizeThe initial stack size to create worker threads with.
BuildInfoInformation about the product's build.
LicenseInfoInformation about the current license.

Active Property (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
int GetActive();

Unicode (Windows)
BOOL GetActive();
int cbfsfilter_cbregistry_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 (CBRegistry Class)

This property specifies the altitude 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_cbregistry_getaltitude(void* lpObj);
int cbfsfilter_cbregistry_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.

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

Data Type

String

DefaultRules Property (CBRegistry Class)

This property includes a collection of default rules.

Syntax

int cbfsfilter_cbregistry_getdefaultrulecount(void* lpObj);
int cbfsfilter_cbregistry_getdefaultruleaccessflags(void* lpObj, int defaultruleindex);
char* cbfsfilter_cbregistry_getdefaultrulemask(void* lpObj, int defaultruleindex);
int GetDefaultRuleCount();

int GetDefaultRuleAccessFlags(int iDefaultRuleIndex);

QString GetDefaultRuleMask(int iDefaultRuleIndex);

Remarks

This property holds a collection of RegDefaultRule objects, each of which represents a default rule. Please refer to the Default Rules topic for more information.

Use the following methods to manage default rules:

Note: Because default rules are managed by the class's system driver, this collection is not populated by default, nor is it updated by any of the aforementioned methods. Applications can call the CreateDefaultRulesSnapshot method to populate this collection; and must call the CloseDefaultRulesSnapshot method when finished working with it to release the associated memory.

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

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

Data Type

CBFSFilterRegDefaultRule

FilterRules Property (CBRegistry Class)

This property includes a collection of filter rules.

Syntax

int cbfsfilter_cbregistry_getfilterrulecount(void* lpObj);
int cbfsfilter_cbregistry_getfilterruleaccessflags(void* lpObj, int filterruleindex);
int64 cbfsfilter_cbregistry_getfilterrulecontrolflags(void* lpObj, int filterruleindex);
char* cbfsfilter_cbregistry_getfilterrulemask(void* lpObj, int filterruleindex);
int GetFilterRuleCount();

int GetFilterRuleAccessFlags(int iFilterRuleIndex);

qint64 GetFilterRuleControlFlags(int iFilterRuleIndex);

QString GetFilterRuleMask(int iFilterRuleIndex);

Remarks

This property holds a collection of RegFilterRule objects, each of which represents a standard filter rule, access rule, or both. Please refer to the File and Registry Filter Rules and Access Rules topics for more information.

Use the following methods to manage the rules in this collection:

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

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

Data Type

CBFSFilterRegFilterRule

PassthroughRules Property (CBRegistry Class)

This properly includes a collection of passthrough rules.

Syntax

CBFSFilterList<CBFSFilterRegPassthroughRule>* GetPassthroughRules();

int cbfsfilter_cbregistry_getpassthroughrulecount(void* lpObj);
int cbfsfilter_cbregistry_getpassthroughruleaccessflags(void* lpObj, int passthroughruleindex);
int64 cbfsfilter_cbregistry_getpassthroughrulecontrolflags(void* lpObj, int passthroughruleindex);
char* cbfsfilter_cbregistry_getpassthroughrulemask(void* lpObj, int passthroughruleindex);
int GetPassthroughRuleCount();

int GetPassthroughRuleAccessFlags(int iPassthroughRuleIndex);

qint64 GetPassthroughRuleControlFlags(int iPassthroughRuleIndex);

QString GetPassthroughRuleMask(int iPassthroughRuleIndex);

Remarks

This property holds a collection of RegPassthroughRule objects, each of which represents a passthrough rule. Please refer to the Passthrough Rules topic for more information.

Use the following methods to manage the rules in this collection:

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

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

Data Type

CBFSFilterRegPassthroughRule

SerializeEvents Property (CBRegistry 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_cbregistry_getserializeevents(void* lpObj);
int cbfsfilter_cbregistry_setserializeevents(void* lpObj, int iSerializeEvents);
int GetSerializeEvents();
int SetSerializeEvents(int iSerializeEvents);

Default Value

0

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

Tag Property (CBRegistry 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_cbregistry_gettag(void* lpObj);
int cbfsfilter_cbregistry_settag(void* lpObj, int64 lTag);
qint64 GetTag();
int SetTag(qint64 lTag);

Default Value

0

Remarks

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

Data Type

Long64

AddDefaultRule Method (CBRegistry Class)

This method adds a default rule.

Syntax

ANSI (Cross Platform)
bool AddDefaultRule(const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);

Unicode (Windows)
INT AddDefaultRule(LPCWSTR lpszMask, INT iAccessFlags, LPCWSTR lpszProductGUID);
bool cbfsfilter_cbregistry_adddefaultrule(void* lpObj, const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);
bool AddDefaultRule(const QString& qsMask, int iAccessFlags, const QString& qsProductGUID);

Remarks

This method adds a default rule for the registry keys that matches the specified Mask. Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it.

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

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

The Mask parameter must be a valid registry key mask according to the Registry Key Masks topic. Only the registry keys that match the specified mask will be covered by the rule.

The AccessFlags parameter specifies which access restrictions the class's system driver should apply to matching registry keys. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

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

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

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

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.

AddFilteredProcessById Method (CBRegistry 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_cbregistry_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).

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

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

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

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

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 (CBRegistry 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_cbregistry_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).

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

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

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

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

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

AddFilterRule Method (CBRegistry Class)

This method adds a standard filter rule or access rule.

Syntax

ANSI (Cross Platform)
bool AddFilterRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags);

Unicode (Windows)
INT AddFilterRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags);
bool cbfsfilter_cbregistry_addfilterrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags);
bool AddFilterRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags);

Remarks

This method adds a standard filter rule or access rule for the registry keys that matches the specified Mask. Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it. If the rule is added successfully, this method returns true; otherwise, it returns false.

Standard filter rules determine which registry operations, of those performed on matching registry keys, the class should fire its events for. Access rules instruct the class's system driver to apply certain access restrictions to matching registry keys.

The Mask parameter must be a valid registry key mask according to the Registry Key Masks topic. Only the registry keys that match the specified mask will be covered by the rule.

The AccessFlags parameter specifies which access restrictions the class's system driver should apply to matching registry keys. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

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

REG_CE_NONE0Don't fire for any registry operations.

Control Events will not fire for any registry operations.

REG_CE_BEFORE_CREATE_KEY0x00000001LFire before registry key creation operations.

The BeforeCreateKey event will fire anytime the OS attempts to create a registry key.

REG_CE_AFTER_CREATE_KEY0x00000002LFire after registry key creation operations.

The AfterCreateKey event will fire after a registry key creation request has been processed, before the response is returned.

REG_CE_BEFORE_OPEN_KEY0x00000004LFire before registry key open operations.

The BeforeOpenKey event will fire anytime the OS attempts to open a registry key.

REG_CE_AFTER_OPEN_KEY0x00000008LFire after registry key open operations.

The AfterOpenKey event will fire after a registry key open request has been processed, before the response is returned.

REG_CE_BEFORE_CLOSE_KEY0x00000010LFire before registry key close operations.

The BeforeCloseKey event will fire anytime the OS closes a registry key.

REG_CE_AFTER_CLOSE_KEY0x00000020LFire after registry key close operations.

The AfterCloseKey event will fire after a registry key close request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_KEY0x00000040LFire before registry key delete operations.

The BeforeDeleteKey event will fire anytime the OS attempts to delete a registry key.

REG_CE_AFTER_DELETE_KEY0x00000080LFire after registry key delete operations.

The AfterDeleteKey event will fire after a registry key delete request has been processed, before the response is returned.

REG_CE_BEFORE_RENAME_KEY0x00000100LFire before registry key rename operations.

The BeforeRenameKey event will fire anytime the OS attempts to rename a registry key.

REG_CE_AFTER_RENAME_KEY0x00000200LFire after registry key rename operations.

The AfterRenameKey event will fire after a registry key rename request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_KEY0x00000400LFire before subkey enumeration operations.

The BeforeEnumerateKey event will fire anytime the OS attempts to enumerate a registry key's subkeys.

REG_CE_AFTER_ENUM_KEY0x00000800LFire after subkey enumeration operations.

The AfterEnumerateKey event will fire after a subkey enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_KEY0x00001000LFire before registry key metadata retrieval operations.

The BeforeQueryKey event will fire anytime the OS attempts to retrieve a registry key's metadata.

REG_CE_AFTER_QUERY_KEY0x00002000LFire after registry key metadata retrieval operations.

The AfterQueryKey event will fire after a registry key metadata retrieval request has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY0x00004000LFire before registry key metadata update operations.

The BeforeSetKey event will fire anytime the OS attempts to update a registry key's metadata.

REG_CE_AFTER_SET_KEY0x00008000LFire after registry key metadata update operations.

The AfterSetKey event will fire after a registry key metadata update request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_VALUE0x00010000LFire before registry value delete operations.

The BeforeDeleteValue event will fire anytime the OS attempts to delete a registry value.

REG_CE_AFTER_DELETE_VALUE0x00020000LFire after registry value delete operations.

The AfterDeleteValue event will fire after a registry value delete request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_VALUE0x00040000LFire before value enumeration operations.

The BeforeEnumerateValue event will fire anytime the OS attempts to enumerate a registry key's values.

REG_CE_AFTER_ENUM_VALUE0x00080000LFire after value enumeration operations.

The AfterEnumerateValue event will fire after a value enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_VALUE0x00100000LFire before registry value query operations.

The BeforeQueryValue event will fire anytime the OS attempts to query a registry value.

REG_CE_AFTER_QUERY_VALUE0x00200000LFire after registry value query operations.

The AfterQueryValue event will fire after a registry value query request has been processed, before the response is returned.

REG_CE_BEFORE_SET_VALUE0x00400000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS attempts to set or update a registry value.

REG_CE_AFTER_SET_VALUE0x00800000LFire after registry value set/update operations.

The AfterSetValue event will fire after a registry value set or update request has been processed, before the response is returned.

REG_CE_BEFORE_GET_KEY_SECURITY0x001000000LFire before get registry key security operations.

The BeforeGetKeySecurity event will fire before the OS queries the security attributes of a registry key.

REG_CE_AFTER_GET_KEY_SECURITY0x002000000LFire after registry value query operations.

The AfterGetKeySecurity event will fire after a get security operation has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY_SECURITY0x004000000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS needs to change the security attributes of a registry key.

REG_CE_AFTER_SET_KEY_SECURITY0x008000000LFire after registry value set/update operations.

The AfterSetValue event will fire after a security attributes change request has been processed, before the response is returned.

REG_CE_ALL-1Fire for all registry operations.

Control Events will fire for all registry operations.

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

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.

AddIgnoredProcessById Method (CBRegistry 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_cbregistry_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).

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

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

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

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

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

AddIgnoredProcessByName Method (CBRegistry 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_cbregistry_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).

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

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

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

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

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

AddPassthroughRule Method (CBRegistry Class)

This method adds a passthrough rule.

Syntax

ANSI (Cross Platform)
bool AddPassthroughRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags);

Unicode (Windows)
INT AddPassthroughRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags);
bool cbfsfilter_cbregistry_addpassthroughrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags);
bool AddPassthroughRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags);

Remarks

This method adds a passthrough rule for the registry keys that matches the specified Mask. Each rule in a ruleset is uniquely identified by its mask; if a rule with the specified mask already exists, the new rule's parameters are merged into it.

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

Passthrough rules exclude matching registry keys from being processed by other filter rules.

The Mask parameter must be a valid registry key mask according to the Registry Key Masks topic. Only the registry keys that match the specified mask will be covered by the rule.

The AccessFlags parameter specifies which access restrictions the class's system driver should lift from matching registry keys. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

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

REG_CE_NONE0Don't fire for any registry operations.

Control Events will not fire for any registry operations.

REG_CE_BEFORE_CREATE_KEY0x00000001LFire before registry key creation operations.

The BeforeCreateKey event will fire anytime the OS attempts to create a registry key.

REG_CE_AFTER_CREATE_KEY0x00000002LFire after registry key creation operations.

The AfterCreateKey event will fire after a registry key creation request has been processed, before the response is returned.

REG_CE_BEFORE_OPEN_KEY0x00000004LFire before registry key open operations.

The BeforeOpenKey event will fire anytime the OS attempts to open a registry key.

REG_CE_AFTER_OPEN_KEY0x00000008LFire after registry key open operations.

The AfterOpenKey event will fire after a registry key open request has been processed, before the response is returned.

REG_CE_BEFORE_CLOSE_KEY0x00000010LFire before registry key close operations.

The BeforeCloseKey event will fire anytime the OS closes a registry key.

REG_CE_AFTER_CLOSE_KEY0x00000020LFire after registry key close operations.

The AfterCloseKey event will fire after a registry key close request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_KEY0x00000040LFire before registry key delete operations.

The BeforeDeleteKey event will fire anytime the OS attempts to delete a registry key.

REG_CE_AFTER_DELETE_KEY0x00000080LFire after registry key delete operations.

The AfterDeleteKey event will fire after a registry key delete request has been processed, before the response is returned.

REG_CE_BEFORE_RENAME_KEY0x00000100LFire before registry key rename operations.

The BeforeRenameKey event will fire anytime the OS attempts to rename a registry key.

REG_CE_AFTER_RENAME_KEY0x00000200LFire after registry key rename operations.

The AfterRenameKey event will fire after a registry key rename request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_KEY0x00000400LFire before subkey enumeration operations.

The BeforeEnumerateKey event will fire anytime the OS attempts to enumerate a registry key's subkeys.

REG_CE_AFTER_ENUM_KEY0x00000800LFire after subkey enumeration operations.

The AfterEnumerateKey event will fire after a subkey enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_KEY0x00001000LFire before registry key metadata retrieval operations.

The BeforeQueryKey event will fire anytime the OS attempts to retrieve a registry key's metadata.

REG_CE_AFTER_QUERY_KEY0x00002000LFire after registry key metadata retrieval operations.

The AfterQueryKey event will fire after a registry key metadata retrieval request has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY0x00004000LFire before registry key metadata update operations.

The BeforeSetKey event will fire anytime the OS attempts to update a registry key's metadata.

REG_CE_AFTER_SET_KEY0x00008000LFire after registry key metadata update operations.

The AfterSetKey event will fire after a registry key metadata update request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_VALUE0x00010000LFire before registry value delete operations.

The BeforeDeleteValue event will fire anytime the OS attempts to delete a registry value.

REG_CE_AFTER_DELETE_VALUE0x00020000LFire after registry value delete operations.

The AfterDeleteValue event will fire after a registry value delete request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_VALUE0x00040000LFire before value enumeration operations.

The BeforeEnumerateValue event will fire anytime the OS attempts to enumerate a registry key's values.

REG_CE_AFTER_ENUM_VALUE0x00080000LFire after value enumeration operations.

The AfterEnumerateValue event will fire after a value enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_VALUE0x00100000LFire before registry value query operations.

The BeforeQueryValue event will fire anytime the OS attempts to query a registry value.

REG_CE_AFTER_QUERY_VALUE0x00200000LFire after registry value query operations.

The AfterQueryValue event will fire after a registry value query request has been processed, before the response is returned.

REG_CE_BEFORE_SET_VALUE0x00400000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS attempts to set or update a registry value.

REG_CE_AFTER_SET_VALUE0x00800000LFire after registry value set/update operations.

The AfterSetValue event will fire after a registry value set or update request has been processed, before the response is returned.

REG_CE_BEFORE_GET_KEY_SECURITY0x001000000LFire before get registry key security operations.

The BeforeGetKeySecurity event will fire before the OS queries the security attributes of a registry key.

REG_CE_AFTER_GET_KEY_SECURITY0x002000000LFire after registry value query operations.

The AfterGetKeySecurity event will fire after a get security operation has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY_SECURITY0x004000000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS needs to change the security attributes of a registry key.

REG_CE_AFTER_SET_KEY_SECURITY0x008000000LFire after registry value set/update operations.

The AfterSetValue event will fire after a security attributes change request has been processed, before the response is returned.

REG_CE_ALL-1Fire for all registry operations.

Control Events will fire for all registry operations.

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

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.

CloseDefaultRulesSnapshot Method (CBRegistry Class)

This method closes the previously created default rules snapshot.

Syntax

ANSI (Cross Platform)
int CloseDefaultRulesSnapshot();

Unicode (Windows)
INT CloseDefaultRulesSnapshot();
int cbfsfilter_cbregistry_closedefaultrulessnapshot(void* lpObj);
int CloseDefaultRulesSnapshot();

Remarks

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

Note: This method cannot be called within events.

The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

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

Config Method (CBRegistry Class)

Sets or retrieves a configuration setting.

Syntax

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

Unicode (Windows)
LPWSTR Config(LPCWSTR lpszConfigurationString);
char* cbfsfilter_cbregistry_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.

CreateDefaultRulesSnapshot Method (CBRegistry Class)

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

Syntax

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

Unicode (Windows)
INT CreateDefaultRulesSnapshot(LPCWSTR lpszProductGUID);
int cbfsfilter_cbregistry_createdefaultrulessnapshot(void* lpObj, const char* lpszProductGUID);
int CreateDefaultRulesSnapshot(const QString& qsProductGUID);

Remarks

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

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

The methods and properties related to rule management are not intended to be used from multiple threads at once. Applications that wish to use said methods and properties from multiple threads (e.g., during the AfterFilterAttachToVolume and AfterFilterDetachFromVolume events) are responsible for employing proper thread synchronization techniques to ensure that manipulation and enumeration of the rule lists both occur in a thread-safe manner.

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

DeleteAllFilterRules Method (CBRegistry Class)

This method deletes all standard filter rules.

Syntax

ANSI (Cross Platform)
bool DeleteAllFilterRules();

Unicode (Windows)
INT DeleteAllFilterRules();
bool cbfsfilter_cbregistry_deleteallfilterrules(void* lpObj);
bool DeleteAllFilterRules();

Remarks

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

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

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

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

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.

DeleteAllPassthroughRules Method (CBRegistry Class)

This method deletes all passthrough rules.

Syntax

ANSI (Cross Platform)
bool DeleteAllPassthroughRules();

Unicode (Windows)
INT DeleteAllPassthroughRules();
bool cbfsfilter_cbregistry_deleteallpassthroughrules(void* lpObj);
bool DeleteAllPassthroughRules();

Remarks

This method deletes all passthrough rules that are currently present.

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

To delete passthrough rules individually, use the DeletePassthroughRule method instead.

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

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.

DeleteDefaultRule Method (CBRegistry Class)

This method deletes a particular default rule.

Syntax

ANSI (Cross Platform)
bool DeleteDefaultRule(const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);

Unicode (Windows)
INT DeleteDefaultRule(LPCWSTR lpszMask, INT iAccessFlags, LPCWSTR lpszProductGUID);
bool cbfsfilter_cbregistry_deletedefaultrule(void* lpObj, const char* lpszMask, int iAccessFlags, const char* lpszProductGUID);
bool DeleteDefaultRule(const QString& qsMask, int iAccessFlags, const QString& qsProductGUID);

Remarks

This method deletes the specified AccessFlags from the default rule identified by Mask and associated with the application identified by ProductGUID. If AccessFlags includes all flags currently present in the rule, then the entire rule is deleted; otherwise, the flags specified by AccessFlags are simply removed from the rule.

If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the registry key mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The AccessFlags parameter specifies which access restrictions should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

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

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

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

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.

DeleteFilterRule Method (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
bool DeleteFilterRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags);

Unicode (Windows)
INT DeleteFilterRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags);
bool cbfsfilter_cbregistry_deletefilterrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags);
bool DeleteFilterRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags);

Remarks

This method deletes the specified AccessFlags or ControlFlags from the standard filter rule or access rule identified by Mask. If the aforementioned parameters include all flags currently present in the rule, then the entire rule is deleted; otherwise, the specified flags are simply removed from the rule.

If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the registry key mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The AccessFlags parameter specifies which access restrictions should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which Control Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

REG_CE_NONE0Don't fire for any registry operations.

Control Events will not fire for any registry operations.

REG_CE_BEFORE_CREATE_KEY0x00000001LFire before registry key creation operations.

The BeforeCreateKey event will fire anytime the OS attempts to create a registry key.

REG_CE_AFTER_CREATE_KEY0x00000002LFire after registry key creation operations.

The AfterCreateKey event will fire after a registry key creation request has been processed, before the response is returned.

REG_CE_BEFORE_OPEN_KEY0x00000004LFire before registry key open operations.

The BeforeOpenKey event will fire anytime the OS attempts to open a registry key.

REG_CE_AFTER_OPEN_KEY0x00000008LFire after registry key open operations.

The AfterOpenKey event will fire after a registry key open request has been processed, before the response is returned.

REG_CE_BEFORE_CLOSE_KEY0x00000010LFire before registry key close operations.

The BeforeCloseKey event will fire anytime the OS closes a registry key.

REG_CE_AFTER_CLOSE_KEY0x00000020LFire after registry key close operations.

The AfterCloseKey event will fire after a registry key close request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_KEY0x00000040LFire before registry key delete operations.

The BeforeDeleteKey event will fire anytime the OS attempts to delete a registry key.

REG_CE_AFTER_DELETE_KEY0x00000080LFire after registry key delete operations.

The AfterDeleteKey event will fire after a registry key delete request has been processed, before the response is returned.

REG_CE_BEFORE_RENAME_KEY0x00000100LFire before registry key rename operations.

The BeforeRenameKey event will fire anytime the OS attempts to rename a registry key.

REG_CE_AFTER_RENAME_KEY0x00000200LFire after registry key rename operations.

The AfterRenameKey event will fire after a registry key rename request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_KEY0x00000400LFire before subkey enumeration operations.

The BeforeEnumerateKey event will fire anytime the OS attempts to enumerate a registry key's subkeys.

REG_CE_AFTER_ENUM_KEY0x00000800LFire after subkey enumeration operations.

The AfterEnumerateKey event will fire after a subkey enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_KEY0x00001000LFire before registry key metadata retrieval operations.

The BeforeQueryKey event will fire anytime the OS attempts to retrieve a registry key's metadata.

REG_CE_AFTER_QUERY_KEY0x00002000LFire after registry key metadata retrieval operations.

The AfterQueryKey event will fire after a registry key metadata retrieval request has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY0x00004000LFire before registry key metadata update operations.

The BeforeSetKey event will fire anytime the OS attempts to update a registry key's metadata.

REG_CE_AFTER_SET_KEY0x00008000LFire after registry key metadata update operations.

The AfterSetKey event will fire after a registry key metadata update request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_VALUE0x00010000LFire before registry value delete operations.

The BeforeDeleteValue event will fire anytime the OS attempts to delete a registry value.

REG_CE_AFTER_DELETE_VALUE0x00020000LFire after registry value delete operations.

The AfterDeleteValue event will fire after a registry value delete request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_VALUE0x00040000LFire before value enumeration operations.

The BeforeEnumerateValue event will fire anytime the OS attempts to enumerate a registry key's values.

REG_CE_AFTER_ENUM_VALUE0x00080000LFire after value enumeration operations.

The AfterEnumerateValue event will fire after a value enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_VALUE0x00100000LFire before registry value query operations.

The BeforeQueryValue event will fire anytime the OS attempts to query a registry value.

REG_CE_AFTER_QUERY_VALUE0x00200000LFire after registry value query operations.

The AfterQueryValue event will fire after a registry value query request has been processed, before the response is returned.

REG_CE_BEFORE_SET_VALUE0x00400000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS attempts to set or update a registry value.

REG_CE_AFTER_SET_VALUE0x00800000LFire after registry value set/update operations.

The AfterSetValue event will fire after a registry value set or update request has been processed, before the response is returned.

REG_CE_BEFORE_GET_KEY_SECURITY0x001000000LFire before get registry key security operations.

The BeforeGetKeySecurity event will fire before the OS queries the security attributes of a registry key.

REG_CE_AFTER_GET_KEY_SECURITY0x002000000LFire after registry value query operations.

The AfterGetKeySecurity event will fire after a get security operation has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY_SECURITY0x004000000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS needs to change the security attributes of a registry key.

REG_CE_AFTER_SET_KEY_SECURITY0x008000000LFire after registry value set/update operations.

The AfterSetValue event will fire after a security attributes change request has been processed, before the response is returned.

REG_CE_ALL-1Fire for all registry operations.

Control Events will fire for all registry operations.

To delete all standard filter rules and access rules, use the DeleteAllFilterRules method instead.

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

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.

DeletePassthroughRule Method (CBRegistry Class)

This method deletes a particular passthrough rule.

Syntax

ANSI (Cross Platform)
bool DeletePassthroughRule(const char* lpszMask, int iAccessFlags, int64 lControlFlags);

Unicode (Windows)
INT DeletePassthroughRule(LPCWSTR lpszMask, INT iAccessFlags, LONG64 lControlFlags);
bool cbfsfilter_cbregistry_deletepassthroughrule(void* lpObj, const char* lpszMask, int iAccessFlags, int64 lControlFlags);
bool DeletePassthroughRule(const QString& qsMask, int iAccessFlags, qint64 lControlFlags);

Remarks

This method deletes the specified AccessFlags or ControlFlags from the passthrough rule identified by Mask. If the aforementioned parameters include all flags currently present in the rule, then the entire rule is deleted; otherwise, the specified flags are simply removed from the rule.

If the flags or this rule are deleted successfully, this method returns true; otherwise, it returns false.

The Mask parameter must be the registry key mask of an existing rule. If a rule with the specified mask cannot be found, this method will fail.

The AccessFlags parameter specifies which access restrictions should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

The ControlFlags parameter specifies which Control Event flags should be removed from the rule. The value passed for this parameter should be constructed by ORing together zero or more of the following flags:

REG_CE_NONE0Don't fire for any registry operations.

Control Events will not fire for any registry operations.

REG_CE_BEFORE_CREATE_KEY0x00000001LFire before registry key creation operations.

The BeforeCreateKey event will fire anytime the OS attempts to create a registry key.

REG_CE_AFTER_CREATE_KEY0x00000002LFire after registry key creation operations.

The AfterCreateKey event will fire after a registry key creation request has been processed, before the response is returned.

REG_CE_BEFORE_OPEN_KEY0x00000004LFire before registry key open operations.

The BeforeOpenKey event will fire anytime the OS attempts to open a registry key.

REG_CE_AFTER_OPEN_KEY0x00000008LFire after registry key open operations.

The AfterOpenKey event will fire after a registry key open request has been processed, before the response is returned.

REG_CE_BEFORE_CLOSE_KEY0x00000010LFire before registry key close operations.

The BeforeCloseKey event will fire anytime the OS closes a registry key.

REG_CE_AFTER_CLOSE_KEY0x00000020LFire after registry key close operations.

The AfterCloseKey event will fire after a registry key close request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_KEY0x00000040LFire before registry key delete operations.

The BeforeDeleteKey event will fire anytime the OS attempts to delete a registry key.

REG_CE_AFTER_DELETE_KEY0x00000080LFire after registry key delete operations.

The AfterDeleteKey event will fire after a registry key delete request has been processed, before the response is returned.

REG_CE_BEFORE_RENAME_KEY0x00000100LFire before registry key rename operations.

The BeforeRenameKey event will fire anytime the OS attempts to rename a registry key.

REG_CE_AFTER_RENAME_KEY0x00000200LFire after registry key rename operations.

The AfterRenameKey event will fire after a registry key rename request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_KEY0x00000400LFire before subkey enumeration operations.

The BeforeEnumerateKey event will fire anytime the OS attempts to enumerate a registry key's subkeys.

REG_CE_AFTER_ENUM_KEY0x00000800LFire after subkey enumeration operations.

The AfterEnumerateKey event will fire after a subkey enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_KEY0x00001000LFire before registry key metadata retrieval operations.

The BeforeQueryKey event will fire anytime the OS attempts to retrieve a registry key's metadata.

REG_CE_AFTER_QUERY_KEY0x00002000LFire after registry key metadata retrieval operations.

The AfterQueryKey event will fire after a registry key metadata retrieval request has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY0x00004000LFire before registry key metadata update operations.

The BeforeSetKey event will fire anytime the OS attempts to update a registry key's metadata.

REG_CE_AFTER_SET_KEY0x00008000LFire after registry key metadata update operations.

The AfterSetKey event will fire after a registry key metadata update request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_VALUE0x00010000LFire before registry value delete operations.

The BeforeDeleteValue event will fire anytime the OS attempts to delete a registry value.

REG_CE_AFTER_DELETE_VALUE0x00020000LFire after registry value delete operations.

The AfterDeleteValue event will fire after a registry value delete request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_VALUE0x00040000LFire before value enumeration operations.

The BeforeEnumerateValue event will fire anytime the OS attempts to enumerate a registry key's values.

REG_CE_AFTER_ENUM_VALUE0x00080000LFire after value enumeration operations.

The AfterEnumerateValue event will fire after a value enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_VALUE0x00100000LFire before registry value query operations.

The BeforeQueryValue event will fire anytime the OS attempts to query a registry value.

REG_CE_AFTER_QUERY_VALUE0x00200000LFire after registry value query operations.

The AfterQueryValue event will fire after a registry value query request has been processed, before the response is returned.

REG_CE_BEFORE_SET_VALUE0x00400000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS attempts to set or update a registry value.

REG_CE_AFTER_SET_VALUE0x00800000LFire after registry value set/update operations.

The AfterSetValue event will fire after a registry value set or update request has been processed, before the response is returned.

REG_CE_BEFORE_GET_KEY_SECURITY0x001000000LFire before get registry key security operations.

The BeforeGetKeySecurity event will fire before the OS queries the security attributes of a registry key.

REG_CE_AFTER_GET_KEY_SECURITY0x002000000LFire after registry value query operations.

The AfterGetKeySecurity event will fire after a get security operation has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY_SECURITY0x004000000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS needs to change the security attributes of a registry key.

REG_CE_AFTER_SET_KEY_SECURITY0x008000000LFire after registry value set/update operations.

The AfterSetValue event will fire after a security attributes change request has been processed, before the response is returned.

REG_CE_ALL-1Fire for all registry operations.

Control Events will fire for all registry operations.

To delete all passthrough rules, use the DeleteAllPassthroughRules method instead.

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

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.

GetDriverStatus Method (CBRegistry 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_cbregistry_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_PRESENT0x00000000The specified module is not present on the system.

Note: This functionality is only available in Windows.

MODULE_STATUS_STOPPED0x00000001The specified module is in the Stopped state.

Note: This functionality is only available in Windows.

MODULE_STATUS_RUNNING0x00000004The 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:

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 (CBRegistry 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_cbregistry_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.

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:

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.

GetOriginatorProcessId Method (CBRegistry Class)

This method retrieves the process Id (PID) that initiated the operation.

Syntax

ANSI (Cross Platform)
int GetOriginatorProcessId();

Unicode (Windows)
INT GetOriginatorProcessId();
int cbfsfilter_cbregistry_getoriginatorprocessid(void* lpObj);
int GetOriginatorProcessId();

Remarks

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

Note: PIDs are not unique and may be reused by different processes over time (although in practice, this is uncommon).

Note: This method can be called only within events.

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.

GetOriginatorProcessName Method (CBRegistry Class)

This method retrieves the name of the process that initiated the operation.

Syntax

ANSI (Cross Platform)
char* GetOriginatorProcessName();

Unicode (Windows)
LPWSTR GetOriginatorProcessName();
char* cbfsfilter_cbregistry_getoriginatorprocessname(void* lpObj);
QString GetOriginatorProcessName();

Remarks

This method can be called within events fired for registry operations to retrieve the name of the process that initiated the operation. If the query fails, this method returns empty string.

Note: This method can be called only within events.

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.

GetOriginatorThreadId Method (CBRegistry Class)

This method retrieves the thread Id that initiated the operation.

Syntax

ANSI (Cross Platform)
int GetOriginatorThreadId();

Unicode (Windows)
INT GetOriginatorThreadId();
int cbfsfilter_cbregistry_getoriginatorthreadid(void* lpObj);
int GetOriginatorThreadId();

Remarks

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

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

Note: This method can be called only within events.

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.

GetOriginatorToken Method (CBRegistry 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_cbregistry_getoriginatortoken(void* lpObj);
qint64 GetOriginatorToken();

Remarks

This method can be called within events fired for registry operations to retrieve the security token associated with the process that initiated the operation. If the query fails, this method returns INVALID_HANDLE_VALUE.

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

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

Note: This method can be called only within events.

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.

Initialize Method (CBRegistry Class)

This method initializes the class.

Syntax

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

Unicode (Windows)
INT Initialize(LPCWSTR lpszProductGUID);
int cbfsfilter_cbregistry_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.

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:

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

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

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

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:

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_VERSIONS0x00000001Uninstall drivers from previous class versions (e.g., 2017).

INSTALL_KEEP_START_TYPE0x00000002Keep 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_VERSION0x00000004Install the driver file when its version and build number is the same as the version of the already installed driver.

INSTALL_REQUESTS_VIA_DRIVER_STACK0x00001000Whether 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_FILES0x00010000Whether 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_CHECK0x00020000Whether 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_CHECKS0x00040000Whether 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 (CBRegistry 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_cbregistry_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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ResetTimeout Method (CBRegistry 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_cbregistry_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++)

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.

ShutdownSystem Method (CBRegistry 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_cbregistry_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++)

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.

StartFilter Method (CBRegistry Class)

This method starts filtering registry operations.

Syntax

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

Unicode (Windows)
INT StartFilter(INT iTimeout);
int cbfsfilter_cbregistry_startfilter(void* lpObj, int iTimeout);
int StartFilter(int iTimeout);

Remarks

This method attaches the filter, causing the class's driver to start filtering registry operations according to the filter rules currently present. Rules can be added and removed both before and after this method is called, so long as the Initialize method is called before doing anything else.

This method can fail for a number of reasons, including (but not limited to) the following:

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

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

StopFilter Method (CBRegistry Class)

This method stops filtering registry operations.

Syntax

ANSI (Cross Platform)
int StopFilter();

Unicode (Windows)
INT StopFilter();
int cbfsfilter_cbregistry_stopfilter(void* lpObj);
int StopFilter();

Remarks

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

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

SuspendDefaultRules Method (CBRegistry Class)

This method suspends all default rules until the application exits.

Syntax

ANSI (Cross Platform)
bool SuspendDefaultRules(const char* lpszProductGUID);

Unicode (Windows)
INT SuspendDefaultRules(LPCWSTR lpszProductGUID);
bool cbfsfilter_cbregistry_suspenddefaultrules(void* lpObj, const char* lpszProductGUID);
bool SuspendDefaultRules(const QString& qsProductGUID);

Remarks

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

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

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

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.

ToggleProcessProtection Method (CBRegistry Class)

This method enables or disables termination protection for the application.

Syntax

ANSI (Cross Platform)
bool ToggleProcessProtection(int bEnabled);

Unicode (Windows)
INT ToggleProcessProtection(BOOL bEnabled);
bool cbfsfilter_cbregistry_toggleprocessprotection(void* lpObj, int bEnabled);
bool ToggleProcessProtection(bool bEnabled);

Remarks

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

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

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

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.

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

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.

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_PREVIOUS0x00000001Uninstall modules from previous product versions.

Note: This functionality is only available in Windows.

UNINSTALL_VERSION_CURRENT0x00000002Uninstall modules from the current product version.

Note: This functionality is only available in Windows.

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

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.

AfterCloseKey Event (CBRegistry Class)

This event fires after a registry key is closed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterCloseKey(CBRegistryAfterCloseKeyEventParams *e);
typedef struct {
void *KeyContext;
int ResultCode; int reserved; } CBRegistryAfterCloseKeyEventParams;
Unicode (Windows) virtual INT FireAfterCloseKey(CBRegistryAfterCloseKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT ResultCode; INT reserved; } CBRegistryAfterCloseKeyEventParams;
#define EID_CBREGISTRY_AFTERCLOSEKEY 1

virtual INT CBFSFILTER_CALL FireAfterCloseKey(LPVOID &lpKeyContext, INT &iResultCode);
class CBRegistryAfterCloseKeyEventParams {
public:
  void *KeyContext();

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterCloseKey(CBRegistryAfterCloseKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterCloseKey(CBRegistryAfterCloseKeyEventParams *e) {...}

Remarks

This event fires after a registry key is closed.

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterCreateKey Event (CBRegistry Class)

This event fires after a registry key is created.

Syntax

ANSI (Cross Platform)
virtual int FireAfterCreateKey(CBRegistryAfterCreateKeyEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int64 *pKeyHandle;
void *KeyHandleContext;
int GrantedAccess;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterCreateKeyEventParams;
Unicode (Windows) virtual INT FireAfterCreateKey(CBRegistryAfterCreateKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
LONG64 *pKeyHandle;
LPVOID KeyHandleContext;
INT GrantedAccess;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterCreateKeyEventParams;
#define EID_CBREGISTRY_AFTERCREATEKEY 2

virtual INT CBFSFILTER_CALL FireAfterCreateKey(LPVOID &lpKeyContext, INT &iStatus, LONG64 &lKeyHandle, LPVOID &lpKeyHandleContext, INT &iGrantedAccess, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterCreateKeyEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  qint64 KeyHandle();
  void SetKeyHandle(qint64 lKeyHandle);

  void *KeyHandleContext();
  void SetKeyHandleContext(void *lpKeyHandleContext);

  int GrantedAccess();
  void SetGrantedAccess(int iGrantedAccess);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterCreateKey(CBRegistryAfterCreateKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterCreateKey(CBRegistryAfterCreateKeyEventParams *e) {...}

Remarks

This event fires after a registry key is created.

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterDeleteKey Event (CBRegistry Class)

This event fires after a registry key is deleted.

Syntax

ANSI (Cross Platform)
virtual int FireAfterDeleteKey(CBRegistryAfterDeleteKeyEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterDeleteKeyEventParams;
Unicode (Windows) virtual INT FireAfterDeleteKey(CBRegistryAfterDeleteKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterDeleteKeyEventParams;
#define EID_CBREGISTRY_AFTERDELETEKEY 3

virtual INT CBFSFILTER_CALL FireAfterDeleteKey(LPVOID &lpKeyContext, INT &iStatus, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterDeleteKeyEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterDeleteKey(CBRegistryAfterDeleteKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterDeleteKey(CBRegistryAfterDeleteKeyEventParams *e) {...}

Remarks

This event fires after a registry key is deleted.

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterDeleteValue Event (CBRegistry Class)

This event fires after a registry value is deleted.

Syntax

ANSI (Cross Platform)
virtual int FireAfterDeleteValue(CBRegistryAfterDeleteValueEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterDeleteValueEventParams;
Unicode (Windows) virtual INT FireAfterDeleteValue(CBRegistryAfterDeleteValueEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterDeleteValueEventParams;
#define EID_CBREGISTRY_AFTERDELETEVALUE 4

virtual INT CBFSFILTER_CALL FireAfterDeleteValue(LPVOID &lpKeyContext, INT &iStatus, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterDeleteValueEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterDeleteValue(CBRegistryAfterDeleteValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterDeleteValue(CBRegistryAfterDeleteValueEventParams *e) {...}

Remarks

This event fires after a registry value is deleted.

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterEnumerateKey Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterEnumerateKey(CBRegistryAfterEnumerateKeyEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int Index;
int ValidFields;
int64 *pLastWriteTime;
char *Name; int lenName;
char *ClassName; int lenClassName;
int SubKeys;
int MaxNameLength;
int MaxClassNameLength;
int Values;
int MaxValueNameLength;
int MaxValueDataSize;
int VirtualizationCandidate;
int VirtualizationEnabled;
int VirtualTarget;
int VirtualStore;
int VirtualSource;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterEnumerateKeyEventParams;
Unicode (Windows) virtual INT FireAfterEnumerateKey(CBRegistryAfterEnumerateKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
INT Index;
INT ValidFields;
LONG64 *pLastWriteTime;
LPWSTR Name; INT lenName;
LPWSTR ClassName; INT lenClassName;
INT SubKeys;
INT MaxNameLength;
INT MaxClassNameLength;
INT Values;
INT MaxValueNameLength;
INT MaxValueDataSize;
BOOL VirtualizationCandidate;
BOOL VirtualizationEnabled;
BOOL VirtualTarget;
BOOL VirtualStore;
BOOL VirtualSource;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterEnumerateKeyEventParams;
#define EID_CBREGISTRY_AFTERENUMERATEKEY 5

virtual INT CBFSFILTER_CALL FireAfterEnumerateKey(LPVOID &lpKeyContext, INT &iStatus, INT &iIndex, INT &iValidFields, LONG64 &lLastWriteTime, LPWSTR &lpName, INT &lenName, LPWSTR &lpClassName, INT &lenClassName, INT &iSubKeys, INT &iMaxNameLength, INT &iMaxClassNameLength, INT &iValues, INT &iMaxValueNameLength, INT &iMaxValueDataSize, BOOL &bVirtualizationCandidate, BOOL &bVirtualizationEnabled, BOOL &bVirtualTarget, BOOL &bVirtualStore, BOOL &bVirtualSource, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterEnumerateKeyEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  int Index();

  int ValidFields();

  const QDateTime &LastWriteTime();
  void SetLastWriteTime(const QDateTime &qdtLastWriteTime);

  const QString &Name();
  bool SetName(const QString &lpName);

  const QString &ClassName();
  bool SetClassName(const QString &lpClassName);

  int SubKeys();
  void SetSubKeys(int iSubKeys);

  int MaxNameLength();
  void SetMaxNameLength(int iMaxNameLength);

  int MaxClassNameLength();
  void SetMaxClassNameLength(int iMaxClassNameLength);

  int Values();
  void SetValues(int iValues);

  int MaxValueNameLength();
  void SetMaxValueNameLength(int iMaxValueNameLength);

  int MaxValueDataSize();
  void SetMaxValueDataSize(int iMaxValueDataSize);

  bool VirtualizationCandidate();
  void SetVirtualizationCandidate(bool bVirtualizationCandidate);

  bool VirtualizationEnabled();
  void SetVirtualizationEnabled(bool bVirtualizationEnabled);

  bool VirtualTarget();
  void SetVirtualTarget(bool bVirtualTarget);

  bool VirtualStore();
  void SetVirtualStore(bool bVirtualStore);

  bool VirtualSource();
  void SetVirtualSource(bool bVirtualSource);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterEnumerateKey(CBRegistryAfterEnumerateKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterEnumerateKey(CBRegistryAfterEnumerateKeyEventParams *e) {...}

Remarks

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

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

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

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

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

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

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

REG_KEYFIELD_LASTWRITETIME1A registry key's last write time.

REG_KEYFIELD_NAME2A registry key's name.

REG_KEYFIELD_MAXNAMELENGTH4A registry key's longest subkey name.

REG_KEYFIELD_CLASSNAME8A registry key's class name.

REG_KEYFIELD_MAXCLASSNAMELENGTH16A registry key's longest subkey class name.

REG_KEYFIELD_SUBKEYS32The number of subkeys a registry key has.

REG_KEYFIELD_VALUES64The number of values a registry key has.

REG_KEYFIELD_MAXVALUENAMELENGTH128A registry key's longest value name.

REG_KEYFIELD_MAXVALUEDATASIZE256A registry key's largest value data size.

REG_KEYFIELD_VIRTUALIZATIONINFO512A registry key's virtualization information.

The LastWriteTime parameter specifies when the key was last changed, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters. Note that the name, if set, should be copied to Name; set lenName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters. Note that the class name, if set, should be copied to ClassName; set lenClassName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterEnumerateValue Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterEnumerateValue(CBRegistryAfterEnumerateValueEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int Index;
int ValidFields;
char *ValueName; int lenValueName;
int ValueType;
int64 *pIntegerValue;
char *StringValue; int lenStringValue;
void *BinaryValue;
int MaxBinaryValueSize;
int BinaryValueSize;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterEnumerateValueEventParams;
Unicode (Windows) virtual INT FireAfterEnumerateValue(CBRegistryAfterEnumerateValueEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
INT Index;
INT ValidFields;
LPWSTR ValueName; INT lenValueName;
INT ValueType;
LONG64 *pIntegerValue;
LPWSTR StringValue; INT lenStringValue;
LPVOID BinaryValue;
INT MaxBinaryValueSize;
INT BinaryValueSize;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterEnumerateValueEventParams;
#define EID_CBREGISTRY_AFTERENUMERATEVALUE 6

virtual INT CBFSFILTER_CALL FireAfterEnumerateValue(LPVOID &lpKeyContext, INT &iStatus, INT &iIndex, INT &iValidFields, LPWSTR &lpValueName, INT &lenValueName, INT &iValueType, LONG64 &lIntegerValue, LPWSTR &lpStringValue, INT &lenStringValue, LPVOID &lpBinaryValue, INT &iMaxBinaryValueSize, INT &iBinaryValueSize, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterEnumerateValueEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  int Index();

  int ValidFields();

  const QString &ValueName();
  bool SetValueName(const QString &lpValueName);

  int ValueType();
  void SetValueType(int iValueType);

  qint64 IntegerValue();
  void SetIntegerValue(qint64 lIntegerValue);

  const QString &StringValue();
  bool SetStringValue(const QString &lpStringValue);

  void *BinaryValue();

  int MaxBinaryValueSize();

  int BinaryValueSize();
  void SetBinaryValueSize(int iBinaryValueSize);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterEnumerateValue(CBRegistryAfterEnumerateValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterEnumerateValue(CBRegistryAfterEnumerateValueEventParams *e) {...}

Remarks

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

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

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

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

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

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

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

REG_VALUEFIELD_TYPE1A registry value's type.

REG_VALUEFIELD_NAME2A registry value's name.

REG_VALUEFIELD_DATA4A registry value's data.

The ValueName parameter specifies the registry value's name. Note that the name, if set, should be copied to ValueName; set lenValueName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

REG_VALUETYPE_SZ1A unicode string.

REG_VALUETYPE_EXPAND_SZ2A unicode string that contains environmental variable references.

REG_VALUETYPE_BINARY3Binary data.

REG_VALUETYPE_DWORD4A 32-bit number.

REG_VALUETYPE_MULTI_SZ7Multiple unicode strings.

REG_VALUETYPE_QWORD11A 64-bit number.

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

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ. Note that data should be copied to StringValue; set lenStringValue to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterGetKeySecurity Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterGetKeySecurity(CBRegistryAfterGetKeySecurityEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int SecurityInformation;
void *SecurityDescriptor;
int Length;
int LengthNeeded;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterGetKeySecurityEventParams;
Unicode (Windows) virtual INT FireAfterGetKeySecurity(CBRegistryAfterGetKeySecurityEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
INT SecurityInformation;
LPVOID SecurityDescriptor;
INT Length;
INT LengthNeeded;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterGetKeySecurityEventParams;
#define EID_CBREGISTRY_AFTERGETKEYSECURITY 7

virtual INT CBFSFILTER_CALL FireAfterGetKeySecurity(LPVOID &lpKeyContext, INT &iStatus, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iLengthNeeded, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterGetKeySecurityEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  int SecurityInformation();

  void *SecurityDescriptor();

  int Length();

  int LengthNeeded();
  void SetLengthNeeded(int iLengthNeeded);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterGetKeySecurity(CBRegistryAfterGetKeySecurityEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterGetKeySecurity(CBRegistryAfterGetKeySecurityEventParams *e) {...}

Remarks

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

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

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

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

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

The SecurityInformation parameter indicates which pieces of security information were requested. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that, if the request was successful, contains the requested security information. The Length parameter reflects the length of the data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterOpenKey Event (CBRegistry Class)

This event fires after a registry key is opened.

Syntax

ANSI (Cross Platform)
virtual int FireAfterOpenKey(CBRegistryAfterOpenKeyEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int64 *pKeyHandle;
void *KeyHandleContext;
int GrantedAccess;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterOpenKeyEventParams;
Unicode (Windows) virtual INT FireAfterOpenKey(CBRegistryAfterOpenKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
LONG64 *pKeyHandle;
LPVOID KeyHandleContext;
INT GrantedAccess;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterOpenKeyEventParams;
#define EID_CBREGISTRY_AFTEROPENKEY 8

virtual INT CBFSFILTER_CALL FireAfterOpenKey(LPVOID &lpKeyContext, INT &iStatus, LONG64 &lKeyHandle, LPVOID &lpKeyHandleContext, INT &iGrantedAccess, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterOpenKeyEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  qint64 KeyHandle();
  void SetKeyHandle(qint64 lKeyHandle);

  void *KeyHandleContext();
  void SetKeyHandleContext(void *lpKeyHandleContext);

  int GrantedAccess();
  void SetGrantedAccess(int iGrantedAccess);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterOpenKey(CBRegistryAfterOpenKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterOpenKey(CBRegistryAfterOpenKeyEventParams *e) {...}

Remarks

This event fires after a registry key is opened.

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterQueryKey Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterQueryKey(CBRegistryAfterQueryKeyEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int ValidFields;
int64 *pLastWriteTime;
char *Name; int lenName;
char *ClassName; int lenClassName;
int SubKeys;
int MaxNameLength;
int MaxClassNameLength;
int Values;
int MaxValueNameLength;
int MaxValueDataSize;
int VirtualizationCandidate;
int VirtualizationEnabled;
int VirtualTarget;
int VirtualStore;
int VirtualSource;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterQueryKeyEventParams;
Unicode (Windows) virtual INT FireAfterQueryKey(CBRegistryAfterQueryKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
INT ValidFields;
LONG64 *pLastWriteTime;
LPWSTR Name; INT lenName;
LPWSTR ClassName; INT lenClassName;
INT SubKeys;
INT MaxNameLength;
INT MaxClassNameLength;
INT Values;
INT MaxValueNameLength;
INT MaxValueDataSize;
BOOL VirtualizationCandidate;
BOOL VirtualizationEnabled;
BOOL VirtualTarget;
BOOL VirtualStore;
BOOL VirtualSource;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterQueryKeyEventParams;
#define EID_CBREGISTRY_AFTERQUERYKEY 9

virtual INT CBFSFILTER_CALL FireAfterQueryKey(LPVOID &lpKeyContext, INT &iStatus, INT &iValidFields, LONG64 &lLastWriteTime, LPWSTR &lpName, INT &lenName, LPWSTR &lpClassName, INT &lenClassName, INT &iSubKeys, INT &iMaxNameLength, INT &iMaxClassNameLength, INT &iValues, INT &iMaxValueNameLength, INT &iMaxValueDataSize, BOOL &bVirtualizationCandidate, BOOL &bVirtualizationEnabled, BOOL &bVirtualTarget, BOOL &bVirtualStore, BOOL &bVirtualSource, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterQueryKeyEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  int ValidFields();

  const QDateTime &LastWriteTime();
  void SetLastWriteTime(const QDateTime &qdtLastWriteTime);

  const QString &Name();
  bool SetName(const QString &lpName);

  const QString &ClassName();
  bool SetClassName(const QString &lpClassName);

  int SubKeys();
  void SetSubKeys(int iSubKeys);

  int MaxNameLength();
  void SetMaxNameLength(int iMaxNameLength);

  int MaxClassNameLength();
  void SetMaxClassNameLength(int iMaxClassNameLength);

  int Values();
  void SetValues(int iValues);

  int MaxValueNameLength();
  void SetMaxValueNameLength(int iMaxValueNameLength);

  int MaxValueDataSize();
  void SetMaxValueDataSize(int iMaxValueDataSize);

  bool VirtualizationCandidate();
  void SetVirtualizationCandidate(bool bVirtualizationCandidate);

  bool VirtualizationEnabled();
  void SetVirtualizationEnabled(bool bVirtualizationEnabled);

  bool VirtualTarget();
  void SetVirtualTarget(bool bVirtualTarget);

  bool VirtualStore();
  void SetVirtualStore(bool bVirtualStore);

  bool VirtualSource();
  void SetVirtualSource(bool bVirtualSource);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterQueryKey(CBRegistryAfterQueryKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterQueryKey(CBRegistryAfterQueryKeyEventParams *e) {...}

Remarks

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

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

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

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

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

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

REG_KEYFIELD_LASTWRITETIME1A registry key's last write time.

REG_KEYFIELD_NAME2A registry key's name.

REG_KEYFIELD_MAXNAMELENGTH4A registry key's longest subkey name.

REG_KEYFIELD_CLASSNAME8A registry key's class name.

REG_KEYFIELD_MAXCLASSNAMELENGTH16A registry key's longest subkey class name.

REG_KEYFIELD_SUBKEYS32The number of subkeys a registry key has.

REG_KEYFIELD_VALUES64The number of values a registry key has.

REG_KEYFIELD_MAXVALUENAMELENGTH128A registry key's longest value name.

REG_KEYFIELD_MAXVALUEDATASIZE256A registry key's largest value data size.

REG_KEYFIELD_VIRTUALIZATIONINFO512A registry key's virtualization information.

The LastWriteTime parameter specifies when the key was last changed, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters. Note that the name, if set, should be copied to Name; set lenName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters. Note that the class name, if set, should be copied to ClassName; set lenClassName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterQueryValue Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterQueryValue(CBRegistryAfterQueryValueEventParams *e);
typedef struct {
void *KeyContext;
int Status;
const char *ValueName;
int ValidFields;
int ValueType;
int64 *pIntegerValue;
char *StringValue; int lenStringValue;
void *BinaryValue;
int MaxBinaryValueSize;
int BinaryValueSize;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterQueryValueEventParams;
Unicode (Windows) virtual INT FireAfterQueryValue(CBRegistryAfterQueryValueEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
LPCWSTR ValueName;
INT ValidFields;
INT ValueType;
LONG64 *pIntegerValue;
LPWSTR StringValue; INT lenStringValue;
LPVOID BinaryValue;
INT MaxBinaryValueSize;
INT BinaryValueSize;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterQueryValueEventParams;
#define EID_CBREGISTRY_AFTERQUERYVALUE 10

virtual INT CBFSFILTER_CALL FireAfterQueryValue(LPVOID &lpKeyContext, INT &iStatus, LPWSTR &lpszValueName, INT &iValidFields, INT &iValueType, LONG64 &lIntegerValue, LPWSTR &lpStringValue, INT &lenStringValue, LPVOID &lpBinaryValue, INT &iMaxBinaryValueSize, INT &iBinaryValueSize, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterQueryValueEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  const QString &ValueName();

  int ValidFields();

  int ValueType();
  void SetValueType(int iValueType);

  qint64 IntegerValue();
  void SetIntegerValue(qint64 lIntegerValue);

  const QString &StringValue();
  bool SetStringValue(const QString &lpStringValue);

  void *BinaryValue();

  int MaxBinaryValueSize();

  int BinaryValueSize();
  void SetBinaryValueSize(int iBinaryValueSize);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterQueryValue(CBRegistryAfterQueryValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterQueryValue(CBRegistryAfterQueryValueEventParams *e) {...}

Remarks

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

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

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

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

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

The ValueName parameter reflects the name of the registry value.

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

REG_VALUEFIELD_TYPE1A registry value's type.

REG_VALUEFIELD_NAME2A registry value's name.

REG_VALUEFIELD_DATA4A registry value's data.

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

REG_VALUETYPE_SZ1A unicode string.

REG_VALUETYPE_EXPAND_SZ2A unicode string that contains environmental variable references.

REG_VALUETYPE_BINARY3Binary data.

REG_VALUETYPE_DWORD4A 32-bit number.

REG_VALUETYPE_MULTI_SZ7Multiple unicode strings.

REG_VALUETYPE_QWORD11A 64-bit number.

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

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ. Note that data should be copied to StringValue; set lenStringValue to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterRenameKey Event (CBRegistry Class)

This event fires after a registry key is renamed.

Syntax

ANSI (Cross Platform)
virtual int FireAfterRenameKey(CBRegistryAfterRenameKeyEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterRenameKeyEventParams;
Unicode (Windows) virtual INT FireAfterRenameKey(CBRegistryAfterRenameKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterRenameKeyEventParams;
#define EID_CBREGISTRY_AFTERRENAMEKEY 11

virtual INT CBFSFILTER_CALL FireAfterRenameKey(LPVOID &lpKeyContext, INT &iStatus, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterRenameKeyEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterRenameKey(CBRegistryAfterRenameKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterRenameKey(CBRegistryAfterRenameKeyEventParams *e) {...}

Remarks

This event fires after a registry key is renamed.

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterSetKey Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetKey(CBRegistryAfterSetKeyEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterSetKeyEventParams;
Unicode (Windows) virtual INT FireAfterSetKey(CBRegistryAfterSetKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterSetKeyEventParams;
#define EID_CBREGISTRY_AFTERSETKEY 12

virtual INT CBFSFILTER_CALL FireAfterSetKey(LPVOID &lpKeyContext, INT &iStatus, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterSetKeyEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetKey(CBRegistryAfterSetKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterSetKey(CBRegistryAfterSetKeyEventParams *e) {...}

Remarks

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterSetKeySecurity Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetKeySecurity(CBRegistryAfterSetKeySecurityEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int SecurityInformation;
const void *SecurityDescriptor;
int Length;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterSetKeySecurityEventParams;
Unicode (Windows) virtual INT FireAfterSetKeySecurity(CBRegistryAfterSetKeySecurityEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
INT SecurityInformation;
LPCVOID SecurityDescriptor;
INT Length;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterSetKeySecurityEventParams;
#define EID_CBREGISTRY_AFTERSETKEYSECURITY 13

virtual INT CBFSFILTER_CALL FireAfterSetKeySecurity(LPVOID &lpKeyContext, INT &iStatus, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterSetKeySecurityEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  int SecurityInformation();

  const void *SecurityDescriptor();

  int Length();

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetKeySecurity(CBRegistryAfterSetKeySecurityEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterSetKeySecurity(CBRegistryAfterSetKeySecurityEventParams *e) {...}

Remarks

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

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

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

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

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

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, were to be set. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that contains the new security information. The Length parameter reflects the length of this data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

AfterSetValue Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireAfterSetValue(CBRegistryAfterSetValueEventParams *e);
typedef struct {
void *KeyContext;
int Status;
int Processed;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryAfterSetValueEventParams;
Unicode (Windows) virtual INT FireAfterSetValue(CBRegistryAfterSetValueEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Status;
BOOL Processed;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryAfterSetValueEventParams;
#define EID_CBREGISTRY_AFTERSETVALUE 14

virtual INT CBFSFILTER_CALL FireAfterSetValue(LPVOID &lpKeyContext, INT &iStatus, BOOL &bProcessed, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryAfterSetValueEventParams {
public:
  void *KeyContext();

  int Status();
  void SetStatus(int iStatus);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void AfterSetValue(CBRegistryAfterSetValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireAfterSetValue(CBRegistryAfterSetValueEventParams *e) {...}

Remarks

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeCloseKey Event (CBRegistry Class)

This event fires before a registry key is closed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeCloseKey(CBRegistryBeforeCloseKeyEventParams *e);
typedef struct {
void *KeyContext;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeCloseKeyEventParams;
Unicode (Windows) virtual INT FireBeforeCloseKey(CBRegistryBeforeCloseKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeCloseKeyEventParams;
#define EID_CBREGISTRY_BEFORECLOSEKEY 15

virtual INT CBFSFILTER_CALL FireBeforeCloseKey(LPVOID &lpKeyContext, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeCloseKeyEventParams {
public:
  void *KeyContext();

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeCloseKey(CBRegistryBeforeCloseKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeCloseKey(CBRegistryBeforeCloseKeyEventParams *e) {...}

Remarks

This event fires before a registry key is closed.

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeCreateKey Event (CBRegistry Class)

This event fires before a registry key is created.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeCreateKey(CBRegistryBeforeCreateKeyEventParams *e);
typedef struct {
const char *FullName;
int DesiredAccess;
int64 *pKeyHandle;
void *KeyHandleContext;
int64 *pGrantedAccess;
void *KeyContext;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeCreateKeyEventParams;
Unicode (Windows) virtual INT FireBeforeCreateKey(CBRegistryBeforeCreateKeyEventParams *e);
typedef struct {
LPCWSTR FullName;
INT DesiredAccess;
LONG64 *pKeyHandle;
LPVOID KeyHandleContext;
LONG64 *pGrantedAccess;
LPVOID KeyContext;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeCreateKeyEventParams;
#define EID_CBREGISTRY_BEFORECREATEKEY 16

virtual INT CBFSFILTER_CALL FireBeforeCreateKey(LPWSTR &lpszFullName, INT &iDesiredAccess, LONG64 &lKeyHandle, LPVOID &lpKeyHandleContext, LONG64 &lGrantedAccess, LPVOID &lpKeyContext, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeCreateKeyEventParams {
public:
  const QString &FullName();

  int DesiredAccess();

  qint64 KeyHandle();
  void SetKeyHandle(qint64 lKeyHandle);

  void *KeyHandleContext();
  void SetKeyHandleContext(void *lpKeyHandleContext);

  qint64 GrantedAccess();
  void SetGrantedAccess(qint64 lGrantedAccess);

  void *KeyContext();
  void SetKeyContext(void *lpKeyContext);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeCreateKey(CBRegistryBeforeCreateKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeCreateKey(CBRegistryBeforeCreateKeyEventParams *e) {...}

Remarks

This event fires before a registry key is created.

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeDeleteKey Event (CBRegistry Class)

This event fires before a registry key is deleted.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeDeleteKey(CBRegistryBeforeDeleteKeyEventParams *e);
typedef struct {
void *KeyContext;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeDeleteKeyEventParams;
Unicode (Windows) virtual INT FireBeforeDeleteKey(CBRegistryBeforeDeleteKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeDeleteKeyEventParams;
#define EID_CBREGISTRY_BEFOREDELETEKEY 17

virtual INT CBFSFILTER_CALL FireBeforeDeleteKey(LPVOID &lpKeyContext, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeDeleteKeyEventParams {
public:
  void *KeyContext();

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeDeleteKey(CBRegistryBeforeDeleteKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeDeleteKey(CBRegistryBeforeDeleteKeyEventParams *e) {...}

Remarks

This event fires before a registry key is deleted.

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeDeleteValue Event (CBRegistry Class)

This event fires before a registry value is deleted.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeDeleteValue(CBRegistryBeforeDeleteValueEventParams *e);
typedef struct {
void *KeyContext;
const char *ValueName;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeDeleteValueEventParams;
Unicode (Windows) virtual INT FireBeforeDeleteValue(CBRegistryBeforeDeleteValueEventParams *e);
typedef struct {
LPVOID KeyContext;
LPCWSTR ValueName;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeDeleteValueEventParams;
#define EID_CBREGISTRY_BEFOREDELETEVALUE 18

virtual INT CBFSFILTER_CALL FireBeforeDeleteValue(LPVOID &lpKeyContext, LPWSTR &lpszValueName, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeDeleteValueEventParams {
public:
  void *KeyContext();

  const QString &ValueName();

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeDeleteValue(CBRegistryBeforeDeleteValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeDeleteValue(CBRegistryBeforeDeleteValueEventParams *e) {...}

Remarks

This event fires before a registry value is deleted.

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeEnumerateKey Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeEnumerateKey(CBRegistryBeforeEnumerateKeyEventParams *e);
typedef struct {
void *KeyContext;
int Index;
int RequestedFields;
int64 *pLastWriteTime;
char *Name; int lenName;
char *ClassName; int lenClassName;
int SubKeys;
int MaxNameLength;
int MaxClassNameLength;
int Values;
int MaxValueNameLength;
int MaxValueDataSize;
int VirtualizationCandidate;
int VirtualizationEnabled;
int VirtualTarget;
int VirtualStore;
int VirtualSource;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeEnumerateKeyEventParams;
Unicode (Windows) virtual INT FireBeforeEnumerateKey(CBRegistryBeforeEnumerateKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Index;
INT RequestedFields;
LONG64 *pLastWriteTime;
LPWSTR Name; INT lenName;
LPWSTR ClassName; INT lenClassName;
INT SubKeys;
INT MaxNameLength;
INT MaxClassNameLength;
INT Values;
INT MaxValueNameLength;
INT MaxValueDataSize;
BOOL VirtualizationCandidate;
BOOL VirtualizationEnabled;
BOOL VirtualTarget;
BOOL VirtualStore;
BOOL VirtualSource;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeEnumerateKeyEventParams;
#define EID_CBREGISTRY_BEFOREENUMERATEKEY 19

virtual INT CBFSFILTER_CALL FireBeforeEnumerateKey(LPVOID &lpKeyContext, INT &iIndex, INT &iRequestedFields, LONG64 &lLastWriteTime, LPWSTR &lpName, INT &lenName, LPWSTR &lpClassName, INT &lenClassName, INT &iSubKeys, INT &iMaxNameLength, INT &iMaxClassNameLength, INT &iValues, INT &iMaxValueNameLength, INT &iMaxValueDataSize, BOOL &bVirtualizationCandidate, BOOL &bVirtualizationEnabled, BOOL &bVirtualTarget, BOOL &bVirtualStore, BOOL &bVirtualSource, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeEnumerateKeyEventParams {
public:
  void *KeyContext();

  int Index();

  int RequestedFields();

  const QDateTime &LastWriteTime();
  void SetLastWriteTime(const QDateTime &qdtLastWriteTime);

  const QString &Name();
  bool SetName(const QString &lpName);

  const QString &ClassName();
  bool SetClassName(const QString &lpClassName);

  int SubKeys();
  void SetSubKeys(int iSubKeys);

  int MaxNameLength();
  void SetMaxNameLength(int iMaxNameLength);

  int MaxClassNameLength();
  void SetMaxClassNameLength(int iMaxClassNameLength);

  int Values();
  void SetValues(int iValues);

  int MaxValueNameLength();
  void SetMaxValueNameLength(int iMaxValueNameLength);

  int MaxValueDataSize();
  void SetMaxValueDataSize(int iMaxValueDataSize);

  bool VirtualizationCandidate();
  void SetVirtualizationCandidate(bool bVirtualizationCandidate);

  bool VirtualizationEnabled();
  void SetVirtualizationEnabled(bool bVirtualizationEnabled);

  bool VirtualTarget();
  void SetVirtualTarget(bool bVirtualTarget);

  bool VirtualStore();
  void SetVirtualStore(bool bVirtualStore);

  bool VirtualSource();
  void SetVirtualSource(bool bVirtualSource);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeEnumerateKey(CBRegistryBeforeEnumerateKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeEnumerateKey(CBRegistryBeforeEnumerateKeyEventParams *e) {...}

Remarks

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

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

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

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

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

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

REG_KEYFIELD_LASTWRITETIME1A registry key's last write time.

REG_KEYFIELD_NAME2A registry key's name.

REG_KEYFIELD_MAXNAMELENGTH4A registry key's longest subkey name.

REG_KEYFIELD_CLASSNAME8A registry key's class name.

REG_KEYFIELD_MAXCLASSNAMELENGTH16A registry key's longest subkey class name.

REG_KEYFIELD_SUBKEYS32The number of subkeys a registry key has.

REG_KEYFIELD_VALUES64The number of values a registry key has.

REG_KEYFIELD_MAXVALUENAMELENGTH128A registry key's longest value name.

REG_KEYFIELD_MAXVALUEDATASIZE256A registry key's largest value data size.

REG_KEYFIELD_VIRTUALIZATIONINFO512A registry key's virtualization information.

The LastWriteTime parameter specifies when the key was last changed, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters. Note that the name, if set, should be copied to Name; set lenName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters. Note that the class name, if set, should be copied to ClassName; set lenClassName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeEnumerateValue Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeEnumerateValue(CBRegistryBeforeEnumerateValueEventParams *e);
typedef struct {
void *KeyContext;
int Index;
int RequestedFields;
char *ValueName; int lenValueName;
int ValueType;
int64 *pIntegerValue;
char *StringValue; int lenStringValue;
void *BinaryValue;
int MaxBinaryValueSize;
int BinaryValueSize;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeEnumerateValueEventParams;
Unicode (Windows) virtual INT FireBeforeEnumerateValue(CBRegistryBeforeEnumerateValueEventParams *e);
typedef struct {
LPVOID KeyContext;
INT Index;
INT RequestedFields;
LPWSTR ValueName; INT lenValueName;
INT ValueType;
LONG64 *pIntegerValue;
LPWSTR StringValue; INT lenStringValue;
LPVOID BinaryValue;
INT MaxBinaryValueSize;
INT BinaryValueSize;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeEnumerateValueEventParams;
#define EID_CBREGISTRY_BEFOREENUMERATEVALUE 20

virtual INT CBFSFILTER_CALL FireBeforeEnumerateValue(LPVOID &lpKeyContext, INT &iIndex, INT &iRequestedFields, LPWSTR &lpValueName, INT &lenValueName, INT &iValueType, LONG64 &lIntegerValue, LPWSTR &lpStringValue, INT &lenStringValue, LPVOID &lpBinaryValue, INT &iMaxBinaryValueSize, INT &iBinaryValueSize, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeEnumerateValueEventParams {
public:
  void *KeyContext();

  int Index();

  int RequestedFields();

  const QString &ValueName();
  bool SetValueName(const QString &lpValueName);

  int ValueType();
  void SetValueType(int iValueType);

  qint64 IntegerValue();
  void SetIntegerValue(qint64 lIntegerValue);

  const QString &StringValue();
  bool SetStringValue(const QString &lpStringValue);

  void *BinaryValue();

  int MaxBinaryValueSize();

  int BinaryValueSize();
  void SetBinaryValueSize(int iBinaryValueSize);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeEnumerateValue(CBRegistryBeforeEnumerateValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeEnumerateValue(CBRegistryBeforeEnumerateValueEventParams *e) {...}

Remarks

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

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

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

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

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

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

REG_VALUEFIELD_TYPE1A registry value's type.

REG_VALUEFIELD_NAME2A registry value's name.

REG_VALUEFIELD_DATA4A registry value's data.

The ValueName parameter specifies the registry value's name. Note that the name, if set, should be copied to ValueName; set lenValueName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

REG_VALUETYPE_SZ1A unicode string.

REG_VALUETYPE_EXPAND_SZ2A unicode string that contains environmental variable references.

REG_VALUETYPE_BINARY3Binary data.

REG_VALUETYPE_DWORD4A 32-bit number.

REG_VALUETYPE_MULTI_SZ7Multiple unicode strings.

REG_VALUETYPE_QWORD11A 64-bit number.

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

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ. Note that data should be copied to StringValue; set lenStringValue to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeGetKeySecurity Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeGetKeySecurity(CBRegistryBeforeGetKeySecurityEventParams *e);
typedef struct {
void *KeyContext;
int SecurityInformation;
void *SecurityDescriptor;
int Length;
int LengthNeeded;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeGetKeySecurityEventParams;
Unicode (Windows) virtual INT FireBeforeGetKeySecurity(CBRegistryBeforeGetKeySecurityEventParams *e);
typedef struct {
LPVOID KeyContext;
INT SecurityInformation;
LPVOID SecurityDescriptor;
INT Length;
INT LengthNeeded;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeGetKeySecurityEventParams;
#define EID_CBREGISTRY_BEFOREGETKEYSECURITY 21

virtual INT CBFSFILTER_CALL FireBeforeGetKeySecurity(LPVOID &lpKeyContext, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, INT &iLengthNeeded, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeGetKeySecurityEventParams {
public:
  void *KeyContext();

  int SecurityInformation();

  void *SecurityDescriptor();

  int Length();

  int LengthNeeded();
  void SetLengthNeeded(int iLengthNeeded);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeGetKeySecurity(CBRegistryBeforeGetKeySecurityEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeGetKeySecurity(CBRegistryBeforeGetKeySecurityEventParams *e) {...}

Remarks

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

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

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

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

The SecurityInformation parameter indicates which pieces of security information are requested. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that receives the requested security information. The buffer referenced by the SecurityDescriptor parameter may be modified by the event handler if the operation is completed without passing it further to other filters and the filesystem driver. The Length parameter reflects the capacity of the SecurityDescriptor buffer, in bytes.

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeOpenKey Event (CBRegistry Class)

This event fires before a registry key is opened.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeOpenKey(CBRegistryBeforeOpenKeyEventParams *e);
typedef struct {
const char *FullName;
int DesiredAccess;
int64 *pKeyHandle;
void *KeyHandleContext;
int GrantedAccess;
void *KeyContext;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeOpenKeyEventParams;
Unicode (Windows) virtual INT FireBeforeOpenKey(CBRegistryBeforeOpenKeyEventParams *e);
typedef struct {
LPCWSTR FullName;
INT DesiredAccess;
LONG64 *pKeyHandle;
LPVOID KeyHandleContext;
INT GrantedAccess;
LPVOID KeyContext;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeOpenKeyEventParams;
#define EID_CBREGISTRY_BEFOREOPENKEY 22

virtual INT CBFSFILTER_CALL FireBeforeOpenKey(LPWSTR &lpszFullName, INT &iDesiredAccess, LONG64 &lKeyHandle, LPVOID &lpKeyHandleContext, INT &iGrantedAccess, LPVOID &lpKeyContext, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeOpenKeyEventParams {
public:
  const QString &FullName();

  int DesiredAccess();

  qint64 KeyHandle();
  void SetKeyHandle(qint64 lKeyHandle);

  void *KeyHandleContext();
  void SetKeyHandleContext(void *lpKeyHandleContext);

  int GrantedAccess();
  void SetGrantedAccess(int iGrantedAccess);

  void *KeyContext();
  void SetKeyContext(void *lpKeyContext);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeOpenKey(CBRegistryBeforeOpenKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeOpenKey(CBRegistryBeforeOpenKeyEventParams *e) {...}

Remarks

This event fires before a registry key is opened.

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeQueryKey Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeQueryKey(CBRegistryBeforeQueryKeyEventParams *e);
typedef struct {
void *KeyContext;
int RequestedFields;
int64 *pLastWriteTime;
char *Name; int lenName;
char *ClassName; int lenClassName;
int SubKeys;
int MaxNameLength;
int MaxClassNameLength;
int Values;
int MaxValueNameLength;
int MaxValueDataSize;
int VirtualizationCandidate;
int VirtualizationEnabled;
int VirtualTarget;
int VirtualStore;
int VirtualSource;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeQueryKeyEventParams;
Unicode (Windows) virtual INT FireBeforeQueryKey(CBRegistryBeforeQueryKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
INT RequestedFields;
LONG64 *pLastWriteTime;
LPWSTR Name; INT lenName;
LPWSTR ClassName; INT lenClassName;
INT SubKeys;
INT MaxNameLength;
INT MaxClassNameLength;
INT Values;
INT MaxValueNameLength;
INT MaxValueDataSize;
BOOL VirtualizationCandidate;
BOOL VirtualizationEnabled;
BOOL VirtualTarget;
BOOL VirtualStore;
BOOL VirtualSource;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeQueryKeyEventParams;
#define EID_CBREGISTRY_BEFOREQUERYKEY 23

virtual INT CBFSFILTER_CALL FireBeforeQueryKey(LPVOID &lpKeyContext, INT &iRequestedFields, LONG64 &lLastWriteTime, LPWSTR &lpName, INT &lenName, LPWSTR &lpClassName, INT &lenClassName, INT &iSubKeys, INT &iMaxNameLength, INT &iMaxClassNameLength, INT &iValues, INT &iMaxValueNameLength, INT &iMaxValueDataSize, BOOL &bVirtualizationCandidate, BOOL &bVirtualizationEnabled, BOOL &bVirtualTarget, BOOL &bVirtualStore, BOOL &bVirtualSource, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeQueryKeyEventParams {
public:
  void *KeyContext();

  int RequestedFields();

  const QDateTime &LastWriteTime();
  void SetLastWriteTime(const QDateTime &qdtLastWriteTime);

  const QString &Name();
  bool SetName(const QString &lpName);

  const QString &ClassName();
  bool SetClassName(const QString &lpClassName);

  int SubKeys();
  void SetSubKeys(int iSubKeys);

  int MaxNameLength();
  void SetMaxNameLength(int iMaxNameLength);

  int MaxClassNameLength();
  void SetMaxClassNameLength(int iMaxClassNameLength);

  int Values();
  void SetValues(int iValues);

  int MaxValueNameLength();
  void SetMaxValueNameLength(int iMaxValueNameLength);

  int MaxValueDataSize();
  void SetMaxValueDataSize(int iMaxValueDataSize);

  bool VirtualizationCandidate();
  void SetVirtualizationCandidate(bool bVirtualizationCandidate);

  bool VirtualizationEnabled();
  void SetVirtualizationEnabled(bool bVirtualizationEnabled);

  bool VirtualTarget();
  void SetVirtualTarget(bool bVirtualTarget);

  bool VirtualStore();
  void SetVirtualStore(bool bVirtualStore);

  bool VirtualSource();
  void SetVirtualSource(bool bVirtualSource);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeQueryKey(CBRegistryBeforeQueryKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeQueryKey(CBRegistryBeforeQueryKeyEventParams *e) {...}

Remarks

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

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

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

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

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

REG_KEYFIELD_LASTWRITETIME1A registry key's last write time.

REG_KEYFIELD_NAME2A registry key's name.

REG_KEYFIELD_MAXNAMELENGTH4A registry key's longest subkey name.

REG_KEYFIELD_CLASSNAME8A registry key's class name.

REG_KEYFIELD_MAXCLASSNAMELENGTH16A registry key's longest subkey class name.

REG_KEYFIELD_SUBKEYS32The number of subkeys a registry key has.

REG_KEYFIELD_VALUES64The number of values a registry key has.

REG_KEYFIELD_MAXVALUENAMELENGTH128A registry key's longest value name.

REG_KEYFIELD_MAXVALUEDATASIZE256A registry key's largest value data size.

REG_KEYFIELD_VIRTUALIZATIONINFO512A registry key's virtualization information.

The LastWriteTime parameter specifies when the key was last changed, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

The Name parameter specifies the key's name. The maximum length of a registry key name is 255 characters. Note that the name, if set, should be copied to Name; set lenName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

The ClassName parameter specifies the key's class name. The maximum length of a registry key class name is 255 characters. Note that the class name, if set, should be copied to ClassName; set lenClassName to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeQueryValue Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeQueryValue(CBRegistryBeforeQueryValueEventParams *e);
typedef struct {
void *KeyContext;
const char *ValueName;
int RequestedFields;
int ValueType;
int64 *pIntegerValue;
char *StringValue; int lenStringValue;
void *BinaryValue;
int MaxBinaryValueSize;
int BinaryValueSize;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeQueryValueEventParams;
Unicode (Windows) virtual INT FireBeforeQueryValue(CBRegistryBeforeQueryValueEventParams *e);
typedef struct {
LPVOID KeyContext;
LPCWSTR ValueName;
INT RequestedFields;
INT ValueType;
LONG64 *pIntegerValue;
LPWSTR StringValue; INT lenStringValue;
LPVOID BinaryValue;
INT MaxBinaryValueSize;
INT BinaryValueSize;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeQueryValueEventParams;
#define EID_CBREGISTRY_BEFOREQUERYVALUE 24

virtual INT CBFSFILTER_CALL FireBeforeQueryValue(LPVOID &lpKeyContext, LPWSTR &lpszValueName, INT &iRequestedFields, INT &iValueType, LONG64 &lIntegerValue, LPWSTR &lpStringValue, INT &lenStringValue, LPVOID &lpBinaryValue, INT &iMaxBinaryValueSize, INT &iBinaryValueSize, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeQueryValueEventParams {
public:
  void *KeyContext();

  const QString &ValueName();

  int RequestedFields();

  int ValueType();
  void SetValueType(int iValueType);

  qint64 IntegerValue();
  void SetIntegerValue(qint64 lIntegerValue);

  const QString &StringValue();
  bool SetStringValue(const QString &lpStringValue);

  void *BinaryValue();

  int MaxBinaryValueSize();

  int BinaryValueSize();
  void SetBinaryValueSize(int iBinaryValueSize);

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeQueryValue(CBRegistryBeforeQueryValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeQueryValue(CBRegistryBeforeQueryValueEventParams *e) {...}

Remarks

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

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

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

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

The ValueName parameter reflects the name of the registry value.

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

REG_VALUEFIELD_TYPE1A registry value's type.

REG_VALUEFIELD_NAME2A registry value's name.

REG_VALUEFIELD_DATA4A registry value's data.

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

REG_VALUETYPE_SZ1A unicode string.

REG_VALUETYPE_EXPAND_SZ2A unicode string that contains environmental variable references.

REG_VALUETYPE_BINARY3Binary data.

REG_VALUETYPE_DWORD4A 32-bit number.

REG_VALUETYPE_MULTI_SZ7Multiple unicode strings.

REG_VALUETYPE_QWORD11A 64-bit number.

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

The StringValue parameter specifies the registry value's data if ValueType is REG_VALUETYPE_SZ, REG_VALUETYPE_EXPAND_SZ, or REG_VALUETYPE_MULTI_SZ. Note that data should be copied to StringValue; set lenStringValue to the length of the copied string (measured in char/wchar_t, not including terminating nulls).

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeRenameKey Event (CBRegistry Class)

This event fires before a registry key is renamed.

Syntax

ANSI (Cross Platform)
virtual int FireBeforeRenameKey(CBRegistryBeforeRenameKeyEventParams *e);
typedef struct {
void *KeyContext;
const char *NewName;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeRenameKeyEventParams;
Unicode (Windows) virtual INT FireBeforeRenameKey(CBRegistryBeforeRenameKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
LPCWSTR NewName;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeRenameKeyEventParams;
#define EID_CBREGISTRY_BEFORERENAMEKEY 25

virtual INT CBFSFILTER_CALL FireBeforeRenameKey(LPVOID &lpKeyContext, LPWSTR &lpszNewName, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeRenameKeyEventParams {
public:
  void *KeyContext();

  const QString &NewName();

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeRenameKey(CBRegistryBeforeRenameKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeRenameKey(CBRegistryBeforeRenameKeyEventParams *e) {...}

Remarks

This event fires before a registry key is renamed.

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeSetKey Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetKey(CBRegistryBeforeSetKeyEventParams *e);
typedef struct {
void *KeyContext;
int64 LastWriteTime;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeSetKeyEventParams;
Unicode (Windows) virtual INT FireBeforeSetKey(CBRegistryBeforeSetKeyEventParams *e);
typedef struct {
LPVOID KeyContext;
LONG64 LastWriteTime;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeSetKeyEventParams;
#define EID_CBREGISTRY_BEFORESETKEY 26

virtual INT CBFSFILTER_CALL FireBeforeSetKey(LPVOID &lpKeyContext, LONG64 &lLastWriteTime, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeSetKeyEventParams {
public:
  void *KeyContext();

  const QDateTime &LastWriteTime();

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetKey(CBRegistryBeforeSetKeyEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeSetKey(CBRegistryBeforeSetKeyEventParams *e) {...}

Remarks

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

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

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

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

The LastWriteTime parameter reflects when the key was last changed, specified as a number of 100-nanosecond intervals since Jan 1, 1601 00:00:00 UTC, i.e., as Windows FILETIME.

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeSetKeySecurity Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetKeySecurity(CBRegistryBeforeSetKeySecurityEventParams *e);
typedef struct {
void *KeyContext;
int SecurityInformation;
void *SecurityDescriptor;
int Length;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeSetKeySecurityEventParams;
Unicode (Windows) virtual INT FireBeforeSetKeySecurity(CBRegistryBeforeSetKeySecurityEventParams *e);
typedef struct {
LPVOID KeyContext;
INT SecurityInformation;
LPVOID SecurityDescriptor;
INT Length;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeSetKeySecurityEventParams;
#define EID_CBREGISTRY_BEFORESETKEYSECURITY 27

virtual INT CBFSFILTER_CALL FireBeforeSetKeySecurity(LPVOID &lpKeyContext, INT &iSecurityInformation, LPVOID &lpSecurityDescriptor, INT &iLength, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeSetKeySecurityEventParams {
public:
  void *KeyContext();

  int SecurityInformation();

  void *SecurityDescriptor();

  int Length();

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetKeySecurity(CBRegistryBeforeSetKeySecurityEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeSetKeySecurity(CBRegistryBeforeSetKeySecurityEventParams *e) {...}

Remarks

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

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

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

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

The SecurityInformation parameter reflects which pieces of security information, of those present in SecurityDescriptor, will be set. Please refer to Microsoft's SECURITY_INFORMATION data type documentation for more information about possible values.

The SecurityDescriptor parameter points to a memory buffer that specifies the new security information. The buffer referenced by the SecurityDescriptor parameter may be modified when needed if the request is to be passed further to other filters and the filesystem driver. The Length parameter reflects the length of the data, in bytes. Please see the Buffer Parameters topic for more information on how to work with memory buffer event parameters.

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

BeforeSetValue Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireBeforeSetValue(CBRegistryBeforeSetValueEventParams *e);
typedef struct {
void *KeyContext;
const char *ValueName;
int ValueType;
int64 IntegerValue;
const char *StringValue;
void *BinaryValue;
int BinaryValueSize;
int Processed;
int FireAfterEvent;
int StopFiltering;
int ResultCode; int reserved; } CBRegistryBeforeSetValueEventParams;
Unicode (Windows) virtual INT FireBeforeSetValue(CBRegistryBeforeSetValueEventParams *e);
typedef struct {
LPVOID KeyContext;
LPCWSTR ValueName;
INT ValueType;
LONG64 IntegerValue;
LPCWSTR StringValue;
LPVOID BinaryValue;
INT BinaryValueSize;
BOOL Processed;
BOOL FireAfterEvent;
BOOL StopFiltering;
INT ResultCode; INT reserved; } CBRegistryBeforeSetValueEventParams;
#define EID_CBREGISTRY_BEFORESETVALUE 28

virtual INT CBFSFILTER_CALL FireBeforeSetValue(LPVOID &lpKeyContext, LPWSTR &lpszValueName, INT &iValueType, LONG64 &lIntegerValue, LPWSTR &lpszStringValue, LPVOID &lpBinaryValue, INT &iBinaryValueSize, BOOL &bProcessed, BOOL &bFireAfterEvent, BOOL &bStopFiltering, INT &iResultCode);
class CBRegistryBeforeSetValueEventParams {
public:
  void *KeyContext();

  const QString &ValueName();

  int ValueType();

  qint64 IntegerValue();

  const QString &StringValue();

  void *BinaryValue();

  int BinaryValueSize();

  bool Processed();
  void SetProcessed(bool bProcessed);

  bool FireAfterEvent();
  void SetFireAfterEvent(bool bFireAfterEvent);

  bool StopFiltering();
  void SetStopFiltering(bool bStopFiltering);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void BeforeSetValue(CBRegistryBeforeSetValueEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireBeforeSetValue(CBRegistryBeforeSetValueEventParams *e) {...}

Remarks

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

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

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

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

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

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

REG_VALUETYPE_SZ1A unicode string.

REG_VALUETYPE_EXPAND_SZ2A unicode string that contains environmental variable references.

REG_VALUETYPE_BINARY3Binary data.

REG_VALUETYPE_DWORD4A 32-bit number.

REG_VALUETYPE_MULTI_SZ7Multiple unicode strings.

REG_VALUETYPE_QWORD11A 64-bit number.

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

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

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

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

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

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

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

CleanupKeyContext Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireCleanupKeyContext(CBRegistryCleanupKeyContextEventParams *e);
typedef struct {
void *KeyContext;
int ResultCode; int reserved; } CBRegistryCleanupKeyContextEventParams;
Unicode (Windows) virtual INT FireCleanupKeyContext(CBRegistryCleanupKeyContextEventParams *e);
typedef struct {
LPVOID KeyContext;
INT ResultCode; INT reserved; } CBRegistryCleanupKeyContextEventParams;
#define EID_CBREGISTRY_CLEANUPKEYCONTEXT 29

virtual INT CBFSFILTER_CALL FireCleanupKeyContext(LPVOID &lpKeyContext, INT &iResultCode);
class CBRegistryCleanupKeyContextEventParams {
public:
  void *KeyContext();

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void CleanupKeyContext(CBRegistryCleanupKeyContextEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireCleanupKeyContext(CBRegistryCleanupKeyContextEventParams *e) {...}

Remarks

This event fires when the specified KeyContext is about to be discarded, giving applications a chance to clean up any information stored in it. Please refer to the Contexts topic for more information.

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

CloseKeyHandle Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireCloseKeyHandle(CBRegistryCloseKeyHandleEventParams *e);
typedef struct {
void *KeyContext;
int64 KeyHandle;
void *KeyHandleContext;
int Error;
int Processed;
int ResultCode; int reserved; } CBRegistryCloseKeyHandleEventParams;
Unicode (Windows) virtual INT FireCloseKeyHandle(CBRegistryCloseKeyHandleEventParams *e);
typedef struct {
LPVOID KeyContext;
LONG64 KeyHandle;
LPVOID KeyHandleContext;
INT Error;
BOOL Processed;
INT ResultCode; INT reserved; } CBRegistryCloseKeyHandleEventParams;
#define EID_CBREGISTRY_CLOSEKEYHANDLE 30

virtual INT CBFSFILTER_CALL FireCloseKeyHandle(LPVOID &lpKeyContext, LONG64 &lKeyHandle, LPVOID &lpKeyHandleContext, INT &iError, BOOL &bProcessed, INT &iResultCode);
class CBRegistryCloseKeyHandleEventParams {
public:
  void *KeyContext();

  qint64 KeyHandle();

  void *KeyHandleContext();

  int Error();

  bool Processed();
  void SetProcessed(bool bProcessed);

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

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void CloseKeyHandle(CBRegistryCloseKeyHandleEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireCloseKeyHandle(CBRegistryCloseKeyHandleEventParams *e) {...}

Remarks

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

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

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

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

The ResultCode parameter will always be 0 when the event is fired. If the event cannot be handled in a "successful" manner for some reason (e.g., a resource is not available or security checks failed), set it to a nonzero value to report an appropriate error. Please see the Error Handling topic for more information.

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

Error Event (CBRegistry Class)

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

Syntax

ANSI (Cross Platform)
virtual int FireError(CBRegistryErrorEventParams *e);
typedef struct {
int ErrorCode;
const char *Description; int reserved; } CBRegistryErrorEventParams;
Unicode (Windows) virtual INT FireError(CBRegistryErrorEventParams *e);
typedef struct {
INT ErrorCode;
LPCWSTR Description; INT reserved; } CBRegistryErrorEventParams;
#define EID_CBREGISTRY_ERROR 31

virtual INT CBFSFILTER_CALL FireError(INT &iErrorCode, LPSTR &lpszDescription);
class CBRegistryErrorEventParams {
public:
  int ErrorCode();

  const QString &Description();

  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void Error(CBRegistryErrorEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireError(CBRegistryErrorEventParams *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.

WorkerThreadCreation Event (CBRegistry Class)

Fires just after a new worker thread is created.

Syntax

ANSI (Cross Platform)
virtual int FireWorkerThreadCreation(CBRegistryWorkerThreadCreationEventParams *e);
typedef struct {
int ResultCode; int reserved; } CBRegistryWorkerThreadCreationEventParams;
Unicode (Windows) virtual INT FireWorkerThreadCreation(CBRegistryWorkerThreadCreationEventParams *e);
typedef struct {
INT ResultCode; INT reserved; } CBRegistryWorkerThreadCreationEventParams;
#define EID_CBREGISTRY_WORKERTHREADCREATION 32

virtual INT CBFSFILTER_CALL FireWorkerThreadCreation(INT &iResultCode);
class CBRegistryWorkerThreadCreationEventParams {
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(CBRegistryWorkerThreadCreationEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireWorkerThreadCreation(CBRegistryWorkerThreadCreationEventParams *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.

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.

WorkerThreadTermination Event (CBRegistry Class)

Fires just before a worker thread is terminated.

Syntax

ANSI (Cross Platform)
virtual int FireWorkerThreadTermination(CBRegistryWorkerThreadTerminationEventParams *e);
typedef struct { int reserved; } CBRegistryWorkerThreadTerminationEventParams;
Unicode (Windows) virtual INT FireWorkerThreadTermination(CBRegistryWorkerThreadTerminationEventParams *e);
typedef struct { INT reserved; } CBRegistryWorkerThreadTerminationEventParams;
#define EID_CBREGISTRY_WORKERTHREADTERMINATION 33

virtual INT CBFSFILTER_CALL FireWorkerThreadTermination();
class CBRegistryWorkerThreadTerminationEventParams {
public:
  int EventRetVal();
  void SetEventRetVal(int iRetVal);
};
// To handle, connect one or more slots to this signal. void WorkerThreadTermination(CBRegistryWorkerThreadTerminationEventParams *e);
// Or, subclass CBRegistry and override this emitter function. virtual int FireWorkerThreadTermination(CBRegistryWorkerThreadTerminationEventParams *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.

RegDefaultRule Type

This type represents a registry default rule.

Syntax

CBFSFilterRegDefaultRule (declared in cbfsfilter.h)

Remarks

This type represents a registry default rule. Please refer to the Default Rules topic for more information.

The following fields are available:

Fields

AccessFlags
int (read-only)

Default Value: 0

This field indicates the access restrictions enforced by the rule.

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

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

Mask
char* (read-only)

Default Value: ""

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

This field reflects the registry key mask used to determine whether a registry key matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

RegFilterRule Type

This type represents a registry filter rule.

Syntax

CBFSFilterRegFilterRule (declared in cbfsfilter.h)

Remarks

This type represents a registry filter rule, which may be either a standard filter rule, an access rule, or a combination of both. Please refer to the File and Registry Filter Rules and Access Rules topics for more information.

The following fields are available:

Fields

AccessFlags
int (read-only)

Default Value: 0

This field indicates the access restrictions enforced by the rule.

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

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

ControlFlags
int64 (read-only)

Default Value: 0

This field indicates which control events the rule causes the class to fire.

This field indicates which registry operations, of those performed on matching registry keys, the class should fire Control Events for. The value of this field is a combination of zero or more of the following:

REG_CE_NONE0Don't fire for any registry operations.

Control Events will not fire for any registry operations.

REG_CE_BEFORE_CREATE_KEY0x00000001LFire before registry key creation operations.

The BeforeCreateKey event will fire anytime the OS attempts to create a registry key.

REG_CE_AFTER_CREATE_KEY0x00000002LFire after registry key creation operations.

The AfterCreateKey event will fire after a registry key creation request has been processed, before the response is returned.

REG_CE_BEFORE_OPEN_KEY0x00000004LFire before registry key open operations.

The BeforeOpenKey event will fire anytime the OS attempts to open a registry key.

REG_CE_AFTER_OPEN_KEY0x00000008LFire after registry key open operations.

The AfterOpenKey event will fire after a registry key open request has been processed, before the response is returned.

REG_CE_BEFORE_CLOSE_KEY0x00000010LFire before registry key close operations.

The BeforeCloseKey event will fire anytime the OS closes a registry key.

REG_CE_AFTER_CLOSE_KEY0x00000020LFire after registry key close operations.

The AfterCloseKey event will fire after a registry key close request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_KEY0x00000040LFire before registry key delete operations.

The BeforeDeleteKey event will fire anytime the OS attempts to delete a registry key.

REG_CE_AFTER_DELETE_KEY0x00000080LFire after registry key delete operations.

The AfterDeleteKey event will fire after a registry key delete request has been processed, before the response is returned.

REG_CE_BEFORE_RENAME_KEY0x00000100LFire before registry key rename operations.

The BeforeRenameKey event will fire anytime the OS attempts to rename a registry key.

REG_CE_AFTER_RENAME_KEY0x00000200LFire after registry key rename operations.

The AfterRenameKey event will fire after a registry key rename request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_KEY0x00000400LFire before subkey enumeration operations.

The BeforeEnumerateKey event will fire anytime the OS attempts to enumerate a registry key's subkeys.

REG_CE_AFTER_ENUM_KEY0x00000800LFire after subkey enumeration operations.

The AfterEnumerateKey event will fire after a subkey enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_KEY0x00001000LFire before registry key metadata retrieval operations.

The BeforeQueryKey event will fire anytime the OS attempts to retrieve a registry key's metadata.

REG_CE_AFTER_QUERY_KEY0x00002000LFire after registry key metadata retrieval operations.

The AfterQueryKey event will fire after a registry key metadata retrieval request has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY0x00004000LFire before registry key metadata update operations.

The BeforeSetKey event will fire anytime the OS attempts to update a registry key's metadata.

REG_CE_AFTER_SET_KEY0x00008000LFire after registry key metadata update operations.

The AfterSetKey event will fire after a registry key metadata update request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_VALUE0x00010000LFire before registry value delete operations.

The BeforeDeleteValue event will fire anytime the OS attempts to delete a registry value.

REG_CE_AFTER_DELETE_VALUE0x00020000LFire after registry value delete operations.

The AfterDeleteValue event will fire after a registry value delete request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_VALUE0x00040000LFire before value enumeration operations.

The BeforeEnumerateValue event will fire anytime the OS attempts to enumerate a registry key's values.

REG_CE_AFTER_ENUM_VALUE0x00080000LFire after value enumeration operations.

The AfterEnumerateValue event will fire after a value enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_VALUE0x00100000LFire before registry value query operations.

The BeforeQueryValue event will fire anytime the OS attempts to query a registry value.

REG_CE_AFTER_QUERY_VALUE0x00200000LFire after registry value query operations.

The AfterQueryValue event will fire after a registry value query request has been processed, before the response is returned.

REG_CE_BEFORE_SET_VALUE0x00400000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS attempts to set or update a registry value.

REG_CE_AFTER_SET_VALUE0x00800000LFire after registry value set/update operations.

The AfterSetValue event will fire after a registry value set or update request has been processed, before the response is returned.

REG_CE_BEFORE_GET_KEY_SECURITY0x001000000LFire before get registry key security operations.

The BeforeGetKeySecurity event will fire before the OS queries the security attributes of a registry key.

REG_CE_AFTER_GET_KEY_SECURITY0x002000000LFire after registry value query operations.

The AfterGetKeySecurity event will fire after a get security operation has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY_SECURITY0x004000000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS needs to change the security attributes of a registry key.

REG_CE_AFTER_SET_KEY_SECURITY0x008000000LFire after registry value set/update operations.

The AfterSetValue event will fire after a security attributes change request has been processed, before the response is returned.

REG_CE_ALL-1Fire for all registry operations.

Control Events will fire for all registry operations.

Mask
char* (read-only)

Default Value: ""

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

This field reflects the registry key mask used to determine whether a registry key matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

RegPassthroughRule Type

This type represents a registry passthrough rule.

Syntax

CBFSFilterRegPassthroughRule (declared in cbfsfilter.h)

Remarks

This type represents a registry passthrough rule. Please refer to the Passthrough Rules topic for more information.

The following fields are available:

Fields

AccessFlags
int (read-only)

Default Value: 0

This field indicates the access restrictions lifted by the rule.

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

ACCESS_NONE0x00No access restrictions.

ACCESS_READ_ONLY0x01Read-only access; writing and deleting are prohibited.

ACCESS_WRITE_ONLY0x02Write-only access; reading and deleting are prohibited.

ACCESS_DELETE_PROTECT0x04Deleting and renaming are prohibited.

ACCESS_EXECUTE_PROTECT0x08Execution is prohibited.

ACCESS_NO_CHANGE_DAC0x10Change of security attributes is prohibited.

ACCESS_NO_CHANGE_OWNER0x20Change of owner is prohibited.

ACCESS_RENAME_PROTECT0x40Renaming is prohibited.

ACCESS_DELETE_ONLY_PROTECT0x80Deleting is prohibited (renaming is not affected).

ACCESS_REMOTE_ACCESS_PROTECT0x100Access from other systems is prohibited.

ACCESS_DENY_ALL0x200All access is denied.

ACCESS_ALL_FLAGS-1Used to denote all currently set access restriction flags.

ControlFlags
int64 (read-only)

Default Value: 0

This field indicates which control events the rule prevents the class from firing.

This field indicates which registry operations, of those performed on matching registry keys, the class should not fire Control Events for. Please refer to the Passthrough Rules topic for more information. The value of this field is a combination of zero or more of the following:

REG_CE_NONE0Don't fire for any registry operations.

Control Events will not fire for any registry operations.

REG_CE_BEFORE_CREATE_KEY0x00000001LFire before registry key creation operations.

The BeforeCreateKey event will fire anytime the OS attempts to create a registry key.

REG_CE_AFTER_CREATE_KEY0x00000002LFire after registry key creation operations.

The AfterCreateKey event will fire after a registry key creation request has been processed, before the response is returned.

REG_CE_BEFORE_OPEN_KEY0x00000004LFire before registry key open operations.

The BeforeOpenKey event will fire anytime the OS attempts to open a registry key.

REG_CE_AFTER_OPEN_KEY0x00000008LFire after registry key open operations.

The AfterOpenKey event will fire after a registry key open request has been processed, before the response is returned.

REG_CE_BEFORE_CLOSE_KEY0x00000010LFire before registry key close operations.

The BeforeCloseKey event will fire anytime the OS closes a registry key.

REG_CE_AFTER_CLOSE_KEY0x00000020LFire after registry key close operations.

The AfterCloseKey event will fire after a registry key close request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_KEY0x00000040LFire before registry key delete operations.

The BeforeDeleteKey event will fire anytime the OS attempts to delete a registry key.

REG_CE_AFTER_DELETE_KEY0x00000080LFire after registry key delete operations.

The AfterDeleteKey event will fire after a registry key delete request has been processed, before the response is returned.

REG_CE_BEFORE_RENAME_KEY0x00000100LFire before registry key rename operations.

The BeforeRenameKey event will fire anytime the OS attempts to rename a registry key.

REG_CE_AFTER_RENAME_KEY0x00000200LFire after registry key rename operations.

The AfterRenameKey event will fire after a registry key rename request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_KEY0x00000400LFire before subkey enumeration operations.

The BeforeEnumerateKey event will fire anytime the OS attempts to enumerate a registry key's subkeys.

REG_CE_AFTER_ENUM_KEY0x00000800LFire after subkey enumeration operations.

The AfterEnumerateKey event will fire after a subkey enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_KEY0x00001000LFire before registry key metadata retrieval operations.

The BeforeQueryKey event will fire anytime the OS attempts to retrieve a registry key's metadata.

REG_CE_AFTER_QUERY_KEY0x00002000LFire after registry key metadata retrieval operations.

The AfterQueryKey event will fire after a registry key metadata retrieval request has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY0x00004000LFire before registry key metadata update operations.

The BeforeSetKey event will fire anytime the OS attempts to update a registry key's metadata.

REG_CE_AFTER_SET_KEY0x00008000LFire after registry key metadata update operations.

The AfterSetKey event will fire after a registry key metadata update request has been processed, before the response is returned.

REG_CE_BEFORE_DELETE_VALUE0x00010000LFire before registry value delete operations.

The BeforeDeleteValue event will fire anytime the OS attempts to delete a registry value.

REG_CE_AFTER_DELETE_VALUE0x00020000LFire after registry value delete operations.

The AfterDeleteValue event will fire after a registry value delete request has been processed, before the response is returned.

REG_CE_BEFORE_ENUM_VALUE0x00040000LFire before value enumeration operations.

The BeforeEnumerateValue event will fire anytime the OS attempts to enumerate a registry key's values.

REG_CE_AFTER_ENUM_VALUE0x00080000LFire after value enumeration operations.

The AfterEnumerateValue event will fire after a value enumeration request has been processed, before the response is returned.

REG_CE_BEFORE_QUERY_VALUE0x00100000LFire before registry value query operations.

The BeforeQueryValue event will fire anytime the OS attempts to query a registry value.

REG_CE_AFTER_QUERY_VALUE0x00200000LFire after registry value query operations.

The AfterQueryValue event will fire after a registry value query request has been processed, before the response is returned.

REG_CE_BEFORE_SET_VALUE0x00400000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS attempts to set or update a registry value.

REG_CE_AFTER_SET_VALUE0x00800000LFire after registry value set/update operations.

The AfterSetValue event will fire after a registry value set or update request has been processed, before the response is returned.

REG_CE_BEFORE_GET_KEY_SECURITY0x001000000LFire before get registry key security operations.

The BeforeGetKeySecurity event will fire before the OS queries the security attributes of a registry key.

REG_CE_AFTER_GET_KEY_SECURITY0x002000000LFire after registry value query operations.

The AfterGetKeySecurity event will fire after a get security operation has been processed, before the response is returned.

REG_CE_BEFORE_SET_KEY_SECURITY0x004000000LFire before registry value set/update operations.

The BeforeSetValue event will fire anytime the OS needs to change the security attributes of a registry key.

REG_CE_AFTER_SET_KEY_SECURITY0x008000000LFire after registry value set/update operations.

The AfterSetValue event will fire after a security attributes change request has been processed, before the response is returned.

REG_CE_ALL-1Fire for all registry operations.

Control Events will fire for all registry operations.

Mask
char* (read-only)

Default Value: ""

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

This field reflects the registry key mask used to determine whether a registry key matches the rule. In addition to being its primary match qualifier, a rule's mask also serves as its identifier; every rule in a ruleset must have a unique mask.

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

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

ForceAdminRightsForDefaultRules:   Specifies whether default rules can be added or deleted only by administrators.

This configuration setting specifies whether the access check must be performed when an attempt is made to add or delete a default rule.

By default, the setting is enabled and rules may be added and deleted only by administrators. If, however, an application uses default rules not for security-related purposes, and the risk of a limited user trying to add or remove the rules is low, such application may disable the setting.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

ForceAppPermissionCheck:   Whether the driver should require the controller process to have elevated or system privileges.

This configuration setting corresponds to the INSTALL_FORCE_APP_PERMISSION_CHECK flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

ForceSecurityChecks:   Whether the driver should prevent the controller process from filtering files that it would not normally have access to.

This configuration setting corresponds to the INSTALL_FORCE_SECURITY_CHECKS flag, which is used with the Install method; please refer to the documentation for both for more information. If this setting is enabled when Install is called, the aforementioned flag will be set automatically.

Administrative rights are required to change this configuration setting after Initialize is called. If the user account of the process that calls Config does not have such rights, the call will fail with an ERROR_PRIVILEGE_NOT_HELD (0x0522) error.

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.

ResolveNtNameToWin32Name:   Whether key names in NT native format are translated to common Win32 format.

This setting specifies whether NT native names (e.g., \Registry\Machine\...) should be translated to common Win32 format (e.g., HKY_LOCAL_MACHINE\...).

Note: Such translation is not always possible.

This setting is disabled by default.

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

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