Share via

3.1.4.4.3 IEnumWbemClassObject::NextAsync (Opnum 5)

  • Article

The IEnumWbemClassObject::NextAsync method is the asynchronous version of the IEnumWbemClassObject::Next method. It provides controlled asynchronous retrieval of CIM objects to a sink. The server MUST asynchronously get one or more CIM objects, starting at the current position in an enumeration, and MUST move the current position by the number of CIM objects. When IEnumWbemClassObject is created, the current position MUST be set on the first CIM object of the collection. The order of the CIM objects that are stored in the enumerator is arbitrary.

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

uCount: MUST be the number of CIM objects being requested.

pSink: MUST be a pointer to the IWbemObjectSink interface, which MUST represent the sink to receive the CIM object. As each batch of CIM objects is requested, they MUST be delivered to the IWbemObjectSink::Indicate method to which pSink points (as specified in section 3.1.4.2.1) and MUST be followed by a final call to the IWbemObjectSink::SetStatus method to which pSink points, as specified in section 3.1.4.2.2. This parameter MUST NOT be NULL. In error cases, indicated by the HRESULT return value, the supplied IWbemObjectSink interface pointer MUST NOT be used by the server.

Return Values: This method MUST return an HRESULT value that MUST indicate the status of the method call. The server MUST return WBEM_S_NO_ERROR (specified in section 2.2.11) to indicate the successful completion of the method.

WBEM_S_NO_ERROR (0x00)

The server MUST locate the entry in EnumWbemClassObjectTable with EnumWbemClassObjectPointer matching IEnumWbemClassObject.

The server MUST validate that the security principal that makes the call is the same as the ClientSecurityContext of the SemiSinkResultSetObject pointed to by the entry in the EnumWbemClassObjectTable; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

The server MUST serialize execution of the IEnumWbemClassObject::Next call and asynchronous execution of the IEnumWbemClassObject::NextAsync call, the IEnumWbemClassObject::Reset call, and the IEnumWbemClassObject::Clone call.

In response to IEnumWbemClassObject::NextAsync, the server MUST synchronously evaluate the uCount parameter as specified in this section. If the uCount parameter value is zero, the server MUST return WBEM_S_FALSE. If the uCount parameter value is greater than zero, the server MUST add a record in SinkQueue of an entry in EnumWbemClassObjectTable for this operation. The new record in SinkQueue will store a reference to pSink in WbemObjectSinkPointer and store the requested count in RemainingRequestCount.

The failed method execution MUST return an error in the format specified in section 2.2.11.

If the method succeeds, the server MUST wait asynchronously until either the SemiSinkResultSetObject contains RemainingRequestCount objects starting at CurrentIndex, or its OperationFinished flag is set to true, or the enumeration encounters an error. At that time:

  • If the enumeration encountered an error, the server MUST deliver the error to the client by calling IWbemObjectSink::SetStatus.

  • If the enumeration finished with fewer than the requested number of objects, the server MUST deliver them to the client by calling the IWbemObjectSink::Indicate method and then indicate completion by calling IWbemObjectSink::SetStatus with status WBEM_S_FALSE.

  • Otherwise, the server MUST deliver RemainingRequestCount objects to the client by calling the IWbemObjectSink::Indicate method and then indicate completion by calling IWbemObjectSink::SetStatus with status WBEM_S_NO_ERROR.

The current index position pointed to by CurrentIndex in an entry of EnumWbemClassObjectTable MUST be incremented by the number of CIM objects delivered to the client.

Finally, the server MUST remove the entry from SinkQueue.