ConvertSecurityDescriptorToAccess

[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
);
 

Parameters

hObject

A handle to the object associated with the pSecDescriptor security descriptor. The function uses the handle to retrieve display names for the GUIDs in any object-specific ACEs. If this handle is NULL, the returned access-control structures contain the GUIDs in string format rather than the display names of the objects associated with the GUIDs.

If the ACLs in the security descriptor do not contain object specific ACEs, the hObject and ObjectType parameters are ignored.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object identified by the hObject parameter.

pSecDescriptor

Pointer to the security descriptor from which to retrieve security information.

ppAccessList

Pointer to a variable that receives a pointer to an ACTRL_ACCESS structure that describes the security descriptor's DACL. This parameter can be NULL if you do not need the DACL information. Call the LocalFree function to free the returned buffer.

ppAuditList

Pointer to a variable that receives a pointer to an ACTRL_AUDIT structure that describes the security descriptor's SACL. This parameter can be NULL if you do not need the SACL information. Call the LocalFree function to free the returned buffer.

lppOwner

Pointer to a variable that receives a pointer to a null-terminated string containing the name of the object's owner. This parameter can be NULL if you do not need the information. Call the LocalFree function to free the returned buffer.

lppGroup

Pointer to a variable that receives a pointer to a null-terminated string containing the name of the object's primary group. This parameter can be NULL if you do not need the information. Call the LocalFree function to free the returned buffer.

Return Values

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.

QuickInfo

  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.

See Also

Access Control Overview, Access Control Functions, ACTRL_ACCESS, ACTRL_AUDIT, ConvertAccessToSecurityDescriptor, ConvertSecurityDescriptorToAccessNamed, LocalFree