CAcl Class
The latest version of this topic can be found at CAcl Class.
This class is a wrapper for an ACL (access-control list) structure.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
class CAcl
Members
Public Typedefs
| Name | Description |
|---|---|
| CAcl::CAccessMaskArray | An array of ACCESS_MASKs. |
| CAcl::CAceFlagArray | An array of BYTEs. |
| CAcl::CAceTypeArray | An array of BYTEs. |
Public Constructors
| Name | Description |
|---|---|
| CAcl::CAcl | The constructor. |
| CAcl::~CAcl | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CAcl::GetAceCount | Returns the number of access-control entry (ACE) objects. |
| CAcl::GetAclEntries | Retrieves the access-control list (ACL) entries from the CAcl object. |
| CAcl::GetAclEntry | Retrieves all of the information about an entry in a CAcl object. |
| CAcl::GetLength | Returns the length of the ACL. |
| CAcl::GetPACL | Returns a PACL (pointer to an ACL). |
| CAcl::IsEmpty | Tests the CAcl object for entries. |
| CAcl::IsNull | Returns the status of the CAcl object. |
| CAcl::RemoveAce | Removes a specific ACE (access-control entry) from the CAcl object. |
| CAcl::RemoveAces | Removes all ACEs (access-control entries) from the CAcl that apply to the given CSid. |
| CAcl::SetEmpty | Marks the CAcl object as empty. |
| CAcl::SetNull | Marks the CAcl object as NULL. |
Public Operators
| Name | Description |
|---|---|
| CAcl::operator const ACL * | Casts a CAcl object to an ACL structure. |
| CAcl::operator = | Assignment operator. |
Remarks
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.
Requirements
Header: atlsecurity.h
CAcl::CAccessMaskArray
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).
CAcl::CAceFlagArray
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.
CAcl::CAceTypeArray
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.
CAcl::CAcl
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.
CAcl::~CAcl
The destructor.
virtual ~CAcl() throw();
Remarks
The destructor frees any resources acquired by the object.
CAcl::GetAceCount
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.
CAcl::GetAclEntries
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.
CAcl::GetAclEntry
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.
CAcl::GetLength
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.
CAcl::GetPACL
Returns a pointer to an access-control list (ACL).
const ACL* GetPACL() const throw(...);
Return Value
Returns a pointer to the ACL structure.
CAcl::IsEmpty
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.
CAcl::IsNull
Returns the status of the CAcl object.
bool IsNull() const throw();
Return Value
Returns true if the CAcl object is NULL, false otherwise.
CAcl::operator const ACL *
Casts a CAcl object to an ACL (access-control list) structure.
operator const ACL *() const throw(...);
Remarks
Returns the address of the ACL structure.
CAcl::operator =
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.
CAcl::RemoveAce
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.
CAcl::RemoveAces
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.
CAcl::SetEmpty
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.
CAcl::SetNull
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.