CDacl Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CDacl Class.

This class is a wrapper for a DACL (discretionary 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 CDacl : public CAcl

Public Constructors

NameDescription
CDacl::CDaclThe constructor.
CDacl::~CDaclThe destructor.

Public Methods

NameDescription
CDacl::AddAllowedAceAdds an allowed ACE (access-control entry) to the CDacl object.
CDacl::AddDeniedAceAdds a denied ACE to the CDacl object.
CDacl::GetAceCountReturns the number of ACEs (access-control entries) in the CDacl object.
CDacl::RemoveAceRemoves a specific ACE (access-control entry) from the CDacl object.
CDacl::RemoveAllAcesRemoves all of the ACEs contained in the CDacl object.

Public Operators

NameDescription
CDacl::operator =Assignment operator.

An object's security descriptor can contain a DACL. A DACL contains zero or more ACEs (access-control entries) that identify the users and groups who can access the object. If a DACL is empty (that is, it contains zero ACEs), no access is explicitly granted, so access is implicitly denied. However, if an object's security descriptor does not have a DACL, the object is unprotected and everyone has complete access.

To retrieve an object's DACL, you must be the object's owner or have READ_CONTROL access to the object. To change an object's DACL, you must have WRITE_DAC access to the object.

Use the class methods provided to create, add, remove, and delete ACEs from the CDacl object. See also AtlGetDacl and AtlSetDacl.

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

CAcl

CDacl

Header: atlsecurity.h

Adds an allowed ACE (access-control entry) to the CDacl object.

bool AddAllowedAce(  
    const CSid& rSid,
    ACCESS_MASK AccessMask,
    BYTE AceFlags = 0) throw(...);

bool AddAllowedAce(  
    const CSid& rSid,
    ACCESS_MASK AccessMask,
    BYTE AceFlags,
    const GUID* pObjectType,
    const GUID* pInheritedObjectType) throw(...);

Parameters

rSid
A CSid object.

AccessMask
Specifies the mask of access rights to be allowed for the specified CSid object.

AceFlags
A set of bit flags that control ACE inheritance.

pObjectType
The object type.

pInheritedObjectType
The inherited object type.

Return Value

Returns true if the ACE is added to the CDacl object, false on failure.

Remarks

A CDacl object contains zero or more ACEs (access-control entries) that identify the users and groups who can access the object. This method adds an ACE that allows access to the CDacl object.

System_CAPS_ICON_note.jpg Note

The second form of AddAllowedAce is only available on Windows 2000 and later.

See ACE_HEADER for a description of the various flags which can be set in the AceFlags parameter.

Adds a denied ACE (access-control entry) to the CDacl object.

bool AddDeniedAce(  
    const CSid& rSid,
    ACCESS_MASK AccessMask,
    BYTE AceFlags = 0) throw(...);

bool AddDeniedAce(
    const CSid& rSid,
    ACCESS_MASK AccessMask,
    BYTE AceFlags,
    const GUID* pObjectType,
    const GUID* pInheritedObjectType) throw(...);

Parameters

rSid
A CSid object.

AccessMask
Specifies the mask of access rights to be denied for the specified CSid object.

AceFlags
A set of bit flags that control ACE inheritance. Defaults to 0 in the first form of the method.

pObjectType
The object type.

pInheritedObjectType
The inherited object type.

Return Value

Returns true if the ACE is added to the CDacl object, false on failure.

Remarks

A CDacl object contains zero or more ACEs (access-control entries) that identify the users and groups who can access the object. This method adds an ACE that denies access to the CDacl object.

System_CAPS_ICON_note.jpg Note

The second form of AddDeniedAce is only available on Windows 2000 and later.

See ACE_HEADER for a description of the various flags which can be set in the AceFlags parameter.

The constructor.

CDacl (const ACL& rhs) throw(...);  
CDacl () throw();

Parameters

rhs
An existing ACL (access-control list) structure.

Remarks

The CDacl object can be optionally created using an existing ACL structure. It is important to note that only a DACL (discretionary access-control list), and not a SACL (system access-control list), should be passed as this parameter. In debug builds, passing a SACL will cause an ASSERT. In release builds, passing a SACL will cause the ACEs (access-control entries) in the ACL to be ignored, and no error will occur.

The destructor.

~CDacl () throw();

Remarks

The destructor frees any resources acquired by the object, including all ACEs (access-control entries) using CDacl::RemoveAllAces.

Returns the number of ACEs (access-control entries) in the CDacl object.

UINT GetAceCount() const throw();

Return Value

Returns the number of ACEs contained in the CDacl object.

Assignment operator.

CDacl& operator= (const ACL& rhs) throw(...);

Parameters

rhs
The ACL (access-control list) to assign to the existing object.

Return Value

Returns a reference to the updated CDacl object.

Remarks

You should ensure that you only pass a DACL (discretionary access-control list) to this function. Passing a SACL (system access-control list) to this function will cause an ASSERT in debug builds but will cause no error in release builds.

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

void RemoveAce(UINT nIndex) throw();

Parameters

nIndex
Index to the ACE entry to remove.

Remarks

This method is derived from CAtlArray::RemoveAt.

Removes all of the ACEs (access-control entries) contained in the CDacl object.

void RemoveAllAces() throw();

Remarks

Removes every ACE (access-control entry) structure (if any) in the CDacl object.

Security Sample
CAcl Class
ACLs
ACEs
Class Overview
Security Global Functions

Show: