Creating an Event Filter

An event filter is a WMI class that describes which events WMI delivers to a physical consumer. For example, an event filter can instruct WMI to deliver to a consumer all power management events, or all system reboot events. An event filter also describes the conditions under which WMI delivers the events. An event filter can specify an intrinsic or extrinsic event; and the filter can refer to events that originate in the namespace—that is, other than the namespace of the filter. The permanent consumer must have the same CreatorSID in the consumer, filter, and binding instances. For more information, see Receiving Events Securely.

The following procedure describes how to create an event filter.

To create an event filter

1. Create an instance of the WMI __EventFilter system class.

2. Create a unique identifier for your filter with the Name property, in one of two ways:

   • Use a private scheme.

     Arbitrarily naming your event filters works as long as you do not conflict with other filter naming schemes. You must avoid naming conflicts because adding an instance with a duplicate Name value overwrites the old instance.

   • Use a globally unique identifier (GUID).

     If you leave Name empty, WMI fills Name with a GUID.

3. Describe the type of event you want filtered with the Query property.

   The Query property contains the WMI Query Language (WQL) query that describes the type of event you want filtered. You can achieve precise filtering using a variety of operators and extensions to WQL.

   An NT Log event is generated when a query from a permanent event consumer fails. The event's source is WinMgmt, the event ID is 10, and the event type is Error.

   WMI is more efficient at processing restrictive, specific queries than broad queries. By creating a specific query, you can avoid unnecessary inter-process communication and network traffic. In cases of events generated by a provider, WMI performs the filtering in process to the provider; this ensures that only events matching the filter incur the interprocess communication cost. For more information, see Querying WMI.

4. Set the QueryLanguage property to the type of query language you use in the Query property.

   You will almost always set QueryLanguage to "WQL".

The following code example describes an event filter that signals an event each time WMI creates an instance of the __TimerEvent class in the root\cimv2 namespace.

instance of __EventFilter as $FILTER
{
    Name = "MyFilterName";
    Query = "select * from __TimerEvent where TimerID=\"MyTimer\"";
    QueryLanguage = "WQL";
    EventNamespace = "\root\cimv2";

    // this is the Administrators SID in array of bytes format
    CreatorSID = {1,2,0,0,0,0,0,5,32,0,0,0,32,2,0,0}; 
};

The EventNamespace property specifies the namespace from which the events originate. You do not have to create an instance of the filters in the namespace where the events originate. If you do not specify the namespace, then WMI creates the filter in the default namespace. The intrinsic events classes, such as __InstanceOperationEvent are available in every namespace.

To register your logical consumer for event notifications, you must bind the event filters to a logical consumer. For more information, see Binding an Event Filter with a Logical Consumer.