Interface IEnumWbemClassObject

For documentation on the semantics of COM enumerators, see IEnumVariant in the Microsoft® Platform SDK. The IEnumWbemClassObject interface semantically resembles the standard enumerators, except that it is designed also to support asynchronous and semisynchronous call behavior.

This interface is derived from IUnknown and supports its methods.

IEnumWbemClassObject::Reset

The IEnumWbemClassObject::Reset method resets the current position of the enumerator to the beginning of the enumeration. Since CIM objects can be dynamic, calling this method does not necessarily return the same list of objects that you obtained previously.

Parameters

None.

Return Values

DCOM-specific error codes may also be returned if the remote connection to the CIM Object Manager (CIMOM) is lost due to network problems.

If an error code is returned, you can call the COM function GetErrorInfo for more information about the error.

IEnumWbemClassObject::Next

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

Parameters

Return Values

You may see DCOM-specific error codes returned if network problems cause you to lose the remote connection to CIMOM.
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 to determine loop termination is correct.

void ListObjects(
    IEnumWbemClassObject *pEnum,
    IWbemObjectSink *pSink
    )
{
    HRESULT hRes;
    ULONG uReturned;

   while (1)
    {
IWbemClassObject *pObj = 0;

        hRes = pEnum->Next(0, 1, &pObj, &uReturned);

        if (hRes == WBEM_S_FALSE)
            break;

        ...use object

        pObj->Release();
    }
}

In the next sample, Next may return WBEM_S_FALSE, even though some objects are returned. You need to check uReturned:

void ListObjects2(IEnumWbemClassObject *pEnum)
{

‹^# $ K + ›IEnumWbemClassObject::NextAsync¦@¦

<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>

Use the IEnumWbemClassObject::NextAsync method when a controlled asynchronous retrieval of objects to a sink is required. Normal asynchronous retrieval, such as a call to IWbemServices::ExecQueryAsync_hmm_IWbemServices_ExecQueryAsync, results in uncontrolled delivery of objects to the caller’s implementation of IWbemObjectSink_hmm_IWbemObjectSink. This method is helpful for cases where components want to control delivery of objects.

Parameters

The sink to receive the objects. The sink must be implemented by the caller. As each batch of objects is requested, they will be delivered to the pSink->Indicate method followed by a final call to pSink->SetStatus. If the sink is going to be used to deliver objects, this API will return WBEM_S_NO_ERROR, even if the number of objects to be delivered is less than requested. However, if there are no more objects remaining, then the pSink parameter will be ingored (no calls to pSink->SetStatus will be made). Instead, this API will return WBEM_S_FALSE.

 

Return Values

A call to the COM function GetErrorInfo provides more information about the error.

DCOM-specific error codes may also be returned if network problems cause you to lose the remote connection to CIMOM.

 

Remarks

As the objects become available, the caller’s implementation of IWbemObjectSink::Indicate_hmm_IWbemObjectSink_Indicate is called zero or more times to deliver the objects. This is followed by a call to IWbemObjectSink::SetStatus_hmm_IWbemObjectSink_SetStatus with a value of WBEM_S_NO_ERROR if uCount items are returned.

If fewer objects are available than the number requested, IWbemObjectSink::Indicate is called for those objects that are available. This is followed by a call to IWbemObjectSink::SetStatus with a value of WBEM_S_FALSE, or the error code if an error occurred. If there are no available objects, Indicate is not called. However, a final call to IWbemObjectSink::SetStatus will always occur to indicate the status of the entire operation.

Sample Code

}

‹^# $ K + ›IEnumWbemClassObject::Clone¦@¦

<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>

The IEnumWbemClassObject::Clone method makes a logical copy of the entire enumerator, retaining its current cursor position. This method will make only a "best effort" copy. Due to the dynamic nature of many CIM objects, it is possible that the new enumerator does not enumerate the same set of objects as the source enumerator.

When the enumeration was initialized with the WBEM_FLAG_FORWARD_ONLY flag, IEnumWbemClassObject::Clone is not supported.

Any pending asynchronous deliveries begun by NextAsync_hmm_IEnumWbemClassObject_NextAsync are not cloned.

Parameters

Receives a pointer to a new IEnumWbemClassObject object. The caller must call Release when the interface pointer is no longer required. On error, there will not be a return of a new object.

 

Return Values

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

DCOM-specific error codes may also be returned if network problems cause you to lose the remote connection to CIMOM.

Sample Code

}

‹^# $ K + ›IEnumWbemClassObject::Skip¦@¦

<span style=color:#FF0000>[This is preliminary documentation and subject to change.]</span>

You can use the IEnumWbemClassObject::Skip method to move the current cursor position ahead by a specified number of objects. Also, this affects subsequent calls to NextAsync, but it does not affect pending deliveries begun with NextAsync.

Parameters

Specifies the number of objects to skip. If this parameter is greater than the number of objects left to enumerate then this call will skip to the end of the enumeration and WBEM_S_FALSE will be returned.

 

Return Values

DCOM-specific error codes may also be returned if network problems cause you to lose the remote connection to CIMOM.