LookupSecurityDescriptorPartsA function (aclapi.h)

Article
02/22/2024

The LookupSecurityDescriptorParts function retrieves security information from a self-relative security descriptor.

Syntax

DWORD LookupSecurityDescriptorPartsA(
  [out, optional] PTRUSTEE_A           *ppOwner,
  [out, optional] PTRUSTEE_A           *ppGroup,
  [out, optional] PULONG               pcCountOfAccessEntries,
  [out, optional] PEXPLICIT_ACCESS_A   *ppListOfAccessEntries,
  [out, optional] PULONG               pcCountOfAuditEntries,
  [out, optional] PEXPLICIT_ACCESS_A   *ppListOfAuditEntries,
  [in]            PSECURITY_DESCRIPTOR pSD
);

Parameters

[out, optional] ppOwner

A pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated with the owner security identifier (SID) in the pSD security descriptor, and returns a pointer to the name in the ptstrName member of the TRUSTEE structure. The function sets the TrusteeForm member to TRUSTEE_IS_NAME.

This parameter can be NULL if you are not interested in the name of the owner.

[out, optional] ppGroup

A pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated with the primary group SID of the security descriptor, and returns a pointer to the name in the ptstrName member of the TRUSTEE structure. The function sets the TrusteeForm member to TRUSTEE_IS_NAME.

This parameter can be NULL if you are not interested in the name of the group.

[out, optional] pcCountOfAccessEntries

A pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the pListOfAccessEntries array. This parameter can be NULL only if the pListOfAccessEntries parameter is also NULL.

[out, optional] ppListOfAccessEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the access control entries (ACEs) in the discretionary access control list (DACL) of the security descriptor. The TRUSTEE structure in these EXPLICIT_ACCESS structures use the TRUSTEE_IS_NAME form. For a description of how an array of EXPLICIT_ACCESS structures describes the ACEs in an access control list (ACL), see the GetExplicitEntriesFromAcl function. If this parameter is NULL, the cCountOfAccessEntries parameter must also be NULL.

[out, optional] pcCountOfAuditEntries

A pointer to a ULONG that receives the number of EXPLICIT_ACCESS structures returned in the pListOfAuditEntries array. This parameter can be NULL only if the pListOfAuditEntries parameter is also NULL.

[out, optional] ppListOfAuditEntries

A pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs in the system access control list (SACL) of the security descriptor. The TRUSTEE structure in these EXPLICIT_ACCESS structures uses the TRUSTEE_IS_NAME form. If this parameter is NULL, the cCountOfAuditEntries parameter must also be NULL.

[in] pSD

A pointer to an existing self-relative security descriptor from which the function retrieves security information.

Return value

If the function succeeds, the function returns ERROR_SUCCESS.

If the function fails, it returns a nonzero error code defined in WinError.h.

Remarks

The LookupSecurityDescriptorParts function retrieves the names of the owner and primary group of the security descriptor. This function also returns descriptions of the ACEs in the DACL and audit-control entries in the SACL of the security descriptor.

The parameters other than pSD can be NULL if you are not interested in the information. If you do not want information about the DACL, both pListOfAccessEntries and cCountOfAuditEntries must be NULL. If you do not want information about the SACL, both pListOfAuditEntries and cCountOfAuditEntries must be NULL. Similarly, if you do want DACL or SACL information, both of the corresponding parameters must not be NULL.

When you have finished using any of the buffers returned by the pOwner, pGroup, pListOfAccessEntries, or pListOfAuditEntries parameters, free them by calling the LocalFree function.

The LookupSecurityDescriptorParts function is intended for trusted servers that implement or expose security on their own objects. The function works with a self-relative security descriptor suitable for serializing into a stream and storing to disk, as a trusted server might require.

Note

The aclapi.h header defines LookupSecurityDescriptorParts as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	aclapi.h
Library	Advapi32.lib
DLL	Advapi32.dll