ADsBuildEnumerator

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

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

Parameters

pADsContainer

[in] Pointer to the IADsContainer interface for the object to enumerate.

ppEnumVariant

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

Return Values

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.

Example Code [C++]

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

[C++]
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

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Adshlp.h.
Library: Use ActiveDS.lib.

See Also

ADSI Error Codes, ADSI Functions, ADsEnumerateNext, ADsFreeEnumerator, IADsContainer, IEnumVARIANT