IEnum::Next

HRESULT IEnum::Next(celt, rgelt, pceltFetched)

Attempt to get the next celt items in the enumeration sequence, and return them through the array pointed to by rgelt. If fewer than the requested number of elements remain in the sequence, then just return the remaining ones; the actual number of elements returned is passed through *pceltFetched (unless it is NULL). If the requested celt elements are in fact returned, then return S_OK; otherwise return S_FALSE. An error condition other than simply "not that many elements left" will return an SCODE which is a failure code rather than one of these two success values.

To clarify:

If S_OK is returned, then on exit the all celt elements requested are valid and returned in rgelt.
If S_FALSE is returned, then on exit only the first *pceltFetched entries of rgelt are valid. The contents of the remaining entries in the rgelt array are indeterminate.
If an error value is returned, then on exit no entries in the rgelt array are valid; they are all in an indeterminate state.

Argument	Type	Description
celt	ULONG	The number of elements that are to be returned.
rgelt16.	ELT_T*	An array of size at least celt in which the next elements are to be returned.
pceltFetched	ULONG*	May be NULL if celt is one. If non-NULL, then this is set with the number of elements actually returned in rgelt.

Return Value	Meaning
S_OK	Success. The requested number of elements were returned.
S_FALSE	Success. Fewer than the requested number of elements were returned.
E_UNEXPECTED	An unknown error occurred.