Função ADsBuildEnumerator (adshlp.h)

Artigo
02/23/2024

A função ADsBuildEnumerator cria um objeto enumerador para o objeto de contêiner ADSI especificado.

Sintaxe

HRESULT ADsBuildEnumerator(
  [in]  IADsContainer *pADsContainer,
  [out] IEnumVARIANT  **ppEnumVariant
);

Parâmetros

[in] pADsContainer

Tipo: IADsContainer*

Ponteiro para a interface IADsContainer para o objeto enumerar.

[out] ppEnumVariant

Tipo: IEnumVARIANT**

Ponteiro para um ponteiro de interface IEnumVARIANT que recebe o objeto enumerador criado para o objeto de contêiner especificado.

Retornar valor

Tipo: HRESULT

Esse método dá suporte aos valores de retorno HRESULT padrão, incluindo S_OK para uma operação bem-sucedida. Para obter mais informações sobre outros valores retornados, consulte Códigos de erro ADSI.

Comentários

A função auxiliar ADsBuildEnumerator encapsula as chamadas usadas para recuperar a interface IEnumVARIANT no objeto enumerador.

Para enumerar os objetos disponíveis em um contêiner

Chame a função ADsBuildEnumerator para criar um objeto IEnumVARIANT que enumerará o conteúdo do contêiner.
Chame a função ADsEnumerateNext quantas vezes forem necessárias para recuperar os itens do objeto enumerador.
Chame a função ADSFreeEnumerator para liberar o objeto enumerador quando ele não for mais necessário.

Se o servidor der suporte a pesquisas paginadas e o cliente tiver especificado um tamanho de página que exceda o máximo de resultados de pesquisa permitidos pelo servidor, a função ADsBuildEnumerator encaminhará erros e resultados do servidor para o usuário.

Exemplos

O exemplo de código a seguir mostra como as funções ADsBuildEnumerator, ADsEnumerateNext e ADSFreeEnumerator podem ser usadas para enumerar o conteúdo de um contêiner.

HRESULT PrintAllObjects(IADsContainer* pContainer)
{
    HRESULT hr;
     
    if(NULL == pContainer) 
    {
        return E_INVALIDARG;
    }
     
    IEnumVARIANT *pEnum = NULL;

    // Create an enumerator object in the container.
    hr = ADsBuildEnumerator(pContainer, &pEnum);
    if(SUCCEEDED(hr))
    {
        VARIANT var;
        ULONG ulFetched = 0L;

        // Get the next contained object.
        while(S_OK == (hr = ADsEnumerateNext(pEnum, 1, &var, &ulFetched)) && (ulFetched > 0))
        {
            IADs *pADs;

            // Print the object
            hr = V_DISPATCH(&var)->QueryInterface(IID_IADs, (void**)&pADs);
            if(SUCCEEDED(hr))
            {
                CComBSTR sbstr;
                IADsContainer *pChildContainer;

                hr = pADs->get_Name(&sbstr);
                if(SUCCEEDED(hr))
                {
                    wprintf(sbstr);
                    wprintf(L"\n");
                }

                hr = pADs->QueryInterface(IID_IADsContainer, (void**)&pChildContainer);
                if(SUCCEEDED(hr))
                {
                    // If the retrieved object is a container, recursively print its contents as well.
                    PrintAllObjects(pChildContainer);
                }
                
                pADs->Release();
            }
            
            // Release the VARIANT.
            VariantClear(&var);
        }
        
        ADsFreeEnumerator(pEnum);
    }

    return hr;
}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	adshlp.h
Biblioteca	Activeds.lib
DLL	Activeds.dll