Interface IWbemEventProviderQuerySink¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemEventProviderQuerySink interface is optionally implemented by event providers who want to know what kinds of event query filters are currently active in order to optimize performance.
Methods in Vtable Order
| Iunknown Methods | Description |
| QueryInterface_hmm_IWbemEventProviderQuerySink_QueryInterface | Determines if the current object supports a given interface. |
| AddRef_hmm_IWbemEventProviderQuerySink_AddRef | Increases the object's reference count by 1. |
| Release_hmm_IWbemEventProviderQuerySink_Release | Decrements the object's reference count, and frees the object when the reference count is zero. |
| IWbemEventProviderQuerySink Methods | Description |
| NewQuery_hmm_IwbemEventProviderQuerySink_NewQuery | Called whenever a new consumer query is registered with CIMOM. |
| CancelQuery_hmm_IwbemEventProviderQuerySink_CancelQuery | Called whenever a consumer query is canceled or unregistered. |
‹^# $ K + ›IWbemEventProviderQuerySink::QueryInterface¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemEventProviderQuerySink::QueryInterface method determines if the object supports a particular COM interface. If it does, the system increases the object's reference count, which means the application can use that interface immediately.
HRESULT IWbemEventProviderQuerySink::QueryInterface(
[in] REFIID riid,
[out] LPVOID *ppv
);
Parameters
riid
The COM interface identifier of the requested interface.
obp
Address of a pointer that will be filled with the interface pointer if the query succeeds.
Return Values
Returns standard COM error codes for QueryInterface. It returns WBEM_S_NO_ERROR if the call succeeds. If the call fails because the requested interface was not supported, the method returns E_NOINTERFACE.
Remarks
When the application no longer needs the interface retrieved by a call to this method, it must call the Release method for that interface to free it. The QueryInterface method allows the extension of objects without interfering with each object's existing or future functionality.‹Dave, This one is cut and pasted! - Howie›
This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_IUnknown_Interface_Basics
‹^# $ K + ›IWbemEventProviderQuerySink::AddRef¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemEventProviderQuerySink::AddRef method increases the object's reference count by 1.
ULONG AddRef( );
Parameters
None.
Return Values
Returns the new reference count.
Remarks
When the object is created, its reference count is set to 1. Every time an application obtains an interface to the object or calls the AddRef method, the object's reference count is increased by 1. Use the Release_hmm_IWbemEventProviderQuerySink_Release method to decrease the object's reference count by 1.
This method is part of the IUnknown interface inherited by the object. For a complete discussion of IUnknown methods, see IUnknown Programming Basics.
For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_IUnknown_Interface_Basics
‹^# $ K + ›IWbemEventProviderQuerySink::Release¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
The IWbemEventProviderQuerySink::Release method decreases the object's reference count by 1.
ULONG IWbemEventProviderQuerySink::Release( );
Parameters
None.
Return Values
Returns the new reference count.
Remarks
The object deallocates itself when its reference count reaches zero. Use the AddRef_hmm_IWbemEventProviderQuerySink_AddRef method to increase the object's reference count by 1.
This method is part of the IUnknown interface inherited by the object. For more information about this method, see the COM documentation in the Microsoft Platform SDK.
See Also
IUnknown Interface Basics_hmm_IUnknown_Interface_Basics
‹^# $ K + ›IWbemEventProviderQuerySink::NewQuery¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
Call this method whenever a logical event consumer registers a relevant event query filter with CIMOM.
HRESULT IWbemEventProviderQuerySink::NewQuery(
[in] UNSIGNED LONG dwId,
[in] WBEM_WSTR wszQueryLanguage,
[in] WBEM_WSTR wszQuery
);
Parameters
dwId
A CIMOM-generated ID for the query. The provider can track this so that during a later cancelation it will know which query was canceled.
wszQueryLanguage
The language of the following query filter. For this version of WBEM, it will always be "WQL."
wszQuery
The text of the event query filter, which was registered by a logical consumer.
Return Values
Return Values
| WBEM_E_FAILED | The provider failed internally, and it cannot accept future requests. |
| 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 CIMOM and the query contains references to events provided by the current event provider, CIMOM can notify the event provider of the query.
If the provider implements the IWbemEventProviderQuerySink interface, CIMOM 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.
CIMOM 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 very 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 such time as consumers actually begin requesting such events.
For each new consumer query filter, a separate call to this method will be made. For this version of WBEM, the query language is always "WQL."
See Also
Constructing Event Providers, IWbemEventProviderQuerySink::CancelQuery
‹^# $ K + ›IWbemEventProviderQuerySink::CancelQuery¦@¦
<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>
Call this method whenever a logical event consumer cancels a relevant event query filter with CIMOM.
HRESULT IWbemEventProviderQuerySink::CancelQuery(
[in] UNSIGNED LONG dwId
);
Parameters
dwId
The ID of the query which was canceled. This ID was originally delivered to the provider by the NewQuery method of this interface.
Return Values
| WBEM_E_FAILED | The provider failed internally, and it cannot accept future requests. |
| WBEM_S_NO_ERROR | The provider received the sink, and it will begin delivery of events. |
Remarks
Whenever a consumer registers a new event query filter, CIMOM calls the IWbemEventProviderQuerySink::NewQuery method with the query ID. Later on, when that query is unregistered, this method is called indicating which query is no longer outstanding.
Providers use this to help optimize the generation of events internally.
See Also
IWbemEventProviderQuerySink::NewQuery