Event Queries

[This is preliminary documentation and subject to change.]

When consumers register to receive event notifications, they specify a query that defines the type of event and the conditions under which it is delivered to them. These conditions depend on the properties that exist for the class used to represent the event. To create a query, consumers use the WBEM Query Language (WQL). WQL is a structured query language (SQL) dialect with extensions to support WBEM event notification and other WBEM-specific features.

In general, a query is limited to the form:

select <* | property_list> from <ClassName> 
  where <selection_criteria>;

The SELECT clause specifies the properties and the FROM clause specifies the class that correspond to the event of interest. The WHERE clause specifies additional filtering and is optional. Without a WHERE clause, consumers receive all notifications for the event class; with a WHERE clause, consumers receive only particular notifications for the event class. WBEM strongly encourages consumers to use extremely detailled WHERE clauses. The cost of a complex query is minimal compared to the cost of delivering and processing unneeded notifications..

The following query shows how to request notification when disk space falls below one megabyte of free space. The SELECT statement requests all properties of the event class __InstanceModificationEvent. The WHERE clause narrows the receipt of that event to instances of the Win32LogicalDisk class when the FreeSpace property has a value of less than one million:

Select * from __InstanceModificationEvent 
where TargetInstance isa "Win32LogicalDisk" and TargetInstance.FreeSpace < 1000000

Note that CIMOM can reject a query for a number of reasons. For example, the query can be too complex or resource-intensive for evaluation. When this occurs, CIMOM returns WBEM_E_INVALID_PARAMETER. For more information about event queries, see SELECT Statements for Event Notifications.

Queries are specified differently depending on the type of consumer. Temporary consumers are consumers whose event registration lasts only for the lifetime of the consumer. Temporary consumers specify their queries in the bstrQuery parameter when they call either IWbemServices::ExecNotificationQuery or IWbemServices::ExecNotificationQueryAsync. Permanent consumers are consumers whose registration lasts until it is explicitly cancelled. Permanent consumers specify their queries in instances of the __EventFilter system class.