Creating an Event Filter

[This is preliminary documentation and subject to change.]

An event filter defines the criteria for receiving an event notification and is an instance of the system class __EventFilter. Administrators create event filters to indicate the class of event that they want to receive and the conditions under which they want to receive it. As with events, event filters belong to a namespace. That is, each event filter works only on events that belong to the namespace to which the filter also belongs.

The __EventFilter system class has three properties:

• Name
• Query
• QueryLanguage

The Name property is a string that uniquely identifies the event filter. Because an event filter is only used internally by CIMOM, WBEM recommends that the Name be set to a GUID converted into a string. However, consumers can use any private scheme for filter naming as long as there is no chance for conflict with other filters.

The Query property is a string that specifies the event criteria.

The QueryLanguage property specifies the language used for the query. Because WBEM currently supports only WQL as a query language, Query must be set to a valid WQL statement and QueryLanguage must be set to "WQL.".

For example, the following event filter requests an instance creation event whenever a new DiskDrive instance is created:

Instance of __EventFilter
{
    Name = "{7ca44681-045f-11d1-ae97-00c04fb68820}";'
].
    Query = 
           "select * from __InstanceCreationEvent "
           "where TargetInstance.__CLASS = \"DiskDrive\"";
    QueryLanguage = "WQL";
}

Note that the preceding query specifies that only creation events for instances of the DiskDrive class are candidates for event notification. This does not include instances of classes derived from the DiskDrive class. If you want to receive events that apply to any instance of DiskDrive class or its derived classes, use the isa ("is a") operator in the Query property of the event filter as follows:

Instance of __EventFilter
{
    Name = "{7ca44681-045f-11d1-ae97-00c04fb68820}"
    Query = 
           "select * from __InstanceCreationEvent "
           "where TargetInstance isa \"DiskDrive\"";
    QueryLanguage = "WQL";
}

Administrators can narrow the scope of their queries if there are properties defined for the target class. For example, if the DiskDrive class includes an ID property, it is possible to request an event notification only when the value of the drive's ID property is within a particular range:

Instance of __EventFilter
{
    Name = "{7ca44681-045f-11d1-ae97-00c04fb68820}"
    Query = 
          "Select * from __InstanceCreationEvent" 
          "where TargetInstance isa \"DiskDrive\"" 
          "and (TargetInstance.ID < 100 or TargetInstance.ID > 500)";
    QueryLanguage = "WQL";
}

TargetInstance contains a copy of the object that was created, modified, or deleted. Because TargetInstance is weakly typed, it is legal to use property names that occur in the affected object at event time.

Since the query can take on any legal form within the bounds of WQL, administrators can achieve very precise filtering. For example, placing the NOT operator in front of the parenthesized OR clause in the previous query example returns the complement result set. Administrators are encouraged to specify the most restrictive query possible to avoid needless interprocess communication and network traffic. It is best to allow CIMOM do as much filtering as possible.