Directory Services

IADsAccessControlList::get__NewEnum

The IADsAccessControlList::get__NewEnum method is used to obtain an enumerator object for the ACL to enumerate ACEs.

HRESULT get__NewEnum( 
  IUnknown** ppEnumerator
);

Parameters

ppEnumerator
[out] Pointer to pointer to the IUnknown interface used to retrieve IEnumVARIANT interface on an enumerator object for the ACL.

Return Values

This method returns the standard return values, including S_OK and E_FAIL. For more information about other return values, see ADSI Error Codes.

Remarks

Be aware that there are two underscores in get__NewEnum.

Example Code [Visual Basic]

The following code example makes an implicit call to the get__NewEnum method in the execution of the For Each loop.

Dim Dacl As IADsAccessControlList
Dim ace As IADsAccessControlEntry

On Error GoTo Cleanup

' Get DACL. Code omitted.

' Display the trustees for each of the ACEs
For Each ace In Dacl 
	Debug.Print ace.trustee
Next ace

Cleanup:
	If (Err.Number<>0) Then
		MsgBox("An error has occurred. " & Err.Number)
	End If
	Set Dacl = Nothing
	Set ace = Nothing

Example Code [C++]

The following code example shows how to enumerate ACEs using IADsAccessControlList::get__NewEnum.

HRESULT ListTrustees(IADsAccessControlList *pACL)
{
	IEnumVARIANT *pEnum = NULL;
	LPUNKNOWN	 pUnk = NULL;
	ULONG  lFetch = 0;
	BSTR	bstr = NULL;
	IADsAccessControlEntry *pACE = NULL;
	IDispatch *pDisp = NULL;
	VARIANT var;
	HRESULT hr = S_OK;

	VariantInit(&var);
	 
	hr = pACL->get__NewEnum(&pUnk);
	if (FAILED(hr)){goto Cleanup;}

	hr = pUnk->QueryInterface( IID_IEnumVARIANT, (void**) &pEnum );
	pUnk->Release();
	if (FAILED(hr)){goto Cleanup;}
	 
	hr = pEnum->Next( 1, &var, &lFetch );
	if (FAILED(hr)){goto Cleanup;}
	 
	while( hr == S_OK )
	{
		if ( lFetch == 1 )
		{
			if ( VT_DISPATCH != V_VT(&var) )
			{
				goto Cleanup;
		}
			pDisp = V_DISPATCH(&var);
			/////////////////////////
			// Get the individual ACE
			/////////////////////////
			hr = pDisp->QueryInterface( IID_IADsAccessControlEntry,
										(void**)&pACE ); 
			if ( SUCCEEDED(hr) )
			{
				pACE->get_Trustee(&bstr);
				printf("\n %S:\n", bstr);
				//ACE manipulation here
				SysFreeString(bstr);
				pACE->Release();
		}
			pACE->Release();
			pDisp->Release();
			VariantClear(&var);
	}
		hr = pEnum->Next( 1, &var, &lFetch );
}
	Cleanup:	
		if(pEnum) pEnum->Release();
		if(pUnk) pUnk->Release();
		if(bstr) SysFreeString(bstr);
		if(pACE) pACE->Release();
		VariantClear(&var);
		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 Iads.h.

See Also

IEnumVARIANT, IADsAccessControlEntry, IADsSecurityDescriptor