Finally, some clear time to write another post!
In order to get WMI to to do something with the stream of events that flows through a system you need to use three classes in combination
- The event filter class.
- The event consumer class.
- The filter to consumer binding class.
Event filters
Event filters are used to specify the particular events that you want WMI to look out for. They are specified in WQL, a SQL like language. There is a good discussion of WQL and event filters here in MSDN.
The WMI class that represents an event filter is '__EventFilter'.
A word about namespaces
Internally the WMI store is partitioned into a number of namespaces. Microsoft recommend that you register all of your event classes in the '\root\subscription' name space. As the events that you will be interested in won't be occurring in this namespace it is important to set the 'EventNamespace' property on any filter that you create so that WMI knows where to look for candidate events. If you forget to do this you will get errors in the Application event log when you try to use your filter.
Event consumers
Event consumers are the bits of code that receive notification of the events that you have registered an interest in. WMI comes with 5 preinstalled consumers on Vista/XP and Server 2003. On Windows 2000 you need to install the providers yourself by compiling their MOF files.
- ActiveScriptEventConsumer
- This allows you to run an arbitrary script in response to an event.
- LogFileEventConsumer
- This allows you to write to a text file in response to events.
- NTEventLogEventConsumer
- Theis allows you to write to the Windows event logs in response to events.
- SMTPEventConsumer
- This allows you to send e-mail in response to events.
- CommandLineEventConsumer
- This allows you to run any command in response to events
You can find much more information about these consumers here in MSDN.
Additionally if you have installed the WMI Tools you will get an extra consumer - the 'WMI Event Viewer Consumer'. This is a simple GUI tool that displays the events captured by a filter as they happen. It's great for testing your filters before you go into production with one of the other consumers.
If you are using CIM Studio from the WMI Tools then have a look in the 'ROOT\subscription namespace' and navigate to '__SystemClass\__IndicationRelated\__EventConsumer' to see a list of the event consumers installed on your machine.
Filter to consumer bindings
These are the essential bits of plumbing that connect filters to consumers. The WMI class for this is '__FilterToConsumerBinding' and you can read more about it here. Once you have set this up WMI will keep routing the events captured by a filter to your chosen consumer until you reconfigure things - even across reboots.