LsaLookupSids2 function

The LsaLookupSids2 function looks up the names that correspond to an array of security identifiers (SIDs) and supports Internet provider identities. If LsaLookupSids2 cannot find a name that corresponds to a SID, the function returns the SID in character form. You should use this function instead of the LsaLookupSids function.

Syntax


NTSTATUS LsaLookupSids2(
  _In_   LSA_HANDLE PolicyHandle,
  _In_   ULONG LookupOptions,
  _In_   ULONG Count,
  _In_   PSID *Sids,
  _Out_  PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
  _Out_  PLSA_TRANSLATED_NAME *Names
);

Parameters

PolicyHandle [in]

A handle to a Policy object. This handle must have the POLICY_LOOKUP_NAMES access right. For more information, see Opening a Policy Object Handle.

LookupOptions [in]

Flags that modify the lookup behavior.

ValueMeaning
LSA_LOOKUP_RETURN_LOCAL_NAMES

Always returns local SAM account names even for Internet provider identities.

 

Count [in]

Specifies the number of SIDs in the Sids array. This is also the number of entries returned in the Names array.

Sids [in]

Pointer to an array of SID pointers to look up. The SIDs can be well-known SIDs, user, group, or local group account SIDs, or domain SIDs.

ReferencedDomains [out]

Receives a pointer to a pointer to a LSA_REFERENCED_DOMAIN_LIST structure. The Domains member of this structure is an array that contains an entry for each domain in which a SID was found. The entry for each domain contains the SID and flat name of the domain. For Windows domains, the flat name is the NetBIOS name. For links with non–Windows domains, the flat name is the identifying name of that domain, or it is NULL.

When you no longer need the information, pass the returned pointer to LsaFreeMemory. This memory must be freed even when the function fails with the either of the error codes STATUS_NONE_MAPPED or STATUS_SOME_NOT_MAPPED

Names [out]

Receives a pointer to an array of LSA_TRANSLATED_NAME structures. Each entry in the Names array contains the name information for the corresponding entry in the Sids array. For account SIDs, the Name member of each structure contains the isolated name of the account. For domain SIDs, the Name member is not valid.

The DomainIndex member of each entry in the Names array is the index of an entry in the Domains array returned in the ReferencedDomains parameter. The index identifies the Domains array for the domain in which the SID was found.

When you no longer need the information, pass the returned pointer to LsaFreeMemory. This memory must be freed even when the function fails with the either of the error codes STATUS_NONE_MAPPED or STATUS_SOME_NOT_MAPPED

Return value

If the function succeeds, the return value is one of the following NTSTATUS values.

Return codeDescription
STATUS_SOME_NOT_MAPPED

Some of the SIDs could not be translated. This is an informational-level return value.

STATUS_SUCCESS

All of the SIDs were found and successfully translated.

 

If the function fails, the return value is an NTSTATUS code, which can be one of the following values or one of the LSA Policy Function Return Values.

Return codeDescription
STATUS_NONE_MAPPED

None of the SIDs were translated. This is an error-level return value.

 

You can use the LsaNtStatusToWinError function to convert the NTSTATUS code to a Windows error code.

Remarks

For account SIDs, the string returned in the Name member is the isolated name of the account (for example, user_name). If you need the composite name of the account (for example, Acctg\user_name), get the domain name from the ReferencedDomains buffer and append a backslash and the isolated name.

If the LsaLookupSids2 function cannot translate a SID, the function uses the following algorithm:

  1. If the SID's domain is known, the ReferencedDomains buffer contains an entry for the domain, and the string returned in the Names parameter is a Unicode representation of the account's relative identifier (RID) from the SID.
  2. If the SID's domain is not known, the string returned in the Names parameter is a Unicode representation of the entire SID, and there is no domain record for this SID in the ReferencedDomains buffer.

In addition to looking up SIDs for local accounts, local domain accounts, and explicitly trusted domain accounts, LsaLookupSids2 can look up SIDs for any account in any domain in the Windows forest, including SIDs that appear only in the SIDhistory field of an account in the forest. The SIDhistory field stores the former SIDs of an account that has been moved from another domain. To perform these searches, the function queries the global catalog of the forest.

Requirements

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Ntsecapi.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

LSA_REFERENCED_DOMAIN_LIST
LSA_TRANSLATED_NAME
LsaOpenPolicy

 

 

Community Additions

ADD
Show:
© 2014 Microsoft