IEnumWbemClassObject::Next

[This is preliminary documentation and subject to change.]

The IEnumWbemClassObject::Next method returns the next object or objects starting at the current cursor position. It then advances the cursor position by that many objects, so that subsequent calls return the subsequent objects.

HRESULT Next(
  [in] long lTimeOut,
  [in] ULONGARG uCount,
  [out, size_is(uCount), length_is(*puReturned)] IWbemClassObject **ppObjects,
  [out] ULONGARG *puReturned
);
 

Parameters

lTimeout

Specifies the maximum amount of time in milliseconds you must wait before objects are available. If you use the Win32® constant INFINITE (0xFFFFFFFF), the call blocks until objects are available. If you use the value zero, the call immediately returns with those objects that are waiting.

uCount

The number of requested objects.

ppObjects

A pointer to enough storage to hold the number of pointers specified by uCount. This storage must be supplied by the caller. It cannot be NULL, but must point to NULL. The caller must call Release on each of the objects using the pointers that are returned when they are no longer needed.

puReturned

A pointer to a ULONG that receives the number of objects returned. This number can be less than the number requested in uCount. This pointer cannot be NULL.

Note  The IWbemClassObject::Next method returns S_FALSE even when a nonzero number of objects is returned. S_OK is returned only when the number of objects returned matches the number requested in uCount. Therefore, loop termination logic should examine the puReturned value to ensure you have reached the end of the enumeration.

Return Values

On error, you can call the COM function GetErrorInfo to obtain more error information.

In the following sample, since objects are only requested one at a time, checking the return code for S_OK is correct:

void ListObjects(IEnumWbemClassObject *pEnum)
{
    pEnum->Reset();

    IWbemClassObject *pObject = 0;
    ULONG uReturned;

    while (pEnum->Next(INFINITE, 1, &pObject, &uReturned) == S_OK)
    {
        pObject->… // Access IWbemClassObject methods
        pObject->Release();
    }
}
 

In the next sample, Next may return S_FALSE, even though some objects are returned, so checking uReturned is required:

void ListObjects2(IEnumWbemClassObject *pEnum)
{
    pEnum->Reset();

    IWbemClassObject *paObjects[10];
    ULONG uReturned;
    HRESULT hRes;

    while (1)
    {
        hRes = pEnum->Next(INFINITE, 10, paObjects, &uReturned);

        if (uReturned == 0)
            break;

        for (ULONG u = 0; u < uReturned; u++)
        {
            IWbemClassObject *pObj = paObjects[u];


            // ... use the object

            pObj->Release();
        }

    }

    // examine hRes to see if the termination finished normally
}