714 lines
30 KiB
HTML
714 lines
30 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<title>Interface IEnumWbemClassObject</title>
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFC1">
|
|
<b><font FACE="Arial Narrow" SIZE="6" COLOR="#008000">
|
|
|
|
<p></font><font FACE="Arial Narrow" SIZE="6">Interface</b><font color="#800000"> </font><b>IEnumWbemClassObject</b></font><font
|
|
FACE="Arial Narrow" SIZE="6" COLOR="#800000"></p>
|
|
</font><font FACE="Arial" SIZE="2">
|
|
|
|
<p>Rev. 1.01, 27-Aug-98, RayMcc</p>
|
|
|
|
<p>The <b>IEnumWbemClassObject</b> interface is similar to a standard Component Object
|
|
Model (COM) enumerator. It works with objects of type <b>IWbemClassObject</b>. However,
|
|
some extensions over standard COM enumerators have been added to accommodate WBEM
|
|
requirements.</p>
|
|
|
|
<p>The enumerator is a logical container of Common Information Model (CIM) objects. It is
|
|
designed for sequential retrieval. An enumerator has a current position, or cursor,
|
|
beginning at offset zero, which is the first element, and moves sequentially through the
|
|
set of objects. When you call the <b>Reset</b> method, once again the current position is
|
|
set to zero, or the first object. Calling the <b>Next</b> method retrieves the requested
|
|
objects. It updates the current position so that subsequent calls to <b>Next</b> retrieve
|
|
the objects. Eventually, you reach the end of the sequence, and cannot retrieve any more
|
|
objects. At this point, you can restart the enumerator by calling <b>Reset</b>, or you can
|
|
discard it by using the <b>Release</b> method.</p>
|
|
|
|
<p>For documentation on the semantics of COM enumerators, see <b>IEnumVariant</b> in the
|
|
Microsoft</font><font FACE="Arial" SIZE="1">®</font><font FACE="Arial" SIZE="2"> Platform
|
|
SDK. The <b>IEnumWbemClassObject</b> interface semantically resembles the standard
|
|
enumerators, except that it is designed also to support asynchronous and semisynchronous
|
|
call behavior.</p>
|
|
</font>
|
|
|
|
<p><font FACE="Arial" SIZE="2">This interface is derived from <strong>IUnknown </strong>and
|
|
supports its methods.</font></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="585">
|
|
<tr>
|
|
<td VALIGN="TOP" COLSPAN="2" width="583"></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="187" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Methods</b></font></td>
|
|
<td WIDTH="394" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Description</b></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="187" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000"><b>Reset</b></font></td>
|
|
<td WIDTH="394" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Resets the cursor
|
|
position to zero so that the enumeration can be repeated.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="187" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000"><b>Next</b></font></td>
|
|
<td WIDTH="394" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Retrieves the
|
|
next object or objects in the enumeration starting from the current position.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="187" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000"><b>NextAsync</b></font></td>
|
|
<td WIDTH="394" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Retrieves the
|
|
next object or objects using asynchronous integration with <b>IWbemObjectSink</b><i>.</i></font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="187" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000"><b>Clone</b></font></td>
|
|
<td WIDTH="394" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Makes a logical
|
|
copy of the enumerator.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="187" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000"><b>Skip</b></font></td>
|
|
<td WIDTH="394" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Skips over the
|
|
object or objects, resulting in a new cursor position.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><font FACE="Arial" SIZE="1"> </p>
|
|
|
|
<hr>
|
|
</font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000">
|
|
|
|
<p></font><font FACE="Arial Narrow" SIZE="5"><b>IEnumWbemClassObject::Reset</b></font><font
|
|
SIZE="2" COLOR="#ff00ff"></p>
|
|
</font><font FACE="Arial" SIZE="2">
|
|
|
|
<p>The <b>IEnumWbemClassObject::Reset</b> method resets the current position of the
|
|
enumerator to the beginning of the enumeration. Since CIM objects can be dynamic, calling
|
|
this method does not necessarily return the same list of objects that you obtained
|
|
previously.</font><font FACE="Arial Narrow"><b></p>
|
|
<font FACE="Arial" SIZE="2">
|
|
|
|
<p></b>This method will fail if the enumerator was originally created with the
|
|
WBEM_FLAG_FORWARD_ONLY option.</font></p>
|
|
</font><b><font FACE="Lucida Sans Typewriter" size="2">
|
|
|
|
<p></font><font FACE="Lucida Sans Typewriter" size="3" color="#008000">HRESULT Reset();</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></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td WIDTH="238" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
|
|
<td WIDTH="221" VALIGN="TOP"><font FACE="Arial" SIZE="2">The operation succeeded.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="238" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_OPERATION </font></td>
|
|
<td WIDTH="221" VALIGN="TOP"><font FACE="Arial" SIZE="2">The operation failed.</font></td>
|
|
</tr>
|
|
</table>
|
|
<font FACE="Arial" SIZE="2" COLOR="#008000">
|
|
|
|
<p></font><font FACE="Arial" SIZE="2">DCOM-specific error codes may also be returned if
|
|
the remote connection to the CIM Object Manager (CIMOM) is lost due to network problems.</p>
|
|
|
|
<p>If an error code is returned, you can call the COM function <strong>GetErrorInfo</strong>
|
|
for more information about the error.</font><font FACE="Arial Narrow" SIZE="5"
|
|
COLOR="#800000"></p>
|
|
|
|
<hr>
|
|
|
|
<p></font><font FACE="Arial Narrow" SIZE="5"><b>IEnumWbemClassObject::Next</b></font><font
|
|
SIZE="2" COLOR="#ff00ff"></p>
|
|
</font><font FACE="Arial" SIZE="2">
|
|
|
|
<p>The <b>IEnumWbemClassObject::Next</b> method returns the next object or objects
|
|
starting at the current cursor position. It then advances the cursor position by <i>uCount</i>
|
|
objects, so that subsequent calls return the subsequent objects.</font><b><font
|
|
FACE="Lucida Sans Typewriter" SIZE="2"></p>
|
|
|
|
<p></font><font FACE="Lucida Sans Typewriter" size="3"><font color="#008000">HRESULT Next(<br>
|
|
[in] LONG <i>lTimeOut</i>,<br>
|
|
[in] ULONG <i>uCount</i>,<br>
|
|
[out] IWbemClassObject <i>**ppObjects</i>,<br>
|
|
[out] ULONG <i>*puReturned</i><br>
|
|
);</font></p>
|
|
</font><font FACE="Arial Narrow">
|
|
|
|
<p>Parameters</font></b><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>lTimeout<br>
|
|
</i>Specifies the maximum amount of time in milliseconds that the call will block before
|
|
returning. If you use the Constant WBEM_INFINITE (-1), the call blocks until objects are
|
|
available. If you use the value zero (WBEM_NO_WAIT), the call will return immediately,
|
|
whether any objects are available or not. Negative values other than -1 are invalid.</p>
|
|
<i>
|
|
|
|
<p>uCount<br>
|
|
</i>The number of requested objects.<i></p>
|
|
|
|
<p>ppObjects<br>
|
|
</i>A pointer to enough storage to hold the number of IWbemClassObject interface pointers
|
|
specified by uCount. This storage must be supplied by the caller. This parameter may not
|
|
be NULL.. The caller must call <b>Release</b> on each of the interface pointers that are
|
|
received when they are no longer needed.</p>
|
|
<i>
|
|
|
|
<p>puReturned<br>
|
|
</i>A pointer to a <b>ULONG</b> that receives the number of objects returned. This number
|
|
can be less than the number requested in uCount. This pointer cannot be NULL.</p>
|
|
</font><font FACE="Arial Narrow"><b>
|
|
|
|
<p>Notes</p>
|
|
<font FACE="Arial" SIZE="2">
|
|
|
|
<p></b>The IEnumWbemClassObject::Next method may return WBEM_S_FALSE even when objects
|
|
have been returned successfully. WBEM_S_NO_ERROR returns only when the number of objects
|
|
returned matches the number requested in <i>uCount</i>. Therefore, you should use loop
|
|
termination logic that examines the <i>puReturned</i> value to ensure you have reached the
|
|
end of the enumeration.</p>
|
|
</font><b>
|
|
|
|
<p>Return Values</b></font></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="599">
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_PARAMETER</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font FACE="Arial" SIZE="2">One or more invalid parameters
|
|
were specified in the call.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_OUT_OF_MEMORY</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font FACE="Arial" SIZE="2">There was not enough memory to
|
|
complete the enumeration.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_UNEXPECTED</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font FACE="Arial" SIZE="2">An object in the enumeration has
|
|
been deleted destroying the validity of the enumeration.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font FACE="Arial" SIZE="2">This indicates the failure of the
|
|
remote procedure call (RPC) link between the current process and CIMOM.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font FACE="Arial" SIZE="2">The number of objects returned
|
|
was the same as the number requested.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_FALSE</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font FACE="Arial" SIZE="2">The number of objects returned
|
|
was less than the number requested.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_TIMEDOUT</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font FACE="Arial" SIZE="2">A timeout occurred before you
|
|
obtained all the objects.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">WBEM_E_UNKNOWN_OBJECT_TYPE</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">Marshaling
|
|
received an invalid object type.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">WBEM_E_UNKNOWN_PACKET_TYPE</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">Marshaling
|
|
received an invalid packet type.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">WBEM_E_MARSHAL_VERSION_MISMATCH</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">Marshaling
|
|
version mismatch error.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="270" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">WBEM_E_MARSHAL_INVALID_SIGNATURE</font></td>
|
|
<td WIDTH="325" VALIGN="TOP"><font face="Arial" size="2" color="#FF0000">Packet received
|
|
by marshaling had an invalid (unrecognized) signature.</font></td>
|
|
</tr>
|
|
</table>
|
|
<b><font FACE="Arial Narrow">
|
|
|
|
<p>Note</p>
|
|
</font><font FACE="Arial Narrow" SIZE="2">
|
|
|
|
<p></font></b><font SIZE="2"><font face="Arial">You may see DCOM-specific error codes
|
|
returned if network problems cause you to lose the remote connection to CIMOM.</font><br>
|
|
<font FACE="Arial" SIZE="2">On error, you can call the COM function <b>GetErrorInfo</b> to
|
|
obtain more error information.</font></p>
|
|
</font><font face="Arial" size="2">
|
|
|
|
<p>In the following sample, since objects are only requested one at a time, checking the
|
|
return code to determine loop termination is correct.</font><font
|
|
FACE="Lucida Sans Typewriter" SIZE="1"></p>
|
|
|
|
<blockquote>
|
|
<p></font><font SIZE="2"><font face="Courier New">void ListObjects(<br>
|
|
IEnumWbemClassObject *pEnum,<br>
|
|
IWbemObjectSink *pSink<br>
|
|
)<br>
|
|
{<br>
|
|
HRESULT hRes;<br>
|
|
ULONG uReturned;</font></p>
|
|
<p><font face="Courier New"> while (1) <br>
|
|
{<br>
|
|
IWbemClassObject *pObj = 0;</font></p>
|
|
<p><font face="Courier New"> hRes =
|
|
pEnum->Next(0, 1, &pObj, &uReturned);</font></p>
|
|
<p><font face="Courier New"> if (hRes ==
|
|
WBEM_S_FALSE)<br>
|
|
break;</font></p>
|
|
<p><font face="Courier New"> ...use object<br>
|
|
<br>
|
|
pObj->Release();<br>
|
|
}<br>
|
|
}</font></p>
|
|
</font><font FACE="Lucida Sans Typewriter" SIZE="1">
|
|
</blockquote>
|
|
</font><font FACE="Arial" SIZE="2">
|
|
|
|
<p>In the next sample, <b>Next</b><i> </i>may return WBEM_S_FALSE, even though some
|
|
objects are returned. You need to check <i>uReturned</i>:</font><font
|
|
FACE="Lucida Sans Typewriter" SIZE="1"></p>
|
|
|
|
<p></font><font size="2"><font face="Courier New">void ListObjects2(IEnumWbemClassObject
|
|
*pEnum)<br>
|
|
{</font></p>
|
|
|
|
<p><font face="Courier New"> pEnum->Reset();<br>
|
|
IWbemClassObject *paObjects[10];<br>
|
|
ULONG uReturned;<br>
|
|
HRESULT hRes;</font></p>
|
|
|
|
<p><font face="Courier New"> while (1)<br>
|
|
{<br>
|
|
hRes = pEnum->Next(INFINITE, 10, paObjects,
|
|
&uReturned);</font></p>
|
|
|
|
<p><font face="Courier New"> if (uReturned == 0)<br>
|
|
break;</font></p>
|
|
|
|
<p><font face="Courier New"> for (ULONG u = 0; u
|
|
< uReturned; u++)<br>
|
|
{<br>
|
|
IWbemClassObject *pObj
|
|
= paObjects[u];</font></p>
|
|
|
|
<p><font face="Courier New"> </font></p>
|
|
|
|
<p><font face="Courier New">
|
|
// ... use the object</font></p>
|
|
|
|
<p><font face="Courier New">
|
|
pObj->Release();</font></p>
|
|
|
|
<p><font face="Courier New"> }<br>
|
|
}</font></p>
|
|
|
|
<p><font face="Courier New"> // Check hRes for other error codes</font></p>
|
|
|
|
<p><font face="Courier New">}</font></p>
|
|
|
|
<p><font face="Courier New"> </font></font><font COLOR="#800000"
|
|
size="6"></p>
|
|
|
|
<p></font> <font COLOR="#800000" size="6"></p>
|
|
|
|
<hr>
|
|
|
|
<p></font><font FACE="Arial Narrow" SIZE="5" COLOR="#800000">‹^</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">IEnumWbemClassObject::NextAsync</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>Use the <b>IEnumWbemClassObject::NextAsync</b> method when a controlled asynchronous
|
|
retrieval of objects to a sink is required. Normal asynchronous retrieval, such as a call
|
|
to <u><b>IWbemServices::ExecQueryAsync</b></u></font><font FACE="Arial" SIZE="2"
|
|
COLOR="#800000">_hmm_IWbemServices_ExecQueryAsync</font><font FACE="Arial" SIZE="2"><i>, </i>results
|
|
in uncontrolled delivery of objects to the caller’s implementation of <u><b>IWbemObjectSink</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemObjectSink</font><font FACE="Arial"
|
|
SIZE="2">.<i> </i>This method is helpful for cases where components want to control
|
|
delivery of objects.</font><font FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>HRESULT NextAsync(</p>
|
|
|
|
<p>[in] ULONG</b><i> uCount</i><b>,</b><i> </i><b></p>
|
|
|
|
<p>[in] IWbemObjectSink </b><i>*pSink </i><b></p>
|
|
|
|
<p>);</font><font FACE="Arial Narrow"></p>
|
|
|
|
<p>Parameters</font></b><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>uCount</p>
|
|
|
|
<blockquote>
|
|
</i><p>The number of objects being requested.</p>
|
|
</blockquote>
|
|
|
|
<p><i> </p>
|
|
|
|
<p>pSink</p>
|
|
|
|
<blockquote>
|
|
</i><p>The sink to receive the objects. The sink must be implemented by the caller. As
|
|
each batch of objects is requested, they will be delivered to the <i>pSink->Indicate </i>method
|
|
followed by a final call to <i>pSink->SetStatus.</i> If the sink is going to be used to
|
|
deliver objects, this API will return WBEM_S_NO_ERROR, even if the number of objects to be
|
|
delivered is less than requested. However, if there are no more objects remaining, then
|
|
the <i>pSink </i>parameter will be ingored (no calls to <i>pSink->SetStatus</i> will be
|
|
made). Instead, this API will return WBEM_S_FALSE.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
|
|
<p><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Return Values</b></font></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td WIDTH="45%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
|
|
<td WIDTH="55%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The call failed, and it is not
|
|
expected to complete.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="45%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_PARAMETER</font></td>
|
|
<td WIDTH="55%" VALIGN="TOP"><font FACE="Arial" SIZE="2">An invalid parameter was
|
|
specified.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="45%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_UNEXPECTED</font></td>
|
|
<td WIDTH="55%" VALIGN="TOP"><font FACE="Arial" SIZE="2">An object in the enumeration has
|
|
been deleted destroying the validity of the enumeration.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="45%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_OUT_OF_MEMORY</font></td>
|
|
<td WIDTH="55%" VALIGN="TOP"><font FACE="Arial" SIZE="2">There was not enough memory to
|
|
complete the operation.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="45%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
|
|
<td WIDTH="55%" VALIGN="TOP"><font FACE="Arial" SIZE="2">This indicates the failure of the
|
|
remote procedure call (RPC) link between the current process and CIMOM.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="45%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
|
|
<td WIDTH="55%" VALIGN="TOP"><font FACE="Arial" SIZE="2">One or more objects successfully
|
|
returned. It is not considered an error if less objects are returned than requested.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="45%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_FALSE</font></td>
|
|
<td WIDTH="55%" VALIGN="TOP"><font FACE="Arial" SIZE="2">This will be returned when no
|
|
more objects are available.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><font FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>A call to the COM function <b>GetErrorInfo</b> provides more information about the
|
|
error.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Note</p>
|
|
|
|
<blockquote>
|
|
</b></font><font FACE="Arial" SIZE="2"><p>DCOM-specific error codes may also be returned
|
|
if network problems cause you to lose the remote connection to CIMOM.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
|
|
<p><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
|
|
|
|
<p>This call returns immediately, and delivery to the sink occurs in the background. If
|
|
multiple calls are made to this method from one or more threads, they are logically
|
|
queued, and the order of calls and object delivery is preserved. Multiple calls made to
|
|
this method from one or more threads will block (will not return) until all the sink
|
|
objects related to previous calls to this method have been serviced. A call to <b>Reset</b>
|
|
does not affect delivery of objects currently in progress as a result of previous calls. <b>Reset</b>
|
|
only causes new calls to start at the beginning of the object sequence.</p>
|
|
|
|
<p>As the objects become available, the caller’s implementation of <u><b>IWbemObjectSink::Indicate</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IWbemObjectSink_Indicate</font><font
|
|
FACE="Arial" SIZE="2"> is called zero or more times to deliver the objects. This is
|
|
followed by a call to <u><b>IWbemObjectSink::SetStatus</b></u></font><font FACE="Arial"
|
|
SIZE="2" COLOR="#800000">_hmm_IWbemObjectSink_SetStatus</font><font FACE="Arial" SIZE="2">
|
|
with a value of WBEM_S_NO_ERROR if uCount items are returned. </p>
|
|
|
|
<p>If fewer objects are available than the number requested, <b>IWbemObjectSink::Indicate</b>
|
|
is called for those objects that are available. This is followed by a call to <b>IWbemObjectSink::SetStatus</b>
|
|
with a value of WBEM_S_FALSE, or the error code if an error occurred. If there are no
|
|
available objects, <b>Indicate</b> is not called. However, a final call to <b>IWbemObjectSink::SetStatus</b>
|
|
will always occur to indicate the status of the entire operation.</font><font
|
|
FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Sample Code</b></font><font FACE="Lucida Sans Typewriter" SIZE="1"></p>
|
|
|
|
<p>void ListObjects(</p>
|
|
|
|
<p>IEnumWbemClassObject *pEnum,</p>
|
|
|
|
<p>IWbemObjectSink *pSink</p>
|
|
|
|
<p>)</p>
|
|
|
|
<p>{</p>
|
|
|
|
<p>HRESULT hRes;</p>
|
|
|
|
<p>while (1)</p>
|
|
|
|
<p>{</p>
|
|
|
|
<p>hRes = pEnum->NextAsync(5, pSink);</p>
|
|
|
|
<p>// Wait until sink is ready for more by</p>
|
|
|
|
<p>// some private mechanism. Note that hRes gives</p>
|
|
|
|
<p>// no indication as to whether to continue the</p>
|
|
|
|
<p>// enumeration or not.</p>
|
|
|
|
<p>BOOL bContinue = WaitUntilMoreObjectsNeeded();</p>
|
|
|
|
<p>if (!bContinue)</p>
|
|
|
|
<p>break;</p>
|
|
|
|
<p>}</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">IEnumWbemClassObject::Clone</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>IEnumWbemClassObject::Clone</b> method makes a logical copy of the entire
|
|
enumerator, retaining its current cursor position. This method will make only a "best
|
|
effort" copy. Due to the dynamic nature of many CIM objects, it is possible that the
|
|
new enumerator does not enumerate the same set of objects as the source enumerator.</font><font
|
|
FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Note</p>
|
|
|
|
<blockquote>
|
|
</b></font><font FACE="Arial" SIZE="2"><p>When the enumeration was initialized with the
|
|
WBEM_FLAG_FORWARD_ONLY flag, IEnumWbemClassObject::Clone is not supported. </font></p>
|
|
</blockquote>
|
|
|
|
<p><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Note</p>
|
|
|
|
<blockquote>
|
|
</b></font><font FACE="Arial" SIZE="2"><p>Any pending asynchronous deliveries begun by <u><b>NextAsync</b></u></font><font
|
|
FACE="Arial" SIZE="2" COLOR="#800000">_hmm_IEnumWbemClassObject_NextAsync</font><font
|
|
FACE="Arial" SIZE="2"> are not cloned.</font></p>
|
|
</blockquote>
|
|
|
|
<p><font FACE="Lucida Sans Typewriter" SIZE="2"><b> </p>
|
|
|
|
<p>HRESULT Clone(</p>
|
|
|
|
<p>[out] IEnumWbemClassObject </b><i>**ppEnum</i> </p>
|
|
|
|
<p><b> </p>
|
|
|
|
<p>);</font><font FACE="Arial Narrow"></p>
|
|
|
|
<p>Parameters</font></b><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>ppEnum</p>
|
|
|
|
<blockquote>
|
|
</i><p>Receives a pointer to a new <b>IEnumWbemClassObject</b> object. The caller must
|
|
call <b>Release</b> when the interface pointer is no longer required. On error, there will
|
|
not be a return of a new object.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</blockquote>
|
|
|
|
<p><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Return Values</b></font></p>
|
|
|
|
<table CELLSPACING="0" BORDER="0" WIDTH="463">
|
|
<tr>
|
|
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
|
|
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">An unspecified error occurred.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_PARAMTER</font></td>
|
|
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The caller passed an invalid
|
|
parameter.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_OUT_OF_MEMORY</font></td>
|
|
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">There was not enough memory to
|
|
complete the operation.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
|
|
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">This indicates the failure of the
|
|
remote procedure call (RPC) link between the current process and CIMOM.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
|
|
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The call succeeds and the cursor
|
|
position was updated.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><font FACE="Arial" SIZE="2"> </p>
|
|
|
|
<p>On error, you can call the COM function <b>GetErrorInfo</b> to obtain more error
|
|
information.</font><font FACE="Arial Narrow"><b></p>
|
|
|
|
<p>Note</p>
|
|
|
|
<blockquote>
|
|
</b></font><font FACE="Arial" SIZE="2"><p>DCOM-specific error codes may also be returned
|
|
if network problems cause you to lose the remote connection to CIMOM.</font></p>
|
|
</blockquote>
|
|
|
|
<p><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Sample Code</b></font><font FACE="Lucida Sans Typewriter" SIZE="1"></p>
|
|
|
|
<p>BOOL CloneEnum(IEnumWbemClassObject *pSrc)</p>
|
|
|
|
<p>{</p>
|
|
|
|
<p>IEnumWbemClassObject *pCopy = 0;</p>
|
|
|
|
<p>HRESULT hRes = pSrc->Clone(&pCopy);</p>
|
|
|
|
<p>if (hRes != WBEM_S_NO_ERROR) // Failed to clone it</p>
|
|
|
|
<p>return FALSE;</p>
|
|
|
|
<p>// Use the copy of the enumerator</p>
|
|
|
|
<p>// ...</p>
|
|
|
|
<p>pCopy->Release();</p>
|
|
|
|
<p>return TRUE;</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">IEnumWbemClassObject::Skip</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>You can use the <b>IEnumWbemClassObject::Skip</b> method to move the current cursor
|
|
position ahead by a specified number of objects. Also, this affects subsequent calls to <b>NextAsync</b><i>,
|
|
</i>but it does not affect pending deliveries begun with <b>NextAsync</b><i>.</i></font><font
|
|
FACE="Lucida Sans Typewriter" SIZE="2"><b></p>
|
|
|
|
<p>HRESULT Skip(</p>
|
|
|
|
<p>[in] LONG </b><i>lTimeOut</i><b>,</p>
|
|
|
|
<p>[in] ULONG </b><i>nCount</i><b></p>
|
|
|
|
<p>);</font><font FACE="Arial Narrow"></p>
|
|
|
|
<p>Parameters</font></b><font FACE="Arial" SIZE="2"><i></p>
|
|
|
|
<p>lTimeout</p>
|
|
|
|
<blockquote>
|
|
</i><p>Specifies the maximum amount of time in milliseconds that the call to <i>Skip </i>will
|
|
block before returning. If you use the constant WBEM_INFINITE (-1), the call will block
|
|
until the operation succeeds. Negative values other than -1 are invalid. If Skip cannot
|
|
complete the operation before the lTimeout value expires, the call returns
|
|
WBEM_S_TIMEDOUT. </p>
|
|
</blockquote>
|
|
|
|
<p><i> </p>
|
|
|
|
<p>UCount</p>
|
|
|
|
<blockquote>
|
|
</i><p>Specifies the number of objects to skip. If this parameter is greater than the
|
|
number of objects left to enumerate then this call will skip to the end of the enumeration
|
|
and WBEM_S_FALSE will be returned.</p>
|
|
</font><font FACE="Arial" SIZE="1"><p></font> </p>
|
|
</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_INVALID_PARAMTER</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The caller passes an invalid
|
|
parameter.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_OUT_OF_MEMORY</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">There was not enough memory to
|
|
complete the operation.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_FALSE</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The call skips less objects than
|
|
specified by the uCount parameter.</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 call succeeds and the cursor
|
|
position was updated.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_TIMEDOUT</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The lTimeout parameter specified
|
|
expired before Skip could complete the operation.</font></td>
|
|
</tr>
|
|
<tr>
|
|
<td WIDTH="49%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
|
|
<td WIDTH="51%" VALIGN="TOP"><font FACE="Arial" SIZE="2">This indicates the failure of the
|
|
remote procedure call (RPC) link between the current process and CIMOM.</font></td>
|
|
</tr>
|
|
<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">An unspecified error occurred.</font></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><font FACE="Arial" SIZE="1"> </p>
|
|
|
|
<p></font><font FACE="Arial Narrow"><b> </p>
|
|
|
|
<p>Note</p>
|
|
|
|
<blockquote>
|
|
</b></font><font FACE="Arial" SIZE="2"><p>DCOM-specific error codes may also be returned
|
|
if network problems cause you to lose the remote connection to CIMOM.</font></p>
|
|
</blockquote>
|
|
</body>
|
|
</html>
|