ADsBuildEnumerator function (adshlp.h)

Article
02/22/2024

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

Call the ADsBuildEnumerator function to create an IEnumVARIANT object that will enumerate the contents of the container.
Call the ADsEnumerateNext function as many times as necessary to retrieve the items from the enumerator object.
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

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