3.1.2.1 Next (Opnum 3)

  • Article

The Next method retrieves the next specified number of objects in the collection.

 HRESULT Next(
   [in] ULONG celt,
   [out, size_is(celt), length_is(*pceltFetched)] 
     VSS_OBJECT_PROP* rgelt,
   [out] ULONG* pceltFetched
 );

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

rgelt: A pointer to an array of VSS_OBJECT_PROP structures that upon completion, contain the next celt objects from the collection.

pceltFetched: A pointer to a ULONG variable that upon completion, contains the number of objects in rgelt that are populated in this call. The value of pceltFetched MUST be less than or equal to celt.

Return Values: The method MUST return the following error code for the specific conditions.

Return value/code

Description

0x00000001

S_FALSE

The number of objects returned is less than the number requested.

0x80070057

E_INVALIDARG

Returned when parameter celt is 0, or when rgelt or pceltFetched is NULL.

For any other conditions, the method MUST return zero when it has succeeded or an implementation-specific nonzero error code on failure.

No exceptions are thrown except those that are thrown by the underlying RPC protocol [MS-RPCE].

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

  • The celt parameter is greater than zero.

  • The rgelt parameter is not NULL.

  • The pceltFetched parameter is not NULL.

The server MUST copy the next celt objects from the collection to the rgelt object array and set pceltFetched to the number of objects actually returned. If the collection contains fewer than celt objects, the remaining objects in the collection MUST be copied to rgelt, pceltFetched MUST be set to the number of objects copied, and the server MUST return 0x00000001 as the method return value.

After the objects are copied to the rgelt array, the server MUST update an internal cursor variable to point to the first object after the last object retrieved, so that a subsequent call to Next begins to retrieve objects that start immediately after those returned on the former call.