Export (0) Print
Expand All

LsaLookupNames function

The LsaLookupNames function retrieves the security identifiers (SIDs) that correspond to an array of user, group, or local group names.

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

The LsaLookupNames function can also retrieve computer accounts.

Syntax


NTSTATUS LsaLookupNames(
  _In_   LSA_HANDLE PolicyHandle,
  _In_   ULONG Count,
  _In_   PLSA_UNICODE_STRING Names,
  _Out_  PLSA_REFERENCED_DOMAIN_LIST *ReferencedDomains,
  _Out_  PLSA_TRANSLATED_SID *Sids
);

Parameters

PolicyHandle [in]

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.

Count [in]

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

Names [in]

Pointer to an array of LSA_UNICODE_STRING structures that contain the names to look up. The strings in these structures 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.

ReferencedDomains [out]

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 the memory 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

Sids [out]

Receives a pointer to an array of LSA_TRANSLATED_SID 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 the memory 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.

ValueDescription
STATUS_SOME_NOT_MAPPED

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

STATUS_SUCCESS

All of the names were found and successfully translated.

 

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

ValueDescription
STATUS_NONE_MAPPED

None of the names were translated.

 

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

Remarks

Use fully qualified account names (for example, domain_name\user_name) instead of isolated names (for example, user_name). 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\user_name) 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 LsaLookupNames function uses the following algorithm to translate isolated names

ms721797.wedge(en-us,VS.85).gifTo 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 primary domain looks in each of its trusted domains.
  10. Otherwise, the name is not translated.

In addition to looking up local accounts, local domain accounts, and explicitly trusted domain accounts, LsaLookupNames can look up the name of any account in any domain in the Windows forest.

Examples

For an example that calls this function, see Translating Between Names and SIDs.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Ntsecapi.h

Library

Advapi32.lib

DLL

Advapi32.dll

See also

LsaFreeMemory
LsaLookupSids
LSA_REFERENCED_DOMAIN_LIST
LSA_TRANSLATED_SID
LSA_UNICODE_STRING

 

 

Community Additions

ADD
Show:
© 2014 Microsoft