IWbemServices::ExecNotificationQuery method

The IWbemServices::ExecNotificationQuery method executes a query to receive events. The call returns immediately, and the user can poll the returned enumerator for events as they arrive. Releasing the returned enumerator cancels the query.

Syntax


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

Parameters

strQueryLanguage [in]

Valid BSTR that contains one of the query languages supported by Windows Management. This cannot be NULL. Currently, only the WMI Query Language (WQL) is supported.

strQuery [in]

Valid BSTR that contains the text of the event-related query. This cannot be NULL. For more information on building WMI query strings, see Querying with WQL and the WQL reference.

lFlags [in]

This parameter must be set to both WBEM_FLAG_RETURN_IMMEDIATELY and WBEM_FLAG_FORWARD_ONLY or the call fails.

FlagMeaning
WBEM_FLAG_FORWARD_ONLY

This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.

WBEM_FLAG_RETURN_IMMEDIATELY

The user must specify this flag or the call fails. This is because events are received continuously, which means the user must poll the returned enumerator. Blocking this call indefinitely while waiting for a possible event blocks the thread for an indefinite amount of time. For more information, see Calling a Method.

 

pCtx [in]

Typically NULL. Otherwise, this is a pointer to an IWbemContext object that can be used by the provider that provides the requested events. The values in the context object must be specified in the documentation for the provider in question. For more information about this parameter, see Making Calls to WMI.

ppEnum [out]

If no error occurs, this parameter receives the enumerator that allows the caller to retrieve the instances in the result set of the query. The caller periodically calls IEnumWbemClassObject::Next to see if any events are available. Notice that, in this usage, Reset does not move the enumerator back to the beginning of the event sequence; it has no effect. The parameter can continue to receive events until Release is called on the returned enumerator.

Return value

This method returns an HRESULT that indicates the status of the method call. The following table lists the value contained within an HRESULT.

On failure, you can obtain any available information from the COM function GetErrorInfo.

COM-specific error codes also can be returned if network problems cause you to lose the remote connection to Windows Management.

Return codeDescription
WBEM_E_ACCESS_DENIED

The current user is not authorized to view the result set.

WBEM_E_FAILED

This indicates other unspecified errors.

WBEM_E_INVALID_CLASS

The query specifies a class that does not exist.

WBEM_E_INVALID_PARAMETER

A specified parameter is not valid.

WBEM_E_REGISTRATION_TOO_PRECISE

Too much precision in delivery of events has been requested. A larger polling tolerance must be specified.

WBEM_E_REGISTRATION_TOO_BROAD

The query requests more information than Windows Management can reasonably provide. This message is returned when an event query results in a request to poll all objects in a namespace.

WBEM_E_INVALID_QUERY

The query was not syntactically valid.

WBEM_E_INVALID_QUERY_TYPE

The requested query language is not supported.

WBEM_E_OUT_OF_MEMORY

There was not enough memory to complete the operation.

WBEM_E_TRANSPORT_FAILURE

This indicates the failure of the remote procedure call (RPC) link between the current process and Windows Management.

WBEM_E_SHUTTING_DOWN

Windows Management service was stopped and restarted. A new call to ConnectServer is required.

WBEM_E_UNPARSABLE_QUERY

The query cannot be parsed.

WBEM_S_NO_ERROR

The call succeeded.

 

Remarks

There are limits to the number of AND and OR keywords that can be used in WQL queries. Large numbers of WQL keywords used in a complex query can cause WMI to return the WBEM_E_QUOTA_VIOLATION error code as an HRESULT value. The limit of WQL keywords depends on how complex the query is.

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Fastprox.dll;
Esscli.dll;
Framedyn.dll;
Ntevt.dll;
Stdprov.dll;
Viewprov.dll;
Wbemcomn.dll;
Wbemcore.dll;
Wbemess.dll;
Wbemsvc.dll;
Wmipicmp.dll;
Wmidcprv.dll;
Wmipjobj.dll;
Wmiprvsd.dll

See also

IWbemServices
Receiving Events for the Duration of your Application
Retrieving an Error Code
Querying with WQL
IWbemServices::ExecNotificationQueryAsync

 

 

Show:
© 2014 Microsoft