CreateSecurityDescriptor() [2/4]

AutoSecurityDescriptor Chusov::Win32::Security::CreateSecurityDescriptor	(	LPCWSTR	pszOwnerName,
		LPCWSTR	pszGroupName,
		const allowed_ace_container_t &	refAccessAllowedACEs,
		const denied_ace_container_t &	refAccessDeniedACEs
	)

Allocates and constructs a self-relative security descriptor from its three components: an owner, a group and a discretionary access control list (DACL). The owner and the group are specified by respective principal names with optional domain names, which the principals belong to. The DACL is passed to the function as a pair of sets of access-allowed and access-denied access control entries (ACEs) within two corresponding containers of ACCESS_ALLOWED_ACE_INFO objects and of ACCESS_DENIED_ACE_INFO objects.

Template Parameters

allowed_ace_container_t	is a type of the container of access-allowed ACEs, passed to the function as a parameter. See details for the requirements for the container type.
denied_ace_container_t	is a type of the container of access-denied ACEs, passed to the function as parameters. See details for the requirements for the container type.

Parameters

[in]	pszOwnerName	is an optional pointer to a zero-terminated wide string specifying a name of a principal to be included into the created security descriptor as its owner. The name can include an optional domain name, which the principal belongs to. A principal name qualified with the domain name should be specified as "domain_name\user_name". If the domain name is omitted, a security identifier of the principal is sought in the current system domain. If the pszOwnerName is NULL, the created security descriptor will not have an owner.
[in]	pszGroupName	is an optional pointer to a zero-terminated wide string specifying a name of a principal, that is associated with a group, to be included into the created security descriptor as its group. The name can include an optional domain name, which the principal belongs to. A principal name qualified with the corresponding domain name should be specified as "domain_name\user_name". If the domain name is omitted, a security identifier of the principal is sought in the current system domain. If the pszGroupName is NULL, the created security descriptor will not have a group.
	refAccessAllowedACEs	is a reference to a container, of the allowed_ace_container_t type, holding a set of ACCESS_ALLOWED_ACE_INFO objects.
	refAccessDeniedACEs	is a reference to a container, of the denied_ace_container_t type, holding a set of ACCESS_DENIED_ACE_INFO objects.

Returns

The function returns a smart AutoSecurityDescriptor pointer to the created self-relative security descriptor.

Each pointer to the names, which are zero-terminated wide strings, is optional. A NULL pointer to an owner name causes the function to create a security descriptor without an owner. Consequently, a NULL pointer to a group name causes the function to create security descriptor without a group.

There is no way to create a security descriptor without a DACL, because if both containers are empty, the function assigns an empty (but valid) DACL to the returned security descriptor. Such descriptor will prohibit anyone from accessing the object, which the created security descriptor is assigned to. To create an empty security descriptor use the CreateSecurityDescriptor overloaded function, for which pOwner and pGroup can be retrieved by calling the GetSidByPrincipalName function.

A revision of the created DACL corresponds to ACL_REVISION constant. See InitializeAcl for more detailed information.

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.