3.4.5.2.1.1 IEnumVdsObject::Next (Opnum 3)

  • Article

The Next method returns a specified number of objects in the enumeration. It begins from the current point.

 [helpstring("method Next")] HRESULT Next(
   [in] unsigned long celt,
   [out, size_is(celt), length_is(*pcFetched)] 
     IUnknown** ppObjectArray,
   [out] unsigned long* pcFetched
 );

celt: The number of elements to retrieve from the enumeration.

ppObjectArray: A pointer to an array of IUnknown interfaces. The size of this array MUST be equal to celt. If successfully completed, it receives an array of the IUnknown interfaces of the next objects in the enumeration; the number of elements in this array MUST be equal in size to the value of pcFetched. Callers MUST release each IUnknown interface that is received.

pcFetched: A pointer to a variable that, upon successful completion, receives the number of elements that are successfully received in ppObjectArray.

Return Values: The method MUST return zero or a non-error HRESULT (as specified in [MS-ERREF]) to indicate success or return an implementation-specific nonzero error code to indicate failure. For the HRESULT values predefined by the Virtual Disk Service Remote Protocol, see section 2.2.3.

If S_FALSE is returned, the client MUST check the value that pcFetched references and not access more than the number of elements returned in ppObjectArray.

When the server receives this message, it MUST validate the following parameters:

  • Verify that ppObjectArray is not NULL.

  • Verify that pcFetched is not NULL.

The server MUST perform the following:

  • If the number of objects from the current index to the end of the enumeration is greater than or equal to the number of objects being requested in celt:

    • Populate the IUnknown pointers in ppObjectArray with the next IUnknown pointers (the amount of which celt specifies) in the enumeration that is starting from the current index.

    • Set the value that pcFetched references to celt.

    • Increment the current index by celt.

    • Return an HRESULT that indicates failure or success.

  • If the number of objects from the current index to the end of the enumeration is less than the number of objects being requested in celt:

    • Populate the IUnknown pointers in ppObjectArray with the next IUnknown pointers in the enumeration. Start from the current index to the end of the enumeration.

    • Set the value that pcFetched references to the number of objects that were populated in ppObjectArray.

    • Increment the current index by the number of objects that were populated in ppObjectArray.

    • Return S_FALSE (HRESULT of 0x00000001) if successful, or any non-zero error for failure.

  • If the current index is already past the list of objects in the enumeration, set the value that pcFetched references to 0 and return S_FALSE (HRESULT of 0x00000001) if successful, or any non-zero error for failure.