Platform SDK: Active Directory, ADSI, and Directory Services

IADsAccessControlList::AddAce

The IADsAccessControlList::AddAce method adds one or more access control entries (ACEs) to the access-control list (ACL).

HRESULT AddAce(
  IDispatch * pAccessControlEntry  
);

Parameters

[in] pAccessControlEntry: Array of ACEs to be added to the ACL. Cannot be NULL.

Return Values

This method returns the standard return values, as well as the following:

S_OK: The ACE was added successfully.
E_OUTOFMEMORY: No memory can be allocated for the new ACEs.
E_FAIL: The operation has failed.
E_INVALIDARG: The supplied argument is not valid.

For other return values, see ADSI Error Codes.

Example Code [Visual Basic]

The following Visual Basic® code snippet illustrates how to use the IADsAccessControlList::AddAce method to add two ACEs to an ACL.

Dim Ace1 as new IADsAccessControlEntry
Dim Ace2 As new IADsAccessControlEntry
Dim Dacl as new IADsAccessControlList
' Add the ACEs to the Disretionary ACL
 
Dacl.AclRevision = ADS_SD_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

Example Code [C++]

The following C++ code snippet 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(ADS_SD_REVISION_DS);
    if(FAILED(hr)) return hr;

    IADsAccessControlEntry *pAce; 
    pAce = createAce(-1,                    // full permissions
                     ADS_ACETYPE_ACCESS_ALLOWED,
                     ADS_ACEFLAG_INHERIT_ACE,
                     L"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(FAILED(hr)) return hr;

    printf("Ace has been added to ACL.\n");
    if(pAce) pAce->Release();

    return S_OK;
}
////////////////////////////////////
// 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