IWbemEventProviderQuerySink::NewQuery method

Call the IWbemEventProviderQuerySink::NewQuery method when a logical event consumer registers a relevant event query filter with Windows Management. The NewQuery method determines how a provider responds to a new query registered by a client application. When WMI receives a new or modified event query from a consumer, WMI calls NewQuery to echo the query to the event provider. The provider then generates the requested notification.

Syntax


HRESULT NewQuery(
  [in]  unsigned long dwId,
  [in]  WBEM_WSTR     wszQueryLanguage,
  [in]  WBEM_WSTR     wszQuery
);

Parameters

dwId [in]

Windows Management-generated identifier for the query. The provider can track this so that during a later call to CancelQuery so that the provider will know which query was canceled.

wszQueryLanguage [in]

Language of the following query filter. For this version of WMI, it will always be "WQL".

wszQuery [in]

Text of the event query filter, which was registered by a logical consumer. The event provider can examine the text of the query filter through the wszQuery parameter and the language of the query filter in the wszQueryLanguage parameter to discover which event notifications the consumer is requesting.

Return value

This method returns an HRESULT indicating the status of the method call. The following table lists return codes returned by NewQuery. Additionally, a third-party event provider could return any valid WMI or COM return code which could be passed through NewQuery as a return value.

Return codeDescription
WBEM_E_ACCESS_DENIED

The user does not have permission to access the event.

WBEM_E_FAILED

The provider failed internally, and it cannot accept future requests.

WBEM_E_INVALID_QUERY

The query was not syntactically valid, or the query references a nonexistent class, property, or so on.

WBEM_S_NO_ERROR

The provider received the sink, and it will begin delivery of events.

 

Remarks

If a consumer registers an event filter query with Windows Management and the query contains references to events provided by the current event provider, Windows Management can notify the event provider of the query.

If the provider implements the IWbemEventProviderQuerySink interface, Windows Management will provide a copy of the query text to the provider. The provider should parse the query, and determine if it can perform any internal optimization.

Windows Management does not expect a provider to alter its behavior in any way. Rather, this is an advisory call to assist the provider with internal optimization.

For example, if the provider is capable of providing many hundreds of events, but the required overhead for providing all of them is great, the provider can achieve substantial savings if it knows that most of these events are not required by the current set of event consumers. If the provider implements IWbemEventProviderQuerySink, it will know about the current set of events requested by all consumers. It may be able to avoid setting up the mechanisms for delivering most of the event types that it supports until consumers actually begin requesting such events.

For each new consumer query filter, a separate call to this method with a unique dwId will be made. Be aware that Windows Management reserves the right to call NewQuery more than one time for the same dwId value; for example, if there is a schema change elsewhere in the system. For this version of WMI, the query language is always "WQL".

The IWbemEventProviderQuerySink::NewQuery method can be called before the IWbemEventProvider::ProvideEvents method.

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Wbemprov.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Wbemsvc.dll

See also

IWbemEventProviderQuerySink
IWbemEventProviderQuerySink::CancelQuery

 

 

Show:
© 2015 Microsoft