Método IEnumIDList::Next (shobjidl_core.h)

Recupera o número especificado de identificadores de item na sequência de enumeração e avança a posição atual pelo número de itens recuperados.

Sintaxe

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

Parâmetros

[in] celt

Tipo: ULONG

O número de elementos na matriz referenciada pelo parâmetro rgelt .

[out] rgelt

Tipo: LPITEMIDLIST*

O endereço de um ponteiro para uma matriz de ponteiros ITEMIDLIST que recebem os identificadores de item. A implementação deve alocar esses identificadores de item usando CoTaskMemAlloc. O aplicativo de chamada é responsável por liberar os identificadores de item usando CoTaskMemFree.

As estruturas ITEMIDLIST retornadas na matriz são relativas ao IShellFolder que está sendo enumerado.

[out] pceltFetched

Tipo: ULONG*

Um ponteiro para um valor que recebe uma contagem dos identificadores de item realmente retornados no rgelt. A contagem pode ser menor do que o valor especificado no parâmetro celt . Esse parâmetro só poderá ser NULL na entrada se celt = 1, pois nesse caso o método só pode recuperar um (S_OK) ou zero (S_FALSE).

Retornar valor

Tipo: HRESULT

Retorna S_OK se o método recuperou com êxito os elementos celt solicitados. Esse método só retornará S_OK se a contagem completa de itens solicitados for recuperada com êxito.

S_FALSE indica que mais itens foram solicitados do que permaneceram na enumeração. O valor apontado pelo parâmetro pceltFetched especifica o número real de itens recuperados. Observe que o valor será 0 se não houver mais itens a serem recuperados.

Retorna um valor de erro definido por COM caso contrário.

Comentários

Se esse método retornar um código de erro COM (Component Object Model) (conforme determinado pela macro FAILED ), nenhuma entrada na matriz rgelt será válida na saída. Se esse método retornar um código de êxito (como S_OK ou S_FALSE), o ULONG apontado pelo parâmetro pceltFetched determinará quantas entradas na matriz rgelt são válidas na saída.

A distinção é importante no caso em que o celt> 1. Por exemplo, se você passar celt=10 e houver apenas três elementos restantes, *pceltFetched será 3 e o método retornará S_FALSE o que significa que você chegou ao final do arquivo. Os três elementos buscados serão armazenados em rgelt e são válidos.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	shobjidl_core.h (inclua Shobjidl.h)
DLL	Shell32.dll (versão 4.0 ou posterior)

Confira também

IEnumIDList