Export (0) Print
Expand All
Expand Minimize

InitializeAcl function

The InitializeAcl function initializes a new ACL structure.

Syntax


BOOL WINAPI InitializeAcl(
  _Out_  PACL pAcl,
  _In_   DWORD nAclLength,
  _In_   DWORD dwAclRevision
);

Parameters

pAcl [out]

A pointer to an ACL structure to be initialized by this function. Allocate memory for pAcl before calling this function.

nAclLength [in]

The length, in bytes, of the buffer pointed to by the pAcl parameter. This value must be large enough to contain the ACL header and all of the access control entries (ACEs) to be stored in the ACL. In addition, this value must be DWORD-aligned. For more information about calculating the size of an ACL, see Remarks.

dwAclRevision [in]

The revision level of the ACL structure being created. This value can be ACL_REVISION or ACL_REVISION_DS. Use ACL_REVISION_DS if the access control list (ACL) supports object-specific ACEs.

Return value

If the function succeeds, the function returns nonzero.

If the function fails, it returns zero. To get extended error information, call GetLastError.

Remarks

The InitializeAcl function creates an empty ACL structure; the ACL contains no ACEs. Applying an empty ACL to an object denies all access to that object.

The initial size of the ACL depends on the number of ACEs you plan to add to the ACL before you use it. For example, if the ACL is to contain an ACE for a user and group, you would initialize the ACL based on two ACEs. For details about modifying an existing ACL, see Modifying the ACLs of an Object.

To calculate the initial size of an ACL, add the following together, and then align the result to the nearest DWORD:

  • Size of the ACL structure.
  • Size of each ACE structure that the ACL is to contain minus the SidStart member (DWORD) of the ACE.
  • Length of the SID that each ACE is to contain.

Examples

The following example calls the InitializeAcl function. The size of the ACL is based on three allow-access ACEs. As an option, you can use security descriptor definition language (SDDL) to create the ACL. For details, see Creating a DACL.

The example also omits a step for simplification. For more information, see the Taking Object Ownership example. You must call the FreeSid function at the end of the example code due to calling the AllocateAndInitializeSid function.


#include <windows.h>
#include <Winbase.h>
#pragma comment(lib, "duser.lib")

#define NUM_OF_ACES 3

void main()
{
    PACL pAcl = NULL;
    DWORD cbAcl = 0;
    PSID psids[NUM_OF_ACES];

    // Allocate and initialize SIDs.
    // Step omitted - See Taking Object Ownership example.

    // Add the SID for each ACE to psids. 
    cbAcl = sizeof(ACL) + 
        ((sizeof(ACCESS_ALLOWED_ACE)) * NUM_OF_ACES);
    for (int i = 0; i < NUM_OF_ACES; i++)
    {
        cbAcl += GetLengthSid(psids[i]) - sizeof(DWORD);
    }

    // Align cbAcl to a DWORD.
    cbAcl = (cbAcl + (sizeof(DWORD) - 1)) & 0xfffffffc;

    pAcl = (ACL*)LocalAlloc(LPTR, cbAcl);
    if (pAcl)
    {
        if (InitializeAcl(pAcl, cbAcl, ACL_REVISION))
        {

            // Add the ACEs to the ACL.
            // Add the ACL to the object's security descriptor.
        }
        else
        {

            // Handle error.
        }
    }
    {

        // Handle error.
    }

    // Free pAcl when finished.
    // Call FreeSid when finished.
}


Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winbase.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

See also

Low-level Access Control
Low-level Access Control Functions
ACCESS_ALLOWED_ACE
ACCESS_DENIED_ACE
ACL
AddAccessAllowedAce
AddAccessDeniedAce
AddAce
AddAuditAccessAce
DeleteAce
GetAce
GetAclInformation
IsValidAcl
SetAclInformation
SID

 

 

Community Additions

ADD
Show:
© 2014 Microsoft