Edit

IEnumIDList::Next method (shobjidl_core.h)

  • Article

Retrieves the specified number of item identifiers in the enumeration sequence and advances the current position by the number of items retrieved.

Syntax

HRESULT Next(
  [in]  ULONG         celt,
  [out] PITEMID_CHILD *rgelt,
  [out] ULONG         *pceltFetched
);

Parameters

[in] celt

Type: ULONG

The number of elements in the array referenced by the rgelt parameter.

[out] rgelt

Type: LPITEMIDLIST*

The address of a pointer to an array of ITEMIDLIST pointers that receive the item identifiers. The implementation must allocate these item identifiers using CoTaskMemAlloc. The calling application is responsible for freeing the item identifiers using CoTaskMemFree.

The ITEMIDLIST structures returned in the array are relative to the IShellFolder being enumerated.

[out] pceltFetched

Type: ULONG*

A pointer to a value that receives a count of the item identifiers actually returned in rgelt. The count can be smaller than the value specified in the celt parameter. This parameter can be NULL on entry only if celt = 1, because in that case the method can only retrieve one (S_OK) or zero (S_FALSE) items.

Return value

Type: HRESULT

Returns S_OK if the method successfully retrieved the requested celt elements. This method only returns S_OK if the full count of requested items are successfully retrieved.

S_FALSE indicates that more items were requested than remained in the enumeration. The value pointed to by the pceltFetched parameter specifies the actual number of items retrieved. Note that the value will be 0 if there are no more items to retrieve.

Returns a COM-defined error value otherwise.

Remarks

If this method returns a Component Object Model (COM) error code (as determined by the FAILED macro), then no entries in the rgelt array are valid on exit. If this method returns a success code (such as S_OK or S_FALSE), then the ULONG pointed to by the pceltFetched parameter determines how many entries in the rgelt array are valid on exit.

The distinction is important in the case where celt > 1. For example, if you pass celt=10 and there are only 3 elements left, *pceltFetched will be 3 and the method will return S_FALSE meaning that you reached the end of the file. The three fetched elements will be stored into rgelt and are valid.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows 2000 Server [desktop apps only]
Target Platform Windows
Header shobjidl_core.h (include Shobjidl.h)
DLL Shell32.dll (version 4.0 or later)

See also

IEnumIDList