Share via

3.1.4.4.2 IEnumWbemClassObject::Next (Opnum 4)

  • Article

When the IEnumWbemClassObject::Next method is invoked, the server MUST get zero or more CIM objects starting at the current position in an enumeration. The server MUST also move the current position by the number of CIM objects in the uCount parameter. 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 Next(
   [in] long lTimeout,
   [in] ULONG uCount,
   [out, size_is(uCount), length_is(*puReturned)] 
     IWbemClassObject** apObjects,
   [out] ULONG* puReturned
 );

lTimeout: MUST be the maximum amount of time, in milliseconds, that the IEnumWbemClassObject::Next method call allows to pass before it times out. If the constant WBEM_INFINITE (0xFFFFFFFF) is specified, the call MUST wait until one or more CIM objects are available. If the value 0x0 (WBEM_NO_WAIT) is specified, the call MUST return the available CIM objects, if any, at the time the call is made, and MUST NOT wait for any more objects.

uCount: MUST be the number of requested CIM objects to return.

apObjects: MUST be a pointer to an array of IWbemClassObject interface pointers. At entry, this parameter MUST NOT be NULL. Upon return by the server, this parameter can be NULL if a failure occurs or if there are no results.

puReturned: MUST be a pointer to a ULONG type that receives the number of CIM objects that are returned. When sent by the client, this parameter MUST NOT be NULL. Upon return by the server, this parameter value can be zero if a failure occurs or if there are no results.

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 EnumWbemClassObjectTable; otherwise, WBEM_E_ACCESS_DENIED MUST be returned.

In response to the IEnumWbemClassObject::Next method call, the server MUST evaluate the uCount and lTimeout parameters (as specified in this section) and MUST return the requested number of CIM objects, if any are available. The server MUST perform the operation within the time allowed by lTimeout.

If the earlier semisynchronous operation is finished, and if the server does not have the requested number of CIM objects, the server MUST return WBEM_S_FALSE with the available CIM objects; otherwise, WBEM_S_NO_ERROR is returned with the requested number of CIM objects. The current index position pointed to by the CurrentIndex entry in EnumWbemClassObjectTable MUST be incremented with the number of CIM objects returned.

If the earlier semisynchronous operation is not finished and the server does not have the requested number of CIM objects, the method MUST wait the amount of time in lTimeout for the operation to finish or for the availability of the requested number of objects, whichever is earlier. The server MUST fill the output parameters of the method as specified previously. If the number of the remaining CIM objects to be given to the client is less than the number of requested CIM objects, the server MUST return WBEM_S_TIMEDOUT; otherwise, WBEM_S_NO_ERROR is returned. The current index position pointed to by the CurrentIndex entry in EnumWbemClassObjectTable MUST be incremented with the number of CIM objects returned.

If the original semisynchronous operation fails, the server MUST return the error code that the original method would have returned in its synchronous version.

The failed method execution MUST set the value that is referenced by the output parameters to NULL and MUST return an error in the format that is specified in section 2.2.11.