CreateDACL() [2/3]

AutoACL Chusov::Win32::Security::CreateDACL	(	const allowed_ace_container_t &	refAccessAllowedACEs,
		const denied_ace_container_t &	refAccessDeniedACEs,
		DWORD	dwAclRevision = ACL_REVISION
	)

Creates a discretionary access control list (DACL) from two sequences of access-allowed and access-denied access control entries represented as C++ containers.

Template Parameters

allowed_ace_container_t	is a type of a container holding access-allowed control entries. The entries themselves can be specified either as a raw pointer to the native ACCESS_ALLOWED_ACE representation, or as a managed pointer to the one (such as standard C++11 smart pointers or inheritors of thereof), or as an ACCESS_ALLOWED_ACE_INFO higher-level representation of the access-allowed control entries.
denied_ace_container_t	is a type of a container of access-denied control entries. Likewise, the elements of the container can be either raw or smart pointers to native ACCESS_DENIED_ACE representation, or be objects of the ACCESS_DENIED_ACE_INFO type.

Parameters

refAccessAllowedACEs	is a reference to a container, of the allowed_ace_container_t type, holding a set of access-allowed control entries to be included into the created DACL.
refAccessDeniedACEs	is a reference to a container, of the denied_ace_container_t type, holding a set of access-denied control entries for the DACL.
dwAclRevision	is a revision level of the ACL object being created. See InitializeAcl for the proper values of the parameter.

Returns

The function returns a smart pointer to a newly created DACL, described by the [ACL] Windows API structure. If no access-control entries were supplied to the function through the refAccessAllowedACEs or refAccessDeniedACEs containers, the function returns an empty DACL, which prohibits any principal from any access to an object, the DACL is assigned to.

The function returns a smart AutoACL pointer wrapped around a raw pointer of native PACL type to the created DACL allocated by the function. The AutoACL class is an inheritor of the std::unique_ptr.

The function creates a DACL from given sets of access-control entries to be included to the list. The sets are represented as the allowed_ace_container_t and denied_ace_container_t container types must adhere the rules of the [C++ Container concept]. The values of the containers can be of any supported type representing either low-level details expressed as ACCESS_ALLOWED_ACE and ACCESS_DENIED_ACE native Windows elements or higher-level names (of the principal) and access-control bit masks as specified for the ACCESS_ALLOWED_ACE_INFO and ACCESS_DENIED_ACE_INFO types.

If the access-control entries are represented as managed pointers, the class of the latter must have element_type alias for the type of value pointed to and implement the standard dereferencing operators (i.e. operator*()const; and operator->()const;).

In the created DACL the access-denied access-control entries precede the the access-allowed one, as required by Windows. The orders of the access-allowed control entries and of the access-denied control entries are preserved for the DACL.

Remarks

If both containers, passed to the function, are empty, the function returns an empty DACL, which prohibits any principal from any access to an object, which the DACL is assigned to. See "Null DACLs and Empty DACLs".

Exceptions

std::bad_alloc	The function was unable to allocate a required amount of memory to complete the request.
Chusov::Exceptions::ArithmeticOverflowException	A size, in bytes, of the DACL to be allocated must fit 32 bits (as specified by DWORD values), but it does not.
Chusov::Exceptions::ChsvCodeException	System-level error occurred.

See also

CreateDACL(AllowedInputIterator, AllowedInputIterator, DeniedInputIterator, DeniedInputIterator, DWORD dwAclRevision); creates a DACL from ACEs, given by ranges, specified as iterator-based half-intervals;
CreateDACL(const std::initializer_list<ACCESS_ALLOWED_ACE_INFO>& refAccessAllowedACEs, const std::initializer_list<ACCESS_DENIED_ACE_INFO>& refAccessDeniedACEs, DWORD dwAclRevision); creates a DACL from initializer lists containing ACEs, specified only by principal names and corresponding access control masks.