ConvertSecurityDescriptorToAccessNamed

[This is preliminary documentation and subject to change.]

The ConvertSecurityDescriptorToAccessNamed 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 name and type of the object associated with the security descriptor. The function uses the object's name to retrieve display names for the GUIDs in any object-specific ACEs.

DWORD ConvertSecurityDescriptorToAccessNamed(
  LPCTSTR lpObject,           // name of the associated object
  SE_OBJECT_TYPE ObjectType,  // type of object
  PSECURITY_DESCRIPTOR pSecDescriptor,
                    // pointer to the object's 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

lpObject

Pointer to a null-terminated string that specifies the name of the object associated with the pSecDescriptor security descriptor. For descriptions of the string formats for the different object types, see SE_OBJECT_TYPE.

The function accesses the object to retrieve display names for the GUIDs in any object-specific ACEs. If lpObject 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 lpObject and ObjectType parameters are ignored.

ObjectType

Specifies a value from the SE_OBJECT_TYPE enumeration that indicates the type of object identified by the lpObject 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. Call the LocalFree function to free the returned buffer. This parameter can be NULL if you do not need the DACL information.

ppAuditList

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

lppOwner

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

lppGroup

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

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, ConvertSecurityDescriptorToAccess, LocalFree