CreateAccessAllowedACE() [2/2]

AutoAccessAllowedACE Chusov::Win32::Security::CreateAccessAllowedACE	(	PSID	pSid,
		DWORD	dwAccessMask
	)

A wrap over the CreateACE<ACCESS_ALLOWED_ACE_TYPE>(PSID pSid, DWORD dwAccessMask) template specialization, that creates an access-allowed ACE by the given principal specified as a native security identifier and a corresponding combination (bit mask) of Windows API access control values. .

Parameters

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 CreateAccessAllowedACE function, that receives an ACCESS_ALLOWED_ACE_INFO structure as its parameter, specifying a principal name and an access mask directly.

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 the AutoAccessAllowedACE type to the created ACE of ACCESS_ALLOWED_ACE type. The returned value points to data with the SID, partially occupying a space that contiguously follows the fields described by the ACCESS_ALLOWED_ACE structure.

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

CreateAccessDeniedACE - a function creating access-denied ACEs from a SID and an access-control mask;
CreateACE - a function template creating an ACE of type that depends upon a template parameter;
CreateAccessAllowedACE - an overload creating an access-allowed ACE from a name of a principal and from corresponding access-control mask.