LsaLookupNames2 function (ntsecapi.h)

The LsaLookupNames2 function retrieves the security identifiers (SIDs) for specified account names. LsaLookupNames2 can look up the SID for any account in any domain in a Windows forest.

The LsaLookupNames function is superseded by the LsaLookupNames2 function. Applications should use the LsaLookupNames2 function to ensure future compatibility.

This function differs from the LsaLookupNames function in that LsaLookupNames2 returns each SID as a single element, while LsaLookupNames divides each SID into an RID/domain pair.

Syntax

NTSTATUS LsaLookupNames2(
  [in]  LSA_HANDLE                  PolicyHandle,
  [in]  ULONG                       Flags,
  [in]  ULONG                       Count,
  [in]  PLSA_UNICODE_STRING         Names,
  [out] PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
  [out] PLSA_TRANSLATED_SID2        *Sids
);

Parameters

[in] PolicyHandle

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

[in] Flags

Values that control the behavior of this function. The following value is currently defined.

[in] Count

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

[in] Names

Pointer to an array of LSA_UNICODE_STRING structures that contain the names to look up. These strings can be the names of user, group, or local group accounts, or the names of domains. Domain names can be DNS domain names or NetBIOS domain names.

For more information about the format of the name strings, see Remarks.

[out] ReferencedDomains

Receives a pointer to an LSA_REFERENCED_DOMAIN_LIST structure. The Domains member of this structure is an array that contains an entry for each domain in which a name was found. The DomainIndex member of each entry in the Sids array is the index of the Domains array entry for the domain in which the name was found.

When you have finished using the returned pointer, free it by calling the
LsaFreeMemory function. 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

[out] Sids

Receives a pointer to an array of LSA_TRANSLATED_SID2 structures. Each entry in the Sids array contains the SID information for the corresponding entry in the Names array.

When you have finished using the returned pointer, free it by calling the
LsaFreeMemory function. 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 function returns one of the following NTSTATUS values.

If the function fails, the return value is the following NTSTATUS value or one of the LSA Policy Function Return Values.

Use the LsaNtStatusToWinError function to convert the NTSTATUS code to a Windows error code.

Remarks

Use fully qualified account names (for example, DomainName\UserName) instead of isolated names (for example, UserName). Fully qualified names are unambiguous and provide better performance when the lookup is performed. This function also supports fully qualified DNS names (for example, Example.Example.com\UserName) and user principal names (UPN) (for example, Someone@Example.com).

Translation of isolated names introduces the possibility of name collisions because the same name may be used in multiple domains. The LsaLookupNames2 function uses the following algorithm to translate isolated names.

To translate isolated names

1. If the name is a well-known name, such as Local or Interactive, the function returns the corresponding well-known security identifier (SID).
2. If the name is the name of the built-in domain, the function returns the SID of that domain.
3. If the name is the name of the account domain, the function returns the SID of that domain.
4. If the name is the name of the primary domain, the function returns the SID of that domain.
5. If the name is one of the names of the trusted domain, the function returns the SID of that domain.
6. If the name is a user, group, or local group account in the built-in domain, the function returns the SID of that account.
7. If the name is a user, group, or local group account in the account domain on the local system, the function returns the SID of that account.
8. If the name is a user, group, or a local group in the primary domain, the function returns the SID of that account.
9. After looking in the primary domain, the function looks in each of the primary domain's trusted domains.
10. Otherwise, the name is not translated.

Requirements

See also

LSA_REFERENCED_DOMAIN_LIST

LSA_TRANSLATED_SID2

LSA_UNICODE_STRING

LsaFreeMemory