WindowsXP/admin/wmi/wbem/winmgmt/specs/html/interface_iwbemcallresult.htm
2025-04-27 07:49:33 -04:00

436 lines
21 KiB
HTML

<html>
<head>
<title>Interface IWbemCallResult</title>
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
</head>
<body bgcolor="#FFFFC1">
<font FACE="Arial Narrow" SIZE="6" COLOR="#800000">
<p></font><font FACE="Arial Narrow" SIZE="6"><b>Interface IWbemCallResult</b></font><font
SIZE="2" COLOR="#ff00ff"></p>
</font><font FACE="Arial" SIZE="2">
<p>You can use the <b>IWbemCallResult</b> interface for making a semisynchronous call of
the <b>IWbemServices</b><i> </i>interface. When you make such calls, the <b>IWbemServices</b><i>
</i>method returns immediately, along with an <b>IWbemCallResult</b> object. Periodically,
you can poll the returned <b>IWbemCallResult</b> object to determine the status of the
call. You can obtain the result of the original <b>IWbemServices</b> call after it is
complete by calling <b>IWbemCallResult::GetCallStatus</b>.&nbsp; </p>
<p>This call-return paradigm is useful in cases where a thread cannot afford to be blocked
for more than a few seconds because it is servicing other tasks, such as processing window
messages.</p>
<p>Not all <b>IWbemServices</b><i> </i>methods support this interface because it is not
required for all of them. The intent is to allow nonblocking synchronous operation
(semisynchronous operation) for all relevant operations. Since many of the <b>IWbemServices</b><i>
</i>methods are already nonblocking due to the use of enumerators or other constructs,
only <b>OpenNamespace</b>, <b>GetObject</b>, <b>PutInstance</b>, <b>PutClass</b>, <b>DeleteClass</b>,
<b>DeleteInstance</b>, and <b>ExecMethod</b><i> </i>need this helper interface to support
semisynchronous operation.</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="597">
<tr>
<td VALIGN="TOP" COLSPAN="2" width="549"></td>
</tr>
<tr>
<td WIDTH="232" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>IWbemCallResult Methods</b></font></td>
<td WIDTH="361" VALIGN="TOP"><font FACE="Arial" SIZE="2"><b>Description</b></font></td>
</tr>
<tr>
<td WIDTH="232" VALIGN="TOP"><a href="#GetResultObject"><font FACE="Arial" SIZE="2"
color="#008000"><b>GetResultObject</b></font></a></td>
<td WIDTH="361" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Returns an <b>IWbemClassObject</b>;
which is the result of a semisynchronous call to <b>IWbemServices::GetObject</b>.</font></td>
</tr>
<tr>
<td WIDTH="232" VALIGN="TOP"><a href="#GetResultString"><font FACE="Arial" SIZE="2"
color="#008000"><u><b>GetResultString</b></u></font></a></td>
<td WIDTH="361" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Returns an <b>Object
Path</b>; which is the result of a semisynchronous call to <b>IWbemServices::PutInstance</b>.</font></td>
</tr>
<tr>
<td WIDTH="232" VALIGN="TOP"><a href="#GetResultServices"><font FACE="Arial" SIZE="2"
color="#008000"><u><b>GetResultServices</b></u></font></a></td>
<td WIDTH="361" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Returns the
result of a semisynchronous call to <b>IWbemServices::OpenNamespace</b> verb action.</font></td>
</tr>
<tr>
<td WIDTH="232" VALIGN="TOP"><a href="#GetCallStatus"><font FACE="Arial" SIZE="2"
color="#008000"><u><b>GetCallStatus</b></u></font></a></td>
<td WIDTH="361" VALIGN="TOP"><font FACE="Arial" SIZE="2" color="#008000">Reports whether a
semisynchronous call was successful.</font></td>
</tr>
</table>
<p>&nbsp;</p>
<hr>
<font FACE="Arial Narrow" SIZE="5" COLOR="#800000">
<p></font><a name="GetResultObject"></a><font FACE="Arial Narrow" SIZE="5"><b>IWbemCallResult::GetResultObject</b></font><font
SIZE="2" COLOR="#ff00ff"></p>
</font>
<p><font FACE="Arial" SIZE="2">The <b>IWbemCallResult::GetResultObject</b> method returns
the object. This results from a semisynchronous invocation of <b>IWbemServices::GetObject </b>or
<b>IWbemServices::ExecMethod</b>. If the object is not yet available, the call returns
WBEM_S_TIMEDOUT. Also, before invoking this method to get the resultant object, you may
call <b>IWbemCallResult::GetCallStatus</b> until it returns WBEM_S_NO_ERROR.</font></p>
<b><font FACE="Lucida Sans Typewriter" SIZE="2">
<p><font color="#008000">HRESULT GetResultObject(<br>
&nbsp;&nbsp;&nbsp; [in] LONG <i>lTimeout</i>,<br>
&nbsp;&nbsp;&nbsp; [out] IWbemClassObject <i>**ppResultObject</i><br>
&nbsp;&nbsp; <i> </i>);</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 time in milliseconds that this call will block before returning.
If you use the constant WBEM_INFINITE (-1), the call will block until the object
is available. If you use zero, the call immediately returns either the object or a status
code. Negative values other than -1 are invalid.</p>
<p><i>ppResultObject<br>
</i>This parameter cannot be NULL. It receives the copy of the object when it becomes
available. You must call <strong>Release( ) </strong>on the returned object when the
object is no longer required.</p>
<p>A new object is not returned on error.</p>
</font>
<p><font FACE="Arial Narrow"><b>&nbsp;</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_S_NO_ERROR</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The object successfully returned
.</font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_TIMEDOUT</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The object was not yet available
after the <i>lTimeout </i>value expired.</font></td>
</tr>
<tr>
<td WIDTH="53%" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_UNEXPECTED</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">The call failed, and it is not
expected to complete.</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_E_INVALID_PARAMETER</font></td>
<td WIDTH="47%" VALIGN="TOP"><font FACE="Arial" SIZE="2">An invalid parameter was
specified.</font></td>
</tr>
</table>
<font FACE="Arial" SIZE="2">
<p><strong>Notes</strong></p>
<p>If the original semi-synchronous operation failed such as when the object was not
found, or the method could not be invoked, this method will return the error code that the
original API would have returned in its synchronous version. </p>
<p>On error, you can call the COM function <b>GetErrorInfo</b> to obtain more error
information.&nbsp; DCOM-specific error codes may also be returned if network problems
cause you to lose the remote connection to CIMOM.</font><b><font FACE="Arial Narrow"></p>
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
<p></u></font><font color="#008000" FACE="Arial" SIZE="2">IWbemServices::GetObject</font><font
color="#008000"><br>
<font FACE="Arial" SIZE="2">IWbemServices::ExecMethod</font></font></b><font
FACE="Arial Narrow" SIZE="5"></p>
</font>
<hr>
<p><a name="GetResultString"></a><font FACE="Arial Narrow" SIZE="5" color="#000000"><b>IWbemCallResult::GetResultString</b></font></p>
<font face="Arial" size="2">
<p>The <b>IWbemCallResult::GetResultString</b> method returns the assigned object path of
an instance newly created by <b>IWbemServices::PutInstance.</font><font
FACE="Arial Narrow"></p>
<font FACE="Arial" SIZE="2">
<p></b>The call result object is primarily used when the <i>PutInstance </i>call is
carried out by a provider and the client needs to know the object path (the values of the
key properties) assigned the provider. For example, if the <i>key </i>property to the
class is a globally unique identifier (GUID), and it is assigned by the provider during
the <i>PutInstance </i>operation, the client would have no way of knowing this GUID unless
the provider was able to return it in this way.</font><b></p>
</font><font FACE="Lucida Sans Typewriter" SIZE="2">
<p></font><font FACE="Lucida Sans Typewriter" SIZE="2" color="#008000">HRESULT
GetResultString(<br>
&nbsp;&nbsp;&nbsp; [in] LONG <i>lTimeout</i>,</font><br>
<font FACE="Lucida Sans Typewriter" SIZE="2" color="#008000">&nbsp;&nbsp;&nbsp; [out] BSTR
<i>*pstrResultString</i></font><br>
<font FACE="Lucida Sans Typewriter" SIZE="2" color="#008000">&nbsp;&nbsp; <i> </i>);</font><font
FACE="Lucida Sans Typewriter" SIZE="2"></p>
</font><font FACE="Arial Narrow">
<p>Parameters</font></b><font FACE="Arial" SIZE="2"><i></p>
<p>lTimeout<br>
</i>Specifies the maximum time in milliseconds that this call will block before returning.
If you use the constant WBEM_INFINITE (-1), the call will block until the object
path is available. If you use zero, the call immediately returns either the object path or
a status code. Negative values other than -1 are invalid.</p>
<i>
<p>pstrResultString<br>
</i>Cannot be NULL. This parameter receives a pointer to the object path, which, in turn,
leads to the newly created object. The returned string must be deallocated using the
system call <b>SysFreeString</b>. On error, a new string is not returned.</p>
</font><font FACE="Arial Narrow"><b>
<p>Return Values</b></font></p>
<table CELLSPACING="0" BORDER="0" WIDTH="622">
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
<td WIDTH="374" VALIGN="TOP"><font FACE="Arial" SIZE="2">The object path was retrieved.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_TIMEDOUT</font></td>
<td WIDTH="374" VALIGN="TOP"><font FACE="Arial" SIZE="2">The object was not yet available
after the <i>lTimeout </i>value expired.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_UNEXPECTED</font></td>
<td WIDTH="374" VALIGN="TOP"><font FACE="Arial" SIZE="2">An internal failure occurred.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
<td WIDTH="374" 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="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_ACCESS_DENIED</font></td>
<td WIDTH="374" VALIGN="TOP"><font FACE="Arial" SIZE="2">The caller attempted an
unauthorized operation.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_PARAMETER</font></td>
<td WIDTH="374" VALIGN="TOP"><font FACE="Arial" SIZE="2">An invalid parameter was
specified.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_OUT_OF_MEMORY</font></td>
<td WIDTH="374" VALIGN="TOP"><font FACE="Arial" SIZE="2">There was not enough memory to
complete the operation.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
<td WIDTH="374" VALIGN="TOP"><font FACE="Arial" SIZE="2">An unspecified error occurred.</font></td>
</tr>
</table>
<font FACE="Arial" SIZE="2">
<p>On error, you can call the COM function <b>GetErrorInfo </b>to obtain more error
information. DCOM-specific error codes may also be returned if network problems cause you
to lose the remote connection to CIMOM.</font><b><font FACE="Arial Narrow"></p>
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
<p></u>IWbemServices::PutInstance</font></b><font FACE="Arial Narrow" SIZE="5"
COLOR="#800000"></p>
<hr>
<p></font><a name="GetResultServices"></a><font FACE="Arial Narrow" SIZE="5"><b>IWbemCallResult::GetResultServices</b></font><font
SIZE="2" COLOR="#ff00ff"></p>
</font><font FACE="Arial" SIZE="2">
<p>You can use the <b>IWbemCallResult::GetResultServices</b> method to retrieve the <b>IWbemServices</b><i>
</i>pointer, which resulted from a semisynchronous call to <b>IWbemServices::OpenNamespace</b>
when it becomes available.</font><b><font FACE="Lucida Sans Typewriter" SIZE="2"></p>
<p><font color="#008000">HRESULT GetResultServices(<br>
&nbsp;&nbsp;&nbsp; [in] LONG <i>lTimeout</i>,<br>
&nbsp;&nbsp;&nbsp; [out] IWbemServices<i> **ppServices</i><br>
&nbsp;&nbsp; <i> </i>);</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 time in milliseconds that this call will block before it
returns. If you use the constant WBEM_INFINITE (-1), the call will block until the
interface pointer is available. If you use zero, the call immediately returns either the
pointer or a status code. Negative values other than -1 are invalid. </p>
<i>
<p>ppServices<br>
</i>This parameter cannot be NULL. It receives a pointer to the <b>IWbemServices</b>
interface requested by the original call to <b>OpenNamespace</b> when it becomes available
The caller must call <b>Release</b> on the returned object when it is no longer required.</p>
<p>On error, a new object is not returned.</p>
</font><font FACE="Arial Narrow"><b>
<p>Return Values</b></font></p>
<table CELLSPACING="0" BORDER="0" WIDTH="576">
<tr>
<td WIDTH="246" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
<td WIDTH="326" VALIGN="TOP"><font FACE="Arial" SIZE="2">The call succeeded and returned
an <b>IWbemServices</b><i> </i>pointer.</font></td>
</tr>
<tr>
<td WIDTH="246" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">WBEM_S_TIMEDOUT</font></td>
<td WIDTH="326" VALIGN="TOP"><font FACE="Arial" SIZE="2">The time-out occurred, and the
call has not yet completed.</font></td>
</tr>
<tr>
<td WIDTH="246" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">WBEM_E_UNEXPECTED</font></td>
<td WIDTH="326" VALIGN="TOP"><font FACE="Arial" SIZE="2">An internal failure occurred.</font></td>
</tr>
<tr>
<td WIDTH="246" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
<td WIDTH="326" 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="246" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">WBEM_E_ACCESS_DENIED</font></td>
<td WIDTH="326" VALIGN="TOP"><font FACE="Arial" SIZE="2">The user attempted to perform an
unauthorized operation.</font></td>
</tr>
<tr>
<td WIDTH="243" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_NAMESPACE</font></td>
<td WIDTH="329" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">The specified
namespace did not exist on the server.</font></td>
</tr>
<tr>
<td WIDTH="246" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
<td WIDTH="326" VALIGN="TOP"><font FACE="Arial" SIZE="2">There has been a general failure.</font></td>
</tr>
<tr>
<td WIDTH="246" VALIGN="TOP" COLSPAN="2"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_PARAMETER</font></td>
<td WIDTH="326" VALIGN="TOP"><font FACE="Arial" SIZE="2">An invalid parameter was
specified.</font></td>
</tr>
</table>
<p><font FACE="Arial" SIZE="2">&nbsp;</p>
<p>On error, the COM function <b>GetErrorInfo</b> can be called to obtain more error
information.&nbsp; DCOM-specific error codes may also be returned if network problems
cause you to lose the remote connection to CIMOM.</font><b><font FACE="Arial Narrow"></p>
<p>See Also</font><font FACE="Arial" SIZE="2"><u></p>
<p></u>IWbemServices::OpenNamespace</font></b><font FACE="Arial Narrow" SIZE="5"
COLOR="#800000"></p>
<hr>
<p></font><a name="GetCallStatus"></a><font FACE="Arial Narrow" SIZE="5"><b>IWbemCallResult::GetCallStatus</b></font><font
SIZE="2" COLOR="#ff00ff"></p>
</font><font FACE="Arial" SIZE="2">
<p>The <b>IWbemCallResult::GetCallStatus</b> method returns to the user the status of the
current outstanding semisynchronous call. When this call returns WBEM_S_NO_ERROR, the
original call to the <b>IWbemServices</b><i> </i>method is complete.</font><b><font
FACE="Lucida Sans Typewriter" SIZE="2"></p>
<p></font><font FACE="Lucida Sans Typewriter" SIZE="2" color="#008000">HRESULT
GetCallStatus(<br>
&nbsp;&nbsp;&nbsp; [in] LONG <i>lTimeout</i>,</font><br>
<font FACE="Lucida Sans Typewriter" SIZE="2" color="#008000">&nbsp;&nbsp;&nbsp; [out] LONG
<i>*plStatus</i></font><br>
<font FACE="Lucida Sans Typewriter" SIZE="2" color="#008000">&nbsp;&nbsp; <i> </i>);</font><font
FACE="Lucida Sans Typewriter" SIZE="2"></p>
</font><font FACE="Arial Narrow">
<p>Parameters</font></b><font FACE="Arial" SIZE="2"><i></p>
<p>lTimeout<br>
</i>Specifies the maximum time in milliseconds that this call will block before it
returns. If you use the constant WBEM_INFINITE (-1), the call will block until the
original semisynchronous call to an <b>IWbemServices</b> method is complete. If you use
zero, the call immediately returns the call status. Negative values other than
-1 are invalid. </p>
<i>
<p>plStatus<br>
</i>If WBEM_S_NO_ERROR returns in the HRESULT to this method, this parameter will receive
the final result status of a call to one of the <b>IWbemServices</b> methods: <b>OpenNamespace</b>,
<b>PutInstance</b>, <b>PutClass</b>, <b>GetObject</b>, <b>DeleteInstance</b>, <b>DeleteClass</b>,
or <b>ExecMethod</b>. On error, the value pointed to by plStatus will not be used.</p>
</font><font FACE="Arial Narrow"><b>
<p>Return Values</b></font></p>
<table CELLSPACING="0" BORDER="0" WIDTH="720">
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_NO_ERROR</font></td>
<td WIDTH="472" VALIGN="TOP"><font FACE="Arial" SIZE="2">The call is complete, and <i>plStatus
</i>has been assigned.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_S_TIMEDOUT</font></td>
<td WIDTH="472" VALIGN="TOP"><font FACE="Arial" SIZE="2">The object was not yet available
after the <i>lTimeout </i>value expired.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_TRANSPORT_FAILURE</font></td>
<td WIDTH="472" 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="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_INVALID_PARAMETER</font></td>
<td WIDTH="472" VALIGN="TOP"><font FACE="Arial" SIZE="2">An invalid parameter was
specified.</font></td>
</tr>
<tr>
<td WIDTH="244" VALIGN="TOP"><font FACE="Arial" SIZE="2">WBEM_E_FAILED</font></td>
<td WIDTH="472" VALIGN="TOP"><font FACE="Arial" SIZE="2">An unexpected system error has
occurred.</font></td>
</tr>
</table>
<font FACE="Arial" SIZE="2">
<p>On error, you can call the COM function <b>GetErrorInfo</b><i> </i>to obtain more error
information.&nbsp; DCOM-specific error codes may also be returned if network problems
cause you to lose the remote connection to CIMOM.</font><font FACE="Arial Narrow"><b></p>
<p>Remarks</b></font><font FACE="Arial" SIZE="2"></p>
<p>After invoking an <b>IWbemServices</b> method semisynchronously, you can call <b>GetCallStatus
</b>at any time to determine whether the call is complete. After <b>GetCallStatus</b><i> </i>has
returned WBEM_S_NO_ERROR, which indicates completion of the original <i>IWbemServices </i>operation,
calls to other <b>IWbemCallResult</b><i> </i>methods may be required to retrieve the
result of the call, according to the following rules:</p>
<blockquote>
<p>1. For the <b>IWbemServices</b><i> </i>method <b>OpenNamespace</b><i>, </i>the <b>GetResultServices</b><i>
</i>method must be called to retrieve the new <b>IWbemServices</b><i> </i>pointer.</p>
<p>2. For the <b>IWbemServices</b><i> </i>method <b>PutInstance</b><i>, </i>the <b>GetResultString</b><i>
</i>method must be called to obtain the object path that was assigned to the object.</p>
<p>3. For the <b>IWbemServices</b> method <b>GetObject</b><i>, </i>the <b>GetResultObject</b><i>
</i>method must be called to retrieve the object.</p>
<p>4. For the <b>IWbemServices</b> methods <b>DeleteInstance</b>, <b>DeleteClass</b>, and <b>ExecMethod</b>,
the <b>GetCallStatus</b><i> </i>method is the only call that returns information regarding
these operations.</p>
</blockquote>
</font>
</body>
</html>