CreateDACL() [1/3]

AutoACL Chusov::Win32::Security::CreateDACL	(	AllowedInputIterator	itAccessAllowedACEsBegin,
		AllowedInputIterator	itAccessAllowedACEsEnd,
		DeniedInputIterator	itAccessDeniedACEsBegin,
		DeniedInputIterator	itAccessDeniedACEsEnd,
		DWORD	dwAclRevision = ACL_REVISION
	)

Creates a discretionary access control list (DACL) from two sequences of access-allowed and access-denied access control entries. Each sequence is given as a range with inclusive start position and exclusive ending one.

Template Parameters

AllowedInputIterator

is a type of an input iterator, specifying a range within a container of access-allowed ACEs. The access control entries 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.

DeniedInputIterator

is a type of an input iterator, specifying a range within a container of access-denied ACEs. The ones can also be specified as raw pointers to the native ACCESS_DENIED_ACE representation, as managed pointers or as a higher level ACCESS_DENIED_ACE_INFO representation.

Parameters

itAccessAllowedACEsBegin	is at least an input iterator, bound with the first ACE within the range of access-allowed control entries to be added to the DACL.
itAccessAllowedACEsEnd	is at least an input iterator, bound with the first element, either existent or not, outside the range of access-allowed ACEs. I.e. the range of access-allowed ACEs is given by a half-interval [itAccessAllowedACEsBegin, itAccessAllowedACEsEnd).
itAccessDeniedACEsBegin	is at least an input iterator, bound with the first ACE within the range of access-denied control entries to be added to the DACL.
itAccessDeniedACEsEnd	is at least an input iterator, bound with the first element, either existent or not, outside the range of access-denied ACEs. I.e. the range of access-denied ACEs is given by a half-interval [itAccessDeniedACEsBegin, itAccessDeniedACEsEnd).
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 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 the given ranges of access-control entries to be included to the list. The ranges are specified as bounding iterators, which are at least input iterators. The value held by an iterator can be of any supported type representing a low-level details expressed as ACCESS_ALLOWED_ACE and ACCESS_DENIED_ACE native Windows elements or by a name (of the principal) and a corresponding access-control bitmask 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 ranges, 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(const allowed_ace_container_t& refAccessAllowedACEs, const denied_ace_container_t& refAccessDeniedACEs, DWORD dwAclRevision); creates a DACL from ACEs, held within containers;
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.

Examples

chsvwinutilex\CreateDACL.cpp.