[This is preliminary documentation and subject to change.]
Asynchronous methods increase the performance of a management application by allowing it to proceed with other tasks while requests are pending, and while results are delivered through another thread. The IWbemServices interface supports both the synchronous and asynchronous versions of several methods. Whereas applications can make calls to either version, providers implement only the asynchronous versions.
The asynchronous version of a method has the Async suffix attached to its name as is shown in the following table:
| Synchronous method | Asynchronous method |
|---|---|
| CreateClassEnum | CreateClassEnumAsync |
| CreateInstanceEnum | CreateInstanceEnumAsync |
| DeleteClass | DeleteClassAsync |
| DeleteInstance | DeleteInstanceAsync |
| ExecMethod | ExecMethodAsync |
| ExecNotificationQuery | ExecNotificationQueryAsync |
| ExecQuery | ExecQueryAsync |
| GetObject | GetObjectAsync |
| PutClass | PutClassAsync |
| PutInstance | PutInstanceAsync |
The asynchronous methods return immediately whether or not they have finished performing the requested operation. The results of an asynchronous call are provided through the IWbemObjectSink interface. Each asynchronous method has as an input parameter a pointer to an IWbemObjectSink implementation.
If the asynchronous method completes successfully, it:
As the operation is progressing, calls are made to IWbemObjectSink::Indicate. Indicate has two parameters: an array of pointers to objects accessible through the IWbemClassObject interface and a count of the number of pointers in the array. The object pointer array contains data that is relevant to the particular operation. For example, a query operation invoked through the IWbemServices::ExecQueryAsync method returns one or more data objects from the query's result set in the array.
Status is reported through the IWbemObjectSink::SetStatus method. An asynchronous operation can report an intermediate status, a final status, or an error. After the final status has been reported, a call is made to IWbemObjectSink::Release to release the IWbemObjectSink pointer.
An application calls IWbemServices::CancelAsyncCall if it wants to shut down before it has received all of the results from its asynchronous call. CancelAsyncCall cancels asynchronous processing by immediately releasing the IWbemObjectSink pointer included in the pSink parameter. Note, however, that timing and the nature of an asynchronous operation can affect whether or not the operation is truly canceled. Only lengthy queries are likely to be successfully canceled before they have completed. Faster operations such as asynchronous deletions or modifications typically complete before a CancelAsyncCall can be made. CancelAsyncCall attempts to cancel the current operation, but sometimes all that can be done is to release the IWbemObjectSink pointer.
Applications must never delete the object that exposes their IWbemObjectSink implementation without verifying that its reference count has reached zero. Due to the way in which Distributed COM (DCOM) forwards Release calls, there is no guarantee that this object will remain unused. Applications must always obey standard COM rules regarding reference counts.