3.1.4.3.20 IWbemServices::ExecNotificationQuery (Opnum 22)

  • Article

The IWbemServices::ExecNotificationQuery method provides a subscription for event notifications. When this method is invoked, the server runs a query to deliver events matching the query. The call is executed semisynchronously and MUST follow the rules that are specified in section 3.1.1.1.2. The WMI client can poll the returned enumerator for events as they arrive. Releasing the returned enumerator cancels the query.

 HRESULT ExecNotificationQuery(
   [in] const BSTR strQueryLanguage,
   [in] const BSTR strQuery,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [out] IEnumWbemClassObject** ppEnum
 );

strQueryLanguage: MUST be set to "WQL".

strQuery: MUST contain the WQL event-related query text as specified in section 2.2.1. This parameter MUST NOT be NULL.

lFlags: Specifies the behavior of the IWbemServices::ExecNotificationQuery method. Flag behavior MUST be interpreted as specified in the following table.

The server MUST allow any combination of zero or more flags from the following table and MUST comply with all the restrictions in a flag description. Any other DWORD value that does not match a flag condition MUST be treated as not valid.

Value

Meaning

WBEM_FLAG_USE_AMENDED_QUALIFIERS

0x00020000

If this bit is not set, the server SHOULD return no CIM localizable information.

If this bit is set, the server SHOULD return CIM localizable information for the CIM object, as specified in section 2.2.6.

WBEM_FLAG_RETURN_IMMEDIATELY

0x00000010

If this bit is set, the server MUST make the method call semisynchronously.

This flag MUST always be set.

WBEM_FLAG_FORWARD_ONLY

0x00000020

If this bit is set, the server MUST return an enumerator that does not have reset capability, as specified in section 3.1.4.4.

This flag MUST always be set.

pCtx: MUST be a pointer to an IWbemContext interface, which MUST contain additional information that the client wants to pass to the server. If pCtx is NULL, the parameter MUST be ignored.

ppEnum: MUST receive the pointer to the IEnumWbemClassObject that is used to enumerate through the CIM objects that are returned for the query result set. This parameter MUST NOT be NULL.

Return Values: This method MUST return an HRESULT value that MUST indicate the status of the method call. The server MUST return WBEM_S_NO_ERROR (as specified in section 2.2.11) to indicate the successful completion of the method.

WBEM_S_NO_ERROR (0x00)

The security principal that makes the call MUST have WBEM_ENABLE and WBEM_REMOTE_ENABLE accesses to the namespace; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

In response to IWbemServices::ExecNotificationQuery, the server MUST evaluate the strQuery and strQueryLanguage parameters (as specified in this section) and MUST return all events that match the query. The method MUST fail if the method parameters or their combinations are not valid as specified earlier in this section, or if the server is unable to execute the method. Because the stream of events that are returned by the server is not finite, the method IWbemServices::ExecNotificationQuery MUST NOT be executed synchronously. As previously specified, this request MUST fail because the method parameters are not valid.

For each provider in the ProviderTable where EventQueryList is not empty:

  • For each query in EventQueryList, the server MUST check whether the instance of a CIM class passed as part of strQuery is a logical subset of the query.

If no query is matched, the server MUST return WBEM_E_INVALID_CLASS.

If strQuery is evaluated successfully, the server MUST create an entry (row) in the EventBindingTable. If strQuery includes a WITHIN clause, then the server MUST create an EventPollingTimer, set its interval to the number of seconds specified in the WITHIN clause, and start the timer. If strQuery includes a GROUP WITHIN clause, then the server MUST create an EventGroupingTimer and set its interval to the number of seconds specified in the GROUP WITHIN clause. The server MUST set ClientSecurityContext to RpcImpersonationAccessToken.Sids[UserIndex]). The server response to out-of-range time intervals is implementation-dependent.<52>

If either WITHIN or GROUP WITHIN clause is specified, the server MUST query for the instances of the underlying CIM class (for which the notifications are requested) in the strQuery and populate EventBindingTable.PrevInstances with the list of instances.

The server MUST delete the row when the client releases all references to the IEnumWbemClassObject Interface returned in ppEnum. If strQuery specified an EventPollingTimer, the server MUST also cancel the timer. If strQuery specified an EventGroupingTimer, the server MUST also cancel the timer.

The server SHOULD enforce a maximum length for the strQuery parameter, and return WBEM_E_QUOTA_VIOLATION if the limit is exceeded.<53>

If the FROM clause of strQuery represents a class that is not derived from __Event, the server MUST return WBEM_E_NOT_EVENT_CLASS.

If the GROUP BY clause of strQuery does not have WITHIN specified, the server MUST return WBEM_E_MISSING_GROUP_WITHIN.

If the GROUP BY clause of strQuery was used with aggregation that is not supported, the server MUST return WBEM_E_MISSING_AGGREGATION_LIST.

If the GROUP BY clause of strQuery references an object that is an embedded object without using Dot notation, the server MUST return WBEM_E_AGGREGATING_BY_OBJECT.

If WITHIN clause is not specified as part of strQuery that contains an intrinsic event class, the server MUST return WBEM_E_REGISTRATION_TOO_PRECISE.

If the strQuery is not syntactically valid or one or more elements in <PROPERTY-LIST> contains undefined properties, the server MUST return WBEM_E_INVALID_QUERY.

The failed method execution MUST set the value that is referenced by the output parameters to NULL and MUST return an error in the format specified in section 2.2.11.