Expand Minimize

LookupSecurityDescriptorParts function

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

Syntax


DWORD WINAPI LookupSecurityDescriptorParts(
  _Out_opt_  PTRUSTEE *pOwner,
  _Out_opt_  PTRUSTEE *pGroup,
  _Out_opt_  PULONG cCountOfAccessEntries,
  _Out_opt_  PEXPLICIT_ACCESS *pListOfAccessEntries,
  _Out_opt_  PULONG cCountOfAuditEntries,
  _Out_opt_  PEXPLICIT_ACCESS *pListOfAuditEntries,
  _In_       PSECURITY_DESCRIPTOR pSD
);

Parameters

pOwner [out, optional]

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.

pGroup [out, optional]

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.

cCountOfAccessEntries [out, optional]

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.

pListOfAccessEntries [out, optional]

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.

cCountOfAuditEntries [out, optional]

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.

pListOfAuditEntries [out, optional]

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.

pSD [in]

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.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Aclapi.h

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

LookupSecurityDescriptorPartsW (Unicode) and LookupSecurityDescriptorPartsA (ANSI)

See also

Client/Server Access Control Overview
Client/Server Access Control Functions
ACE
ACL
EXPLICIT_ACCESS
GetExplicitEntriesFromAcl
LocalFree
SECURITY_DESCRIPTOR
SID
TRUSTEE

 

 

Community Additions

ADD
Show:
© 2014 Microsoft