You can use the IWbemCallResult interface for making a semisynchronous call of the IWbemServices interface. When you make such calls, the IWbemServices method returns immediately, along with an IWbemCallResult object. Periodically, you can poll the returned IWbemCallResult object to determine the status of the call. You can obtain the result of the original IWbemServices call after it is complete by calling IWbemCallResult::GetCallStatus.
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.
Not all IWbemServices 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 IWbemServices methods are already nonblocking due to the use of enumerators or other constructs, only OpenNamespace, GetObject, PutInstance, PutClass, DeleteClass, DeleteInstance, and ExecMethod need this helper interface to support semisynchronous operation.
This interface is derived from IUnknown and supports its methods.
| IWbemCallResult Methods | Description |
| GetResultObject | Returns an IWbemClassObject; which is the result of a semisynchronous call to IWbemServices::GetObject. |
| GetResultString | Returns an Object Path; which is the result of a semisynchronous call to IWbemServices::PutInstance. |
| GetResultServices | Returns the result of a semisynchronous call to IWbemServices::OpenNamespace verb action. |
| GetCallStatus | Reports whether a semisynchronous call was successful. |
The IWbemCallResult::GetResultObject method returns the object. This results from a semisynchronous invocation of IWbemServices::GetObject or IWbemServices::ExecMethod. 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 IWbemCallResult::GetCallStatus until it returns WBEM_S_NO_ERROR.
HRESULT GetResultObject(
[in] LONG lTimeout,
[out] IWbemClassObject **ppResultObject
);
Parameters
lTimeout
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.
ppResultObject
This parameter cannot be NULL. It receives the copy of the object when it becomes
available. You must call Release( ) on the returned object when the
object is no longer required.
A new object is not returned on error.
Return Values
| WBEM_S_NO_ERROR | The object successfully returned . |
| WBEM_S_TIMEDOUT | The object was not yet available after the lTimeout value expired. |
| WBEM_E_UNEXPECTED | The call failed, and it is not expected to complete. |
| WBEM_E_TRANSPORT_FAILURE | This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM. |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
Notes
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.
On error, you can call the COM function GetErrorInfo 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.
See Also
IWbemServices::GetObjectIWbemCallResult::GetResultString
The IWbemCallResult::GetResultString method returns the assigned object path of an instance newly created by IWbemServices::PutInstance.
The call result object is primarily used when the PutInstance 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 key property to the class is a globally unique identifier (GUID), and it is assigned by the provider during the PutInstance operation, the client would have no way of knowing this GUID unless the provider was able to return it in this way.
HRESULT GetResultString(Parameters
lTimeout
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.
pstrResultString
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 SysFreeString. On error, a new string is not returned.
Return Values
| WBEM_S_NO_ERROR | The object path was retrieved. |
| WBEM_S_TIMEDOUT | The object was not yet available after the lTimeout value expired. |
| WBEM_E_UNEXPECTED | An internal failure occurred. |
| WBEM_E_TRANSPORT_FAILURE | This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM. |
| WBEM_E_ACCESS_DENIED | The caller attempted an unauthorized operation. |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_OUT_OF_MEMORY | There was not enough memory to complete the operation. |
| WBEM_E_FAILED | An unspecified error occurred. |
On error, you can call the COM function GetErrorInfo 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.
See Also
IWbemServices::PutInstance
You can use the IWbemCallResult::GetResultServices method to retrieve the IWbemServices pointer, which resulted from a semisynchronous call to IWbemServices::OpenNamespace when it becomes available.
HRESULT GetResultServices(
[in] LONG lTimeout,
[out] IWbemServices **ppServices
);
Parameters
lTimeout
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.
ppServices
This parameter cannot be NULL. It receives a pointer to the IWbemServices
interface requested by the original call to OpenNamespace when it becomes available
The caller must call Release on the returned object when it is no longer required.
On error, a new object is not returned.
Return Values
| WBEM_S_NO_ERROR | The call succeeded and returned an IWbemServices pointer. | |
| WBEM_S_TIMEDOUT | The time-out occurred, and the call has not yet completed. | |
| WBEM_E_UNEXPECTED | An internal failure occurred. | |
| WBEM_E_TRANSPORT_FAILURE | This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM. | |
| WBEM_E_ACCESS_DENIED | The user attempted to perform an unauthorized operation. | |
| WBEM_E_INVALID_NAMESPACE | The specified namespace did not exist on the server. | |
| WBEM_E_FAILED | There has been a general failure. | |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. | |
On error, the COM function GetErrorInfo can be called 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.
See Also
IWbemServices::OpenNamespace
IWbemCallResult::GetCallStatus
The IWbemCallResult::GetCallStatus 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 IWbemServices method is complete.
HRESULT GetCallStatus(Parameters
lTimeout
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 IWbemServices method is complete. If you use
zero, the call immediately returns the call status. Negative values other than
-1 are invalid.
plStatus
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 IWbemServices methods: OpenNamespace,
PutInstance, PutClass, GetObject, DeleteInstance, DeleteClass,
or ExecMethod. On error, the value pointed to by plStatus will not be used.
Return Values
| WBEM_S_NO_ERROR | The call is complete, and plStatus has been assigned. |
| WBEM_S_TIMEDOUT | The object was not yet available after the lTimeout value expired. |
| WBEM_E_TRANSPORT_FAILURE | This indicates the failure of the remote procedure call (RPC) link between the current process and CIMOM. |
| WBEM_E_INVALID_PARAMETER | An invalid parameter was specified. |
| WBEM_E_FAILED | An unexpected system error has occurred. |
On error, you can call the COM function GetErrorInfo 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.
Remarks
After invoking an IWbemServices method semisynchronously, you can call GetCallStatus at any time to determine whether the call is complete. After GetCallStatus has returned WBEM_S_NO_ERROR, which indicates completion of the original IWbemServices operation, calls to other IWbemCallResult methods may be required to retrieve the result of the call, according to the following rules:
1. For the IWbemServices method OpenNamespace, the GetResultServices method must be called to retrieve the new IWbemServices pointer.
2. For the IWbemServices method PutInstance, the GetResultString method must be called to obtain the object path that was assigned to the object.
3. For the IWbemServices method GetObject, the GetResultObject method must be called to retrieve the object.
4. For the IWbemServices methods DeleteInstance, DeleteClass, and ExecMethod, the GetCallStatus method is the only call that returns information regarding these operations.