LookupSecurityDescriptorParts

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

DWORD LookupSecurityDescriptorParts(
  PTRUSTEE *pOwner,                       // owner SID from SD
  PTRUSTEE *pGroup,                       // group SID from SD
  PULONG cCountOfAccessEntries,           // number of access-control entries
  PEXPLICIT_ACCESS *pListOfAccessEntries, // DACL access-control array
  PULONG cCountOfAuditEntries,            // number of audit-control entries
  PEXPLICIT_ACCESS *pListOfAuditEntries,  // SACL audit-control array
  PSECURITY_DESCRIPTOR pSD                // self-relative SD
);

Parameters

pOwner

[out] Pointer to a variable that receives a pointer to a TRUSTEE structure. The function looks up the name associated with the owner 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] 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] 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] Pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs in the 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 ACL, see the GetExplicitEntriesFromAcl function. If this parameter is NULL, the cCountOfAccessEntries parameter must also be NULL.

cCountOfAuditEntries

[out] 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] Pointer to a variable that receives a pointer to an array of EXPLICIT_ACCESS structures that describe the ACEs in the 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] Pointer to an existing self-relative security descriptor from which the function retrieves security information. A self-relative security descriptor stores a SECURITY_DESCRIPTOR structure and associated security information in a contiguous block of memory. This differs from an absolute security descriptor, which contains pointers to the associated security information.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is 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. It also returns descriptions of the access-control entries 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 cCountOfAccessEntries 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 be non-NULL.

You must call the LocalFree function to free any buffers returned by the pOwner, pGroup, pListOfAccessEntries, or pListOfAuditEntries parameters.

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

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Header: Declared in Aclapi.h.
  Library: Use Advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

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