ADsBuildEnumerator function (adshlp.h)

The ADsBuildEnumerator function creates an enumerator object for the specified ADSI container object.

Syntax

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

Parameters

[in] pADsContainer

Type: IADsContainer*

Pointer to the IADsContainer interface for the object to enumerate.

[out] ppEnumVariant

Type: IEnumVARIANT**

Pointer to an IEnumVARIANT interface pointer that receives the enumerator object created for the specified container object.

Return value

Type: HRESULT

This method supports the standard HRESULT return values, including S_OK for a successful operation. For more information about other return values, see ADSI Error Codes.

Remarks

The ADsBuildEnumerator helper function wraps the calls used to retrieve the IEnumVARIANT interface on the enumerator object.

To enumerate the available objects in a container

  1. Call the ADsBuildEnumerator function to create an IEnumVARIANT object that will enumerate the contents of the container.
  2. Call the ADsEnumerateNext function as many times as necessary to retrieve the items from the enumerator object.
  3. Call the ADSFreeEnumerator function to release the enumerator object when it is no longer required.
If the server supports paged searches and the client has specified a page size that exceeds the maximum search results allowed by the server, the ADsBuildEnumerator function will forward errors and results from the server to the user.

Examples

The following code example shows how the ADsBuildEnumerator, ADsEnumerateNext, and ADSFreeEnumerator functions can be used to enumerate the contents of a container.

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;
}

Requirements

   
Minimum supported client Windows Vista
Minimum supported server Windows Server 2008
Target Platform Windows
Header adshlp.h
Library Activeds.lib
DLL Activeds.dll

See also

ADSI Error Codes

ADSI Functions

ADsEnumerateNext

ADsFreeEnumerator

IADsContainer

IEnumVARIANT