ISecurityInformation2::LookupSids method (aclui.h)

Article
02/22/2024

The LookupSids method returns the common names corresponding to each of the elements in the specified list of SIDs.

Syntax

HRESULT LookupSids(
  [in]  ULONG        cSids,
  [in]  PSID         *rgpSids,
  [out] LPDATAOBJECT *ppdo
);

Parameters

[in] cSids

The number of pointers to SID structures pointed to by rgpSids.

[in] rgpSids

A pointer to an array of pointers to SID structures.

[out] ppdo

A pointer to a pointer to a returned data transfer object that contains the common names of the SIDs. Optionally, this parameter also returns the user principal name (UPN) of the SIDs in the rgpSids parameter. The data transfer object is a SID_INFO structure.

Return value

Returns S_OK if successful.

Returns a nonzero error code if an error occurs.

Remarks

Your implementation of LookupSids can return E_NOTIMPL if the access control editor is to determine the common names corresponding to the specified SIDs. However, if the access control editor receives any return code other than S_OK, the editor determines this information.

The client must return the common names through the data object using the following format.

#include <windows.h>

// HGLOBAL containing SID_INFO_LIST returned by
// ISecurityInformation2::LookupSids
#define CFSTR_ACLUI_SID_INFO_LIST   TEXT("CFSTR_ACLUI_SID_INFO_LIST")

// Data structures corresponding to CFSTR_ACLUI_SID_INFO_LIST
typedef struct _SID_INFO
{
    PSID    pSid;
    PWSTR   pwzCommonName;
    PWSTR   pwzClass;       // Used for selecting icon, for example,
                            // "User" or "Group"
    PWSTR   pwzUPN;         // Optional pointer to a user principal
                            // name
} SID_INFO, *PSID_INFO;

typedef struct _SID_INFO_LIST
{
    ULONG       cItems;
    SID_INFO    aSidInfo[ANYSIZE_ARRAY];
} SID_INFO_LIST, *PSID_INFO_LIST;

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	aclui.h