[This is preliminary documentation and subject to change.]
The ConvertSecurityDescriptorToAccess function retrieves the security information from a specified security descriptor. The function converts the security descriptor's SIDs and ACLs into name strings and data structures that you can use with the access-control functions introduced for Windows NT version 5.0.
For security descriptors that contain object-specific ACEs, you can specify the handle and type of the object associated with the security descriptor. The function uses the handle to retrieve display names for the GUIDs in any object-specific ACEs.
DWORD ConvertSecurityDescriptorToAccess(
HANDLE hObject, // handle to the associated object
SE_OBJECT_TYPE ObjectType, // type of object
PSECURITY_DESCRIPTOR pSecDescriptor,
// pointer to a security descriptor
PACTRL_ACCESS *ppAccessList,
// receives a pointer to access-control info
PACTRL_AUDIT *ppAuditList,
// receives a pointer to audit-control info
LPTSTR *lppOwner, // receives the name of the object's owner
LPTSTR *lppGroup // receives the name of the object's primary group
);
If the ACLs in the security descriptor do not contain object specific ACEs, the hObject and ObjectType parameters are ignored.
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value can be one of the following error codes.
Value | Meaning |
---|---|
ERROR_NOT_ENOUGH_MEMORY | A memory allocation failed. |
ERROR_INVALID_PARAMETER | An invalid parameter was specified. |
Windows NT: Requires version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in aclapi.h.
Import Library: Use advapi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.
Access Control Overview, Access Control Functions, ACTRL_ACCESS, ACTRL_AUDIT, ConvertAccessToSecurityDescriptor, ConvertSecurityDescriptorToAccessNamed, LocalFree