Directory Services

IADsAccessControlList::AddAce

The IADsAccessControlList::AddAce method adds an IADsAccessControlEntry object to the IADsAccessControlList object.

HRESULT AddAce( 
  IDispatch* pAccessControlEntry
);

Parameters

pAccessControlEntry
[in] Pointer to the IDispatch interface of the IADsAccessControlEntry object to be added. This parameter cannot be NULL.

Return Values

Returns a standard HRESULT value including the following.
Return Code Description
S_OK The object was added successfully.
E_OUTOFMEMORY A memory allocation failure occurred.

Example Code [Visual Basic]

The following Visual Basic code example shows how to use the IADsAccessControlList::AddAce method to add two ACEs to an ACL.

Const ACL_REVISION_DS = &H4

Dim x as IADs
Dim sd as IADsSecurityDescriptor
Dim Ace1 As new IADsAccessControlEntry
Dim Ace2 As new IADsAccessControlEntry
Dim Dacl As new IADsAccessControlList
On Error GoTo Cleanup

Set x = GetObject("LDAP://OU=Sales,DC=Fabrikam,DC=com")
Set sd = x.Get("ntSecurityDescriptor")

' Add the ACEs to the Disretionary ACL.
 
Dacl.AclRevision = ACL_REVISION_DS 'DS ACL Revision
' Set up the first ACE.
Ace1.AccessMask = -1 'Full Permission (Allowed)
Ace1.AceType = ADS_ACETYPE_ACCESS_ALLOWED
Ace1.AceFlags = ADS_ACEFLAG_INHERIT_ACE
Ace1.Trustee = "myMachine\Administrator"
 
' Set up the 2nd ACE.
Ace2.AccessMask = -1 'Full Permission (Denied)
Ace2.AceType = ADS_ACETYPE_ACCESS_DENIED
Ace2.AceFlags = ADS_ACEFLAG_INHERIT_ACE
Ace2.Trustee = "aDomain\aUser"
 
' Add the ACEs to the Disretionary ACL.
Dacl.AddAce Ace1
Dacl.AddAce Ace2

'Commit the changes. 
sd.DiscretionaryAcl = Dacl
x.Put "ntSecurityDescriptor", Array(sd)
x.SetInfo

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

Example Code [C++]

The following C++ code example adds an ACE to an ACL using the IADsAccessControlList::AddAce method. The added ACE has allowed access rights with the full permission.

HRESULT addAceTo(IADsAccessControlList *pAcl)
{
	if(!pAcl) 
	{
		return E_FAIL;
}

	HRESULT hr = pAcl->put_AclRevision(ACL_REVISION_DS);
	if(FAILED(hr)) 
	{
		return hr;
}

	IADsAccessControlEntry *pAce = NULL; 
	pAce = createAce(-1, 				// Full permissions.
					 ADS_ACETYPE_ACCESS_ALLOWED,
					 ADS_ACEFLAG_INHERIT_ACE,
					 CComBSTR("aDomain\\aUser"));

	if(!pAce)
	{
		return E_FAIL;
}

	IDispatch *pDisp;
	hr = pAce->QueryInterface(IID_IDispatch,(void**)&pDisp);
	if(FAILED(hr)) 
	{
		pAce->Release();
		return hr;
}

	hr = pAcl->AddAce(pDisp);
	pDisp->Release();
	if(pAce) pAce->Release();
	if(FAILED(hr)) 
	{
		return hr;
}

	printf("Ace has been added to ACL.\n");

	return hr;
}

////////////////////////////////////
// function to create an allowed ACE
////////////////////////////////////
IADsAccessControlEntry *createAce(
				 long mask,
				 long type, 
				 long flag,
				 BSTR trustee)
{
	HRESULT hr;
	IADsAccessControlEntry *pAce;
	hr = CoCreateInstance(CLSID_AccessControlEntry,
						NULL,
						CLSCTX_INPROC_SERVER,
						IID_IADsAccessControlEntry,
						(void**)&pAce);
	if(FAILED(hr)) 
	{
		if(pAce) 
		{
			pAce->Release();
	}

		return NULL;
}

	hr = pAce->put_AccessMask(mask); 
	hr = pAce->put_AceType(type);
	hr = pAce->put_AceFlags(flag);
	hr = pAce->put_Trustee(trustee); 

	return pAce;
}

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, IADsAccessControlList