3.2.4.2.8 Invoking Synchronous and Semisynchronous Operations Returning Multiple Objects
If the client wants to invoke any of the following WMI methods semisynchronously, the client MUST set WBEM_FLAG_RETURN_IMMEDIATELY when making method calls. If the client wants to invoke any of the following methods synchronously, the client MUST NOT set WBEM_FLAG_RETURN_IMMEDIATELY when making IWbemServices method calls.
The methods returning multiple objects are as follows:
When the method execution fails, as indicated by the return value, the output parameter does not have IEnumWbemClassObject.
When IWbemServices method execution succeeds, an object of type IEnumWbemClassObject is returned to the client.
The client SHOULD obtain IWbemFetchSmartEnum interface using IRemUnknown and IRemUnknown2 interfaces as specified in [MS-DCOM], on this IEnumWbemClassObject interface. If client obtains IWbemFetchSmartEnum, the client MUST call IWbemFetchSmartEnum::GetSmartEnum to obtain IWbemWCOSmartEnum. The client SHOULD call IWbemWCOSmartEnum::Next method repeatedly to retrieve the objects. When IWbemWCOSmartEnum::Next returns WBEM_S_NO_ERROR or WBEM_S_TIMEDOUT, the client SHOULD call IEnumWbemClassObject::Next again. If IWbemWCOSmartEnum::Next returns an error as specified in 2.2.11 or returns WBEM_S_FALSE, the client MUST NOT call IWbemWCOSmartEnum::Next again.
If the server returns an error when obtaining IWbemFetchSmartEnum, the client MUST ignore the error and SHOULD call IEnumWbemClassObject::Next method repeatedly to retrieve the objects. When IEnumWbemClassObject::Next returns WBEM_S_NO_ERROR or WBEM_S_TIMEDOUT, the client SHOULD call IEnumWbemClassObject::Next again. If IEnumWbemClassObject::Next returns an error as specified in 2.2.11 or returns WBEM_S_FALSE, the client MUST NOT call IEnumWbemClassObject::Next again.
When the client made a semisynchronous call and subsequent IEnumWbemClassObject::Next or IWbemWCOSmartEnum::Next call returns an error, the client MUST interpret the error as the error of actual semisynchronous operation as though the operation is executed synchronously.
The client MUST NOT call IEnumWbemClassObject::Reset or IEnumWbemClassObject::Clone, if the IWbemServices method that created the IEnumWbemClassObject is passed WBEM_FLAG_FORWARD_ONLY flag.
If the client wants to start the enumerator from the first object, the client MUST call IEnumWbemClassObject::Reset, if the IWbemServices method that created the IEnumWbemClassObject is not passed WBEM_FLAG_FORWARD_ONLY flag.
If the client wants to create a new enumerator containing the same result set, the client MUST call IEnumWbemClassObject::Clone, if the IWbemServices method that created the IEnumWbemClassObject is not passed WBEM_FLAG_FORWARD_ONLY flag. The client SHOULD use IEnumWbemClassObject created using IEnumWbemClassObject::Clone as another result object by calling IEnumWbemClassObject::Next.
If the client wants to get some results of the operation asynchronously, the client MUST call IEnumWbemClassObject::NextAsync with the uCount, in this case next uCount result objects are returned in IWbemObjectSink passed as a parameter to IEnumWbemClassObject::NextAsync.