Registering for Registry Events

[This is preliminary documentation and subject to change.]

To receive notifications from the Registry Provider, a management application must:

1. Register the Registry Provider as an event provider.
2. Register as a temporary event consumer.

Registering the Registry Provider as an event provider involves compiling the Regevent.mof file that is included with the WBEM SDK. Regevent.mof contains an instance of the __Win32Provider class to identify the Registry Provider by name and CLSID, and an instance of the __EventProviderRegistration class to publish queries that describe the types of event notifications that are supported. Each type of event notification is represented by a different class. The Registry Event Provider supports three classes of events:

• RegistryKeyChangeEvent
• RegistryTreeChangeEvent
• RegistryValueChangeEvent

All three of these classes have a property called Hive that identifies the hierarchy of keys to be monitored for change, such as HKEY_LOCAL_MACHINE, and a path to the key or tree of keys to be monitored. RegistryValueChangeEvent also has a ValueName property to hold the changed key value.

The Regevent.mof file contains the following instances to register the Registry Provider as an event provider:

instance of __Win32Provider as $P
{
    Name = "RegistryEventProvider";
    Clsid = "{fa77a74e-e109-11d0-ad6e-00c04fd8fdff}";
};

instance of __EventProviderRegistration
{
    Provider = $P;
    EventQueryList = {
            "select * from RegistryKeyChangeEvent",
            "select * from RegistryValueChangeEvent",
            "select * from RegistryTreeChangeEvent"};
};

Registering as a temporary event consumer involves:

• Implementing the IWbemObjectSink interface.
• Calling the IWbemServices::ExecNotificationQueryAsync method.

IWbemObjectSink contains two methods: Indicate and SetStatus. Indicate is the method that the Registry Event Provider calls to deliver its notifications. SetStatus is the method that is called to report the completion of a delivery.

When a consumer is ready to receive registry event notifications, it calls ExecNotificationQueryAsync and passes a pointer to the IWbemObjectSink implementation in the pResponseHandler parameter. The bstrQuery parameter describes which registry events are to be delivered. For each class of event, a WHERE clause needs to be included in the query that names values for each property in the class. For example, the following query registers to receive RegistryTreeChangeEvents for "HKEY_LOCAL_MACHINE\Software":

select * from RegistryTreeChangeEvent 
    where Hive = "HKEY_LOCAL_MACHINE" and Rootpath = "Software";

When using the AND and OR operators, make sure that a list of possible values for every event property can be inferred from the query. For example, the following query is valid:

select * from RegistryTreeChangeEvent 
    where (hive = "hkey_local_machine" and rootpath = "software") 
    or    (hive = "hkey_current_user" and rootpath = "console");

However, this next query is not valid because there is no way for CIMOM to evaluate the possible values for each of the properties:

select * from RegistryTreeChangeEvent 
    where hive = hkey_local_machine" OR rootpath="software";

If the WHERE clause is missing or is too broad to be of use, the Registry Event Provider returns the error WBEM_E_TOO_BROAD.

Note  The WITHIN clause must be included in queries to be used on Windows 95 and Windows 98 platforms. This clause is unnecessary on Windows NT platforms. For information about the WITHIN clause, see SELECT Statement WITHIN Clause.