ADsBuildEnumerator

ADsBuildEnumerator function

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

Syntax


HRESULT ADsBuildEnumerator(
  _In_  IADsContainer *pADsContainer,
  _Out_ IEnumVARIANT  **ppEnumVariant
);

Parameters

pADsContainer [in]

Type: IADsContainer*

Pointer to the IADsContainer interface for the object to enumerate.

ppEnumVariant [out]

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.

Aa772177.wedge(en-us,VS.85).gif 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

Header

Adshlp.h

Library

Activeds.lib

DLL

Activeds.dll

See also

ADSI Error Codes
ADSI Functions
ADsEnumerateNext
ADsFreeEnumerator
IADsContainer
IEnumVARIANT

 

 

Show:
© 2016 Microsoft