405 lines
17 KiB
HTML
405 lines
17 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<title>Interface IWbemEventProviderQuerySink</title>
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<p> <font FACE="Arial Narrow" SIZE="6" COLOR="#800000"></p>
|
|
|
|
<p></font><b><font FACE="Arial Narrow" SIZE="6">Interface IWbemEventProviderQuerySink</font><font
|
|
FACE="Arial Narrow" SIZE="1" COLOR="#800000">¦@¦</font></b><font SIZE="2"
|
|
COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>The <b>IWbemEventProviderQuerySink</b> 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.</font><b><font FACE="Arial" SIZE="2" COLOR="#008000"> </font><font
|
|
FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Methods in Vtable Order</font></b></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Iunknown Methods</b></font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Description</b></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>QueryInterface</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemEventProviderQuerySink_QueryInterface</font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Determines if the current object
|
|
supports a given interface.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>AddRef</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemEventProviderQuerySink_AddRef</font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Increases the object's reference
|
|
count by 1.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>Release</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemEventProviderQuerySink_Release</font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Decrements the object's reference
|
|
count, and frees the object when the reference count is zero.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p> </p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td VALIGN="TOP" COLSPAN="2"></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>IWbemEventProviderQuerySink
|
|
Methods</b></font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Description</b></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>NewQuery</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IwbemEventProviderQuerySink_NewQuery</font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2" COLOR="#008000">Called whenever a
|
|
new consumer query is registered with CIMOM.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="37%" VALIGN="TOP"><font FACE="Arial" SIZE="2"><u><b>CancelQuery</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IwbemEventProviderQuerySink_CancelQuery</font></td>
|
|
<td WIDTH="63%" VALIGN="TOP"><font FACE="Arial" SIZE="2">Called whenever a consumer query
|
|
is canceled or unregistered.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p> <font FACE="Arial" SIZE="1"></p>
|
|
|
|
<p> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IWbemEventProviderQuerySink::QueryInterface</font><font FACE="Arial Narrow"
|
|
SIZE="1" COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>The <b>IWbemEventProviderQuerySink::QueryInterface</b> 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.</font><font
|
|
FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>HRESULT IWbemEventProviderQuerySink::QueryInterface(</p>
|
|
|
|
<p>[in] REFIID</b><i> riid</i><b>,</p>
|
|
|
|
<p>[out] LPVOID</b><i> *ppv</i><b></p>
|
|
|
|
<p>);</b></p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Parameters</b></font><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>riid</p>
|
|
|
|
<blockquote>
|
|
</i><p>The COM interface identifier of the requested interface.</p>
|
|
</blockquote>
|
|
|
|
<p> <i></p>
|
|
|
|
<p>obp</p>
|
|
|
|
<blockquote>
|
|
</i><p>Address of a pointer that will be filled with the interface pointer if the query
|
|
succeeds.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
|
|
<p> <font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Returns standard COM error codes for <b>QueryInterface</b><i>. </i>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.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>When the application no longer needs the interface retrieved by a call to this method,
|
|
it must call the <b>Release</b> method for that interface to free it. The <b>QueryInterface</b>
|
|
method allows the extension of objects without interfering with each object's existing or
|
|
future functionality.</font><font FACE="Arial" SIZE="2" COLOR="#008000"><b>‹Dave,
|
|
This one is cut and pasted! - Howie›</b></font><font FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>This method is part of the <b>IUnknown</b> interface inherited by the object. For more
|
|
information about this method, see the COM documentation in the Microsoft Platform SDK.</font><b><font
|
|
FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
|
|
|
|
<p>IUnknown Interface Basics</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnknown_Interface_Basics</font><font
|
|
FACE="Arial" SIZE="2"> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IWbemEventProviderQuerySink::AddRef</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>The <b>IWbemEventProviderQuerySink::AddRef</b> method increases the object's reference
|
|
count by 1.</font><font FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>ULONG AddRef( );</b></p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Parameters</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>None.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Returns the new reference count.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>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 <b>AddRef</b> method, the object's
|
|
reference count is increased by 1. Use the <u><b>Release</b></u></font><font FACE="Arial"
|
|
SIZE="2" COLOR="#800000">_hmm_IWbemEventProviderQuerySink_Release</font><font FACE="Arial"
|
|
SIZE="2"> method to decrease the object's reference count by 1. </p>
|
|
|
|
<p>This method is part of the <b>IUnknown</b> interface inherited by the object. For a
|
|
complete discussion of <b>IUnknown</b> methods, see <b>IUnknown Programming Basics</b>.</p>
|
|
|
|
<p>For more information about this method, see the COM documentation in the Microsoft
|
|
Platform SDK.</font><b><font FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
|
|
|
|
<p>IUnknown Interface Basics</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnknown_Interface_Basics</font><font
|
|
FACE="Arial" SIZE="2"> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IWbemEventProviderQuerySink::Release</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>The <b>IWbemEventProviderQuerySink::Release</b> method decreases the object's reference
|
|
count by 1.</font><b><font FACE="Lucida Sans Typewriter" SIZE="2"></p>
|
|
|
|
<p>ULONG IWbemEventProviderQuerySink::Release( );</p>
|
|
|
|
<p></font><font FACE="Arial Narrow"> </p>
|
|
|
|
<p>Parameters</font></b><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>None.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Returns the new reference count.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>The object deallocates itself when its reference count reaches zero. Use the <u><b>AddRef</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemEventProviderQuerySink_AddRef</font><font
|
|
FACE="Arial" SIZE="2"> method to increase the object's reference count by 1.</p>
|
|
|
|
<p>This method is part of the <b>IUnknown</b> interface inherited by the object. For more
|
|
information about this method, see the COM documentation in the Microsoft Platform SDK.</font><b><font
|
|
FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
|
|
|
|
<p>IUnknown Interface Basics</u></font></b><font FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IUnknown_Interface_Basics</font><font
|
|
FACE="Arial" SIZE="2"> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IWbemEventProviderQuerySink::NewQuery</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>Call this method whenever a logical event consumer registers a relevant event query
|
|
filter with CIMOM. </font><font FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>HRESULT IWbemEventProviderQuerySink::NewQuery(</p>
|
|
|
|
<p>[in] UNSIGNED LONG </b><i>dwId</i><b>,</p>
|
|
|
|
<p>[in] WBEM_WSTR</b><i> wszQueryLanguage</i><b>,</p>
|
|
|
|
<p>[in] WBEM_WSTR</b><i> wszQuery</i><b></p>
|
|
|
|
<p>);</b></p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Parameters</b></font><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>dwId</p>
|
|
|
|
<blockquote>
|
|
</i><p>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.</p>
|
|
</blockquote>
|
|
|
|
<p> <i></p>
|
|
|
|
<p>wszQueryLanguage</p>
|
|
|
|
<blockquote>
|
|
</i><p>The language of the following query filter. For this version of WBEM, it will
|
|
always be "WQL."</p>
|
|
</blockquote>
|
|
|
|
<p> <i></p>
|
|
|
|
<p>wszQuery</p>
|
|
|
|
<blockquote>
|
|
</i><p>The text of the event query filter, which was registered by a logical consumer.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
|
|
<p> <font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</p>
|
|
|
|
<p>Return Values</b></font></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The provider failed internally,
|
|
and it cannot accept future requests.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The provider received the sink,
|
|
and it will begin delivery of events.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p> <font FACE="Arial" SIZE="1"></p>
|
|
|
|
<p> </font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>If the provider implements the <b>IWbemEventProviderQuerySink </b>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.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>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 <b>IWbemEventProviderQuerySink</b>,<b> </b>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.</p>
|
|
|
|
<p>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."</font><b><font
|
|
FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Constructing Event Providers</b>, <b>IWbemEventProviderQuerySink::CancelQuery</b></p>
|
|
|
|
<p> </font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000"></p>
|
|
|
|
<p>‹^</font><font FACE="Arial Narrow" SIZE="5"><b># $ K + </b></font><font
|
|
FACE="Arial Narrow" SIZE="5" COLOR="#800000">›</font><b><font FACE="Arial Narrow"
|
|
SIZE="5">IWbemEventProviderQuerySink::CancelQuery</font><font FACE="Arial Narrow" SIZE="1"
|
|
COLOR="#800000">¦@¦</font></b><font SIZE="2" COLOR="#ff00ff"></p>
|
|
|
|
<p><span style=color:#FF0000></font><font FACE="Arial" SIZE="2" COLOR="#ff0000">[This
|
|
is preliminary documentation and subject to change.]</font><font SIZE="2" COLOR="#ff00ff"></span></font><font
|
|
FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>Call this method whenever a logical event consumer cancels a relevant event query
|
|
filter with CIMOM. </font><font FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>HRESULT IWbemEventProviderQuerySink::CancelQuery(</p>
|
|
|
|
<p>[in] UNSIGNED LONG </b><i>dwId</i><b></p>
|
|
|
|
<p>);</b></p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Parameters</b></font><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>dwId</p>
|
|
|
|
<blockquote>
|
|
<blockquote>
|
|
</i><p>The ID of the query which was canceled. This ID was originally delivered to the
|
|
provider by the <b>NewQuery </b>method of this interface.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
</blockquote>
|
|
|
|
<p> <font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Return Values</b></font></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The provider failed internally,
|
|
and it cannot accept future requests.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The provider received the sink,
|
|
and it will begin delivery of events.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p> <font FACE="Arial" SIZE="1"></p>
|
|
|
|
<p> </font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>Whenever a consumer registers a new event query filter, CIMOM calls the <b>IWbemEventProviderQuerySink::NewQuery
|
|
</b>method with the query ID. Later on, when that query is unregistered, this method is
|
|
called indicating which query is no longer outstanding.</p>
|
|
|
|
<p>Providers use this to help optimize the generation of events internally.</font><b><font
|
|
FACE="Arial Narrow"></p>
|
|
|
|
<p>See Also</font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>IWbemEventProviderQuerySink::NewQuery</font></b><font FACE="Arial" SIZE="3"
|
|
COLOR="#008000"></p>
|
|
|
|
<p></font> </p>
|
|
</body>
|
|
</html>
|