CAcl Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CAcl Class on docs.microsoft.com. This class is a wrapper for an ACL (access-control list) structure.

System_CAPS_ICON_important.jpg Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

class CAcl

Public Typedefs

NameDescription
CAcl::CAccessMaskArrayAn array of ACCESS_MASKs.
CAcl::CAceFlagArrayAn array of BYTEs.
CAcl::CAceTypeArrayAn array of BYTEs.

Public Constructors

NameDescription
CAcl::CAclThe constructor.
CAcl::~CAclThe destructor.

Public Methods

NameDescription
CAcl::GetAceCountReturns the number of access-control entry (ACE) objects.
CAcl::GetAclEntriesRetrieves the access-control list (ACL) entries from the CAcl object.
CAcl::GetAclEntryRetrieves all of the information about an entry in a CAcl object.
CAcl::GetLengthReturns the length of the ACL.
CAcl::GetPACLReturns a PACL (pointer to an ACL).
CAcl::IsEmptyTests the CAcl object for entries.
CAcl::IsNullReturns the status of the CAcl object.
CAcl::RemoveAceRemoves a specific ACE (access-control entry) from the CAcl object.
CAcl::RemoveAcesRemoves all ACEs (access-control entries) from the CAcl that apply to the given CSid.
CAcl::SetEmptyMarks the CAcl object as empty.
CAcl::SetNullMarks the CAcl object as NULL.

Public Operators

NameDescription
CAcl::operator const ACL *Casts a CAcl object to an ACL structure.
CAcl::operator =Assignment operator.

The ACL structure is the header of an ACL (access-control list). An ACL includes a sequential list of zero or more ACEs (access-control entries). The individual ACEs in an ACL are numbered from 0 to n-1, where n is the number of ACEs in the ACL. When editing an ACL, an application refers to an access-control entry (ACE) within the ACL by its index.

There are two ACL types:

  • Discretionary

  • System

A discretionary ACL is controlled by the owner of an object or anyone granted WRITE_DAC access to the object. It specifies the access particular users and groups can have to an object. For example, the owner of a file can use a discretionary ACL to control which users and groups can and cannot have access to the file.

An object can also have system-level security information associated with it, in the form of a system ACL controlled by a system administrator. A system ACL can allow the system administrator to audit any attempts to gain access to an object.

For more details, see the ACL discussion in the Windows SDK.

For an introduction to the access control model in Windows, see Access Control in the Windows SDK.

Header: atlsecurity.h

An array of ACCESS_MASK objects.

typedef CAtlArray<ACCESS_MASK> CAccessMaskArray;

Remarks

This typedef specifies the array type that can be used to store access rights used in access-control entries (ACEs).

An array of BYTEs.

typedef CAtlArray<BYTE> CAceFlagArray;

Remarks

This typedef specifies the array type used to define the access-control entry (ACE) type-specific control flags. See the ACE_HEADER definition for the complete list of possible flags.

An array of BYTEs.

typedef CAtlArray<BYTE> CAceTypeArray;

Remarks

This typedef specifies the array type used to define the nature of the access-control entry (ACE) objects, such as ACCESS_ALLOWED_ACE_TYPE or ACCESS_DENIED_ACE_TYPE. See the ACE_HEADER definition for the complete list of possible types.

The constructor.

CAcl() throw();
CAcl(const CAcl& rhs) throw(...);

Parameters

rhs
An existing CAcl object.

Remarks

The CAcl object can be optionally created using an existing CAcl object.

The destructor.

virtual ~CAcl() throw();

Remarks

The destructor frees any resources acquired by the object.

Returns the number of access-control entry (ACE) objects.

virtual UINT GetAceCount() const throw() = 0;

Return Value

Returns the number of ACE entries in the CAcl object.

Retrieves the access-control list (ACL) entries from the CAcl object.

void GetAclEntries(
    CSid::CSidArray* pSids,
    CAccessMaskArray* pAccessMasks = NULL,
    CAceTypeArray* pAceTypes = NULL,
    CAceFlagArray* pAceFlags = NULL) const throw(...);

Parameters

pSids
A pointer to an array of CSid objects.

pAccessMasks
The access masks.

pAceTypes
The access-control entry ( ACE) types.

pAceFlags
The ACE flags.

Remarks

This method fills the array parameters with the details of every ACE object contained in the CAcl object. Use NULL when the details for that particular array are not required.

The contents of each array correspond to each other, that is, the first element of the CAccessMaskArray array corresponds to the first element in the CSidArray array, and so on.

See ACE_HEADER for more details on ACE types and flags.

Retrieves all of the information about an entry in an access-control list (ACL).

void GetAclEntry(
    UINT nIndex,
    CSid* pSid,
    ACCESS_MASK* pMask = NULL,
    BYTE* pType = NULL,
    BYTE* pFlags = NULL,
    GUID* pObjectType = NULL,
    GUID* pInheritedObjectType = NULL) const throw(...);

Parameters

nIndex
Index to the ACL entry to retrieve.

pSid
The CSid object to which the ACL entry applies.

pMask
The mask specifying permissions to grant or deny access.

pType
The ACE type.

pFlags
The ACE flags.

pObjectType
The object type. This will be set to GUID_NULL if the object type is not specified in the ACE, or if the ACE is not an OBJECT ACE.

pInheritedObjectType
The inherited object type. This will be set to GUID_NULL if the inherited object type is not specified in the ACE, or if the ACE is not an OBJECT ACE.

Remarks

This method will retrieve all of the information about an individual ACE, providing more information than CAcl::GetAclEntries alone makes available.

See ACE_HEADER for more details on ACE types and flags.

Returns the length of the access-control list (ACL).

UINT GetLength() const throw();

Return Value

Returns the required length in bytes necessary to hold the ACL structure.

Returns a pointer to an access-control list (ACL).

const ACL* GetPACL() const throw(...);

Return Value

Returns a pointer to the ACL structure.

Tests the CAcl object for entries.

bool IsEmpty() const throw();

Remarks

Returns true if the CAcl object is not NULL, and contains no entries. Returns false if the CAcl object is either NULL, or contains at least one entry.

Returns the status of the CAcl object.

bool IsNull() const throw();

Return Value

Returns true if the CAcl object is NULL, false otherwise.

Casts a CAcl object to an ACL (access-control list) structure.

operator const ACL *() const throw(...);

Remarks

Returns the address of the ACL structure.

Assignment operator.

CAcl& operator= (const CAcl& rhs) throw(...);

Parameters

rhs
The CAcl to assign to the existing object.

Return Value

Returns a reference to the updated CAcl object.

Removes a specific ACE (access-control entry) from the CAcl object.

void RemoveAce(UINT nIndex) throw();

Parameters

nIndex
Index to the ACE entry to remove.

Remarks

This method is derived from CAtlArray::RemoveAt.

Removes alls ACEs (access-control entries) from the CAcl that apply to the given CSid.

bool RemoveAces(const CSid& rSid) throw(...)

Parameters

rSid
A reference to a CSid object.

Marks the CAcl object as empty.

void SetEmpty() throw();

Remarks

The CAcl can be set to empty or to NULL: the two states are distinct.

Marks the CAcl object as NULL.

void SetNull() throw();

Remarks

The CAcl can be set to empty or to NULL: the two states are distinct.

Class Overview
Security Global Functions

Show: