Handling Notifications

The RegistryCallback routine receives a pointer to a REG_XXX_KEY_INFORMATION structure that contains information about the registry operation that is occurring.

The RegistryCallback routine can monitor, block, or modify a registry operation.

Monitoring Registry Calls

If a registry filtering driver is monitoring registry operations, its RegistryCallback routine can update counters or perform other bookkeeping operations and then return STATUS_SUCCESS. Whenever a RegistryCallback routine returns STATUS_SUCCESS, the configuration manager continues performing the registry operation.

Monitoring registry calls is supported in Windows XP and later versions of Windows.

Blocking Registry Calls

A registry filtering driver can block registry operations if its RegistryCallback routine returns a status value for which NT_SUCCESS(status) equals FALSE (that is, a non-success NTSTATUS value). When the configuration manager receives a non-success return value, it immediately returns to the calling thread with the driver-specified status value. Therefore, a registry filtering driver can use pre-notifications to prevent registry operations from being processed.

If a RegistryCallback routine returns a status value for which NT_SUCCESS(status) equals FALSE for a pre-notification, the operation's post-notification callback does not occur.

Blocking registry calls is supported in Windows XP and later versions of Windows. For Windows Vista and later, the driver can modify the values that the registry operation returns to the calling thread. These values are contained in the REG_XXX_KEY_INFORMATION structures for Windows Vista and later.

Modifying Registry Calls

A registry filtering driver can modify a registry operation's output parameters or return value. Additionally, the driver can completely process a registry operation instead of allowing the registry to handle the operation.

When a registry filtering driver's RegistryCallback routine receives a post-notification, it can:

• Modify the output parameters that its REG_XXX_KEY_INFORMATION structure contains and then return STATUS_SUCCESS. The configuration manager returns the modified output parameters to the calling thread.

  Modifying output parameters is supported in Windows Vista and later.

• Modify the registry operation's return value by providing a status value for the ReturnStatus member of the REG_POST_OPERATION_INFORMATION structure and then returning STATUS_CALLBACK_BYPASS. The configuration manager returns the specified return value to the calling thread.

  Note If the driver changes a status code from success to failure, it might have to deallocate objects that the configuration manager allocated. Alternatively, if the driver changes a status code from failure to success, it might have to provide appropriate output parameters.

Modifying return values is supported in Windows Vista and later.

When a registry filtering driver's RegistryCallback routine receives a pre-notification, the routine can handle the registry operation itself and then return STATUS_CALLBACK_BYPASS. When the registry receives STATUS_CALLBACK_BYPASS from the driver, it just returns STATUS_SUCCESS to the calling thread and does not process the operation. The driver preempts the registry operation and must completely handle it, and the driver must be careful to return valid output values in the REG_XXX_KEY_INFORMATION structure.

Drivers can preempt registry operations in Windows Vista and later.

If a RegistryCallback routine returns STATUS_CALLBACK_BYPASS for a pre-notification, the operation's post-notification callback does not occur.

Note Several registry system calls are not documented because they are rarely used, and, when they are used, it is usually to achieve some unconventional result in the registry. Modifying the operations performed by these calls is difficult and error-prone. Driver developers are discouraged from trying to modify the following registry system calls:

• NtRestoreKey
• NtSaveKey
• NtSaveKeyEx
• NtLoadKeyEx
• NtUnloadKey2
• NtUnloadKeyEx
• NtReplaceKey
• NtRenameKey
• NtSetInformationKey