Share via

3.1.4.3.21 IWbemServices::ExecNotificationQueryAsync (Opnum 23)

  • Article

The IWbemServices::ExecNotificationQueryAsync method is the asynchronous version of the IWbemServices::ExecNotificationQuery method. The IWbemServices::ExecNotificationQueryAsync method provides subscription for asynchronous event notifications. When this method is invoked, the server performs the same task as the IWbemServices::ExecNotificationQuery method, except that events are supplied to the specified response handler (pResponseHandler) until the IWbemServices::CancelAsyncCall method is called.

 HRESULT ExecNotificationQueryAsync(
   [in] const BSTR strQueryLanguage,
   [in] const BSTR strQuery,
   [in] long lFlags,
   [in] IWbemContext* pCtx,
   [in] IWbemObjectSink* pResponseHandler
 );

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::ExecNotificationQueryAsync 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.

WBEM_FLAG_SEND_STATUS

0x00000080

This flag is ignored.

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, this parameter MUST be ignored.

pResponseHandler: MUST be a pointer to the IWbemObjectSink interface that is implemented by the caller, where enumeration results are delivered. 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 following validation occurs before an asynchronous operation is started.

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.

This method MUST fail if strQueryLanguage or strQuery does not exist.

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

Requirements mentioned in the parameter definitions are also checked before the asynchronous operation is started.

If successful, the server MUST create a new entry in AsyncOperationTable as specified in section 3.1.1.1.3.

The following validation happens asynchronously.

In response to IWbemServices::ExecNotificationQueryAsync, the server MUST evaluate the strQueryLanguage and strQuery parameters (as specified earlier in this section) and MUST start to provide events that match the requested 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.

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 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.

If method execution succeeds, the server MUST run the notification query until the query is canceled or execution fails. The server MUST NOT call IWbemObjectSink::SetStatus to send success or operation progress information. When query execution fails, the server MUST call IWbemObjectSink::SetStatus to send the error to the client, and the server MUST release IWbemObjectSink.

If the strQuery is evaluated successfully, the server MUST create an entry (row) in the EventBindingTable. If strQuery includes a WITHIN clause, 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.<55>

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 cancels the query. If strQuery specified an EventPollingTimer, the server MUST also cancel the timer. If strQuery specified an EventGroupingTimer, the server MUST also cancel the timer.