CreateACE() [2/2]

AutoACE<ACE_TYPE_ID> Chusov::Win32::Security::CreateACE	(	PSID	pSid,
		DWORD	dwAccessMask
	)

Creates an access control entry to be used in an access control list. .

Template Parameters

ACE_TYPE_ID

is an integer constant, of value of either ACCESS_ALLOWED_ACE_TYPE or ACCESS_DENIED_ACE_TYPE, specifying a type of an access control entry being created, which is an access-allowed ACE or an access-denied ACE respectively. See ACE_INFO class template.

Parameters

[in]	pSid	is a pointer to a security identifier (SID) of a principal, the ACE is created for. To acquire a SID value use functions like GetSidByPrincipalName, GetTokenUser or functions defined in Win32 API, like LookupAccountName. Also, the one can use the overload of the CreateACE function, that receives an ACE_INFO structure as its parameter, specifying a principal name and an access mask directly.
[in]	dwAccessMask	is an access mask specified for the created ACE. The parameter receives a combination of standard Windows access control values, which can be object-specific (e.g. File access rights or Process access rights), Standard, Generic or a combination of thereof.

Returns

The function returns a smart pointer of type AutoACE<ACE_TYPE_ID> to the created ACE of either ACCESS_ALLOWED_ACE or ACCESS_DENIED_ACE type, depending on a value of the ACE_TYPE_ID template parameter. The returned value points to data of either of these types with the SID, partially occupying a space that contiguously follows the fields described by the structures.

Exceptions

std::bad_alloc	Could not allocate a sufficient amount of memory to complete the request.
Chusov::Exceptions::InvalidParameterException	A parameter has an invalid value.
Chusov::Exceptions::ChsvCodeException	a system-level error occurred. If an invalid SID was specified, the function throws an exception corresponding to the ERROR_INVALID_SID Windows error code.

See also

CreateAccessAllowedACE - a specialization for creating access-allowed ACEs;
CreateAccessDeniedACE - a specialization for creating access-denied ACEs;
CreateACE - an overload receiving higher-level representations of ACEs, that are described by the ACE_INFO template.