Export (0) Print
Expand All

IEnumWbemClassObject::Next method

Use the IEnumWbemClassObject::Next method to get one or more objects starting at the current position in an enumeration. This method advances the current position in the enumeration by uCount objects, so that subsequent calls return the subsequent objects.

Syntax


HRESULT Next(
  [in]   LONG lTimeOut,
  [in]   ULONG uCount,
  [out]  IWbemClassObject **ppObjects,
  [out]  ULONG *puReturned
);

Parameters

lTimeOut [in]

Specifies the maximum amount of time in milliseconds that the call blocks before returning. If you use the constant WBEM_INFINITE (0xFFFFFFFF), the call blocks until objects are available. If you use the value 0 (WBEM_NO_WAIT), the call returns immediately, whether any objects are available or not.

uCount [in]

Number of requested objects.

ppObjects [out]

Pointer to enough storage to hold the number of IWbemClassObject interface pointers specified by uCount. This storage must be supplied by the caller. This parameter cannot be NULL. The caller must call Release on each of the received interface pointers when they are no longer needed.

puReturned [out]

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 Next method returns WBEM_S_FALSE when you have reached the end of the enumeration, even if objects have been returned successfully. The WBEM_S_NO_ERROR value returns only when the number of objects returned matches the number requested in uCount. The WBEM_S_TIMEDOUT value is returned when the number of objects returned is less than the number requested but you are not at the end of the enumeration. Therefore, you should use loop termination logic that examines the puReturned value to ensure that you have reached the end of the enumeration.

Return value

The Next method returns an HRESULT indicating the status of the method call. The following table lists the value contained within an HRESULT.

Return codeDescription
WBEM_E_INVALID_PARAMETER

One or more invalid parameters were specified in the call.

WBEM_E_OUT_OF_MEMORY

There was not enough memory to complete the enumeration.

WBEM_E_UNEXPECTED

An object in the enumeration has been deleted, destroying the validity of the enumeration.

WBEM_E_TRANSPORT_FAILURE

This indicates the failure of the remote procedure call (RPC) link between the current process and Windows Management.

WBEM_S_NO_ERROR

The number of objects returned was the same as the number requested.

WBEM_S_FALSE

The number of objects returned was less than the number requested. WBEM_S_FALSE is also returned when this method is called with a value of 0 for the uCount parameter.

WBEM_S_TIMEDOUT

A time-out occurred before you obtained all the objects.

 

Remarks

You may see COM-specific error codes returned if network problems cause you to lose the remote connection to Windows Management. On error, you can call the COM function GetErrorInfo to obtain more error information.

If more than one object is requested, and if the number of requested objects is returned, the function returns WBEM_S_NO_ERROR. If less than the requested number of objects is available, and if the enumeration has completed, those objects are returned and the function returns WBEM_S_FALSE.

If the enumeration has not completed, the call waits for objects to be available up to the specified time-out. If the enumeration times out before the objects are available, the function returns WBEM_S_TIMEDOUT.

Note  Because the call-back to the sink might not be returned at the same authentication level as the client requires, it is recommended that you use semisynchronous instead of asynchronous communication. For more information, see Calling a Method.

Examples

For an extended discussion and example of making queries in C++ and WMI, see Making WMI Queries In C++ on CodeProject.

In the following code, more than one object is requested:


HRESULT ProcessEnum( IEnumWbemClassObject*    pEnum )
{
    HRESULT    hRes = WBEM_S_NO_ERROR;

    // Final Next will return WBEM_S_FALSE
    while ( WBEM_S_NO_ERROR == hRes )
    {
        ULONG            uReturned;
        IWbemClassObject*    apObj[10];

        hRes = pEnum->Next( WBEM_INFINITE, 10, apObj, &uReturned );

        if ( SUCCEEDED( hRes ) )
        {
            // Do something with the objects.
            //ProcessObjects( uReturned,  apObj );

            for ( ULONG n = 0; n < uReturned; n++ )
            {
                apObj[n]->Release();
            }

        }    // If Enum succeeded...
    }    // While Enum is returning objects...

    return hRes;
}

Requirements

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Wbemcli.h (include Wbemidl.h)

Library

Wbemuuid.lib

DLL

Fastprox.dll

See also

IEnumWbemClassObject
Enumerating WMI

 

 

Show:
© 2014 Microsoft