3.1.4.3.20 IWbemServices::ExecNotificationQuery (Opnum 22)
The IWbemServices::ExecNotificationQuery method provides subscription for event notifications. When invoked, the server executes a query to receive events. The call returns immediately, and 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 contain one of the query languages supported by WMI. This parameter MUST NOT be NULL.<18>
lFlags: Flags that affect the behavior of the IWbemServices::ExecNotificationQuery method. The flags' 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 | When the bit is set, the server MUST return an enumerator without 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 the client wants to pass to the server. If pCtx is NULL, the parameter MUST be ignored.
ppEnum: MUST be an out parameter, which MUST implement the IEnumWbemClassObject interface, which MUST receive the pointer to the enumerator that is used to enumerate through the CIM objects 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 making the call MUST have WBEM_ENABLE and WBEM_REMOTE_ENABLE accesses to the namespace.
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 returned by the server is not finite, the method IWbemServices::ExecNotificationQuery MUST NOT be executed synchronously. This request MUST fail as the method parameters are not valid, as previously specified.
The successful semisynchronous method execution MUST return immediately, it MUST fill ppEnum parameter with a new IEnumWbemClassObject interface pointer and MUST return WBEM_S_NO_ERROR as specified in section 3.1.1.1.2.
The failed method execution MUST set the value referenced by the output parameters to NULL and MUST return an error in the format as specified in section 2.2.11.