IEnumWbemClassObject::NextAsync

[This is preliminary documentation and subject to change.]

The IEnumWbemClassObject::NextAsync method is used when a controlled asynchronous retrieval of objects to a sink is required. Normal asynchronous retrieval, such as a call to IWbemServices::ExecQueryAsync, results in uncontrolled delivery of objects to the caller's implementation of IWbemObjectSink. This method is helpful for cases where components can only handle a reduced rate of delivery.

HRESULT NextAsync(
  [in] ULONGARG uCount, 
  [in] IWbemObjectSink *pSink 
);
 

Parameters

uCount

The number of objects being requested.

pSink

The sink to receive the objects. The sink must be implemented by the caller.

Return Values

Remarks

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. A call to Reset does not affect delivery of objects currently in progress as a result of previous calls. Reset only causes new calls to start at the beginning of the object sequence.

The IWbemObjectSink::SetStatus method is called to indicate the actual result of the request. As the objects become available, IWbemObjectSink::Indicate is called zero or more times to deliver the objects, followed by a call to IWbemObjectSink::SetStatus with a value of S_OK, if uCount items are returned.

If fewer objects are available than the number requested, then IWbemObjectSink::Indicate is called for those objects that are available. This is followed by a call to IWbemObjectSink::SetStatus with a value of S_FALSE, or the error code if an error occurred. If there are no available objects, Indicate is not called.

Sample Code

void ListObjects3(
    IEnumWbemClassObject *pEnum,
    IWbemObjectSink *pSink
    )
{
    HRESULT hRes;

    while (1)
    {
        hRes = pEnum->NextAsync(5, pSink);

            // Wait until sink is ready for more by
            // some private mechanism. Note that hRes gives
            // no indication as to whether to continue the
            // enumeration or not.

           BOOL bContinue = WaitUntilMoreObjectsNeeded();

            if (!bContinue)
                break;
    }
}