IADsAccessControlList

The IADsAccessControlList interface is a dual interface that manages individual access-control entries (ACEs).

Methods in Vtable Order

The IADsAccessControlList interface inherits the methods of the standard COM interfaces:

• IUnknown
• IDispatch

In addition, IADsAccessControlList defines the following methods.

Properties

The IADsAccessControlList interface defines the following properties. The preceding table includes access methods for these properties.

Remarks

An access-control list (ACL) is a collection of ACEs that can provide more specific access control to the same ADSI object for different clients. In general, different providers implement different access controls and therefore the behavior of the object is specific to the provider. For more information, see the provider documentation. For more information about Microsoft® providers, see ADSI System Providers. Currently, only the LDAP provider supports access controls.

Before you can work with an object ACE, first obtain the ACL to which they belong. ACLs are managed by security descriptors and can be of either discretionary ACL and system ACL. For more information, see IADsSecurityDescriptor.

Using the properties and methods of the IADsAccessControlList interface, you can retrieve and enumerate ACEs, add new entries to the list, or remove existing entries.

To manage access controls over an ADSI

1. First, retrieve the security descriptor of the object that implements the IADsSecurityDescriptor interface.
2. Second, retrieve the ACL from the security descriptor.
3. Third, work with the ACE, or ACEs, of the object in the ACL.

To make any new or modified ACEs persistent

1. First, add the ACE to the ACL.
2. Second, assign the ACL to the security descriptor.
3. Third, commit the security descriptor to the directory store.

For more information on DACLs, see Null DACLs and Empty DACLs.

Example Code [Visual Basic]

The following code example shows the general procedure used to work with access control entries of a discretionary ACL.

Dim X As IADs
Dim Namespace As IADsOpenDSObject
Dim SecurityDescriptor As IADsSecurityDescriptor
Dim Dacl As IADsAccessControlList

On Error GoTo Cleanup
 
Set Namespace = GetObject("LDAP://")
Set X= Namespace.OpenDSObject("LDAP://DC=Fabrikam,DC=Com, vbNullString, vbNullString,  ADS_SECURE_AUTHENTICATION)
 
Set SecurityDescriptor = X.Get("ntSecurityDescriptor")
Debug.Print SecurityDescriptor.Owner
Debug.Print SecurityDescriptor.Group
 
Set Dacl = SecurityDescriptor.DiscretionaryAcl
Debug.Print Dacl.AceCount
 
For Each Obj In Dacl
   Debug.Print Obj.Trustee
   Debug.Print Obj.AccessMask
   Debug.Print Obj.AceFlags
   Debug.Print Obj.AceType
Next

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

Example Code [C++]

The following code enumerates ACEs from a DACL.

IADs *pADs = NULL;
IDispatch *pDisp = NULL;
IADsSecurityDescriptor *pSD = NULL;
VARIANT var;
HRESULT hr = S_OK;
 
VariantInit(&var);

hr = ADsOpenObject(L"LDAP://OU=Sales, DC=Fabrikam,DC=com",NULL,NULL,
				 ADS_SECURE_AUTHENTICATION, IID_IADs,(void**)&pADs);
if(FAILED(hr)) {goto Cleanup;}

hr = pADs->Get(CComBSTR("ntSecurityDescriptor"), &var);
if(FAILED(hr)) {goto Cleanup;}

pDisp = V_DISPATCH(&var);

hr = pDisp->QueryInterface(IID_IADsSecurityDescriptor,(void**)&pSD);
if(FAILED(hr)) {goto Cleanup;}
pDisp->Release();


pSD->get_DiscretionaryAcl(&pDisp);

hr = pDisp->QueryInterface(IID_IADsAccessControlList,(void**)&pACL);
if(FAILED(hr)) {goto Cleanup;}

hr = DisplayAccessInfo(pSD);
if(FAILED(hr)) {goto Cleanup;}
VariantClear(&var);

Cleanup:
	if(pADs) pADs->Release();
	if(pDisp) pDisp->Release();
	if(pSD) pSD->Release();
	return hr;



HRESULT DisplayAccessInfo(IADsSecurityDescriptor *pSD)
{
	LPWSTR lpszFunction = L"DisplayAccessInfo";
	IDispatch *pDisp = NULL;
	IADsAccessControlList *pACL = NULL;
	IADsAccessControlEntry *pACE = NULL;
	IEnumVARIANT *pEnum = NULL;
	IUnknown *pUnk = NULL;
	HRESULT hr = S_OK;
	ULONG nFetch = 0;
	BSTR bstrValue = NULL;
	VARIANT var;
	LPWSTR lpszOutput = NULL;
	LPWSTR lpszMask = NULL;
	size_t nLength = 0;

	VariantInit(&var);

	hr = pSD->get_DiscretionaryAcl(&pDisp);
	if(FAILED(hr)){goto Cleanup;}
	hr = pDisp->QueryInterface(IID_IADsAccessControlList,(void**)&pACL);
	if(FAILED(hr)){goto Cleanup;}

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

	hr = pUnk->QueryInterface(IID_IEnumVARIANT,(void**)&pEnum);

	if(FAILED(hr)){goto Cleanup;}
	hr = pEnum->Next(1,&var,&nFetch);

	while(hr == S_OK)
	{
		if(nFetch==1)
		{
			if(VT_DISPATCH != V_VT(&var))
			{
				goto Cleanup;
		}
		
			pDisp = V_DISPATCH(&var);
			hr = pDisp->QueryInterface(IID_IADsAccessControlEntry,(void**)&pACE);
		
			if(SUCCEEDED(hr))
			{
				lpszMask = L"Trustee: %s";
				hr = pACE->get_Trustee(&bstrValue);
				nLength = wcslen(lpszMask) + wcslen(bstrValue) + 1;
				lpszOutput = new WCHAR[nLength];
				swprintf(lpszOutput,lpszMask,bstrValue);
				printf(lpszOutput);
				delete [] lpszOutput;
				SysFreeString(bstrValue);
			
				pACE->Release();
				pACE = NULL;
				pDisp->Release();
				pDisp = NULL;
		}	 
		
			VariantClear(&var);
	}	 
		hr = pEnum->Next(1,&var,&nFetch);
}

Cleanup:
	if(pDisp) pDisp->Release();
	if(pACL) pACL->Release();
	if(pACE) pACE->Release();
	if(pEnum) pEnum->Release();
	if(pUnk) pUnk->Release();
	if(szValue) SysFreeString(szValue);
	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

IADsAccessControlEntry, IADsSecurityDescriptor, Null DACLs and Empty DACLs