LsaLookupNames 函数 (ntsecapi.h)

项目
02/29/2024

LsaLookupNames 函数检索与用户、组或本地组名称数组相对应的 SID (SID) 的安全标识符。

LsaLookupNames 函数被 LsaLookupNames2 函数取代。应用程序应使用 LsaLookupNames2 函数来确保将来的兼容性。

LsaLookupNames 函数还可以检索计算机帐户。

语法

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
);

参数

[in] PolicyHandle

Policy 对象的句柄。句柄必须具有POLICY_LOOKUP_NAMES访问权限。有关详细信息，请参阅打开策略对象句柄。

[in] Count

指定 Names 数组中的名称数。这也是 Sids 数组中返回的条目数。此值必须小于或等于 1000。

[in] Names

指向包含要查找的名称的 LSA_UNICODE_STRING 结构的数组的指针。这些结构中的字符串可以是用户、组或本地组帐户的名称，也可以是域的名称。域名可以是 DNS 域名或 NetBIOS 域名。

有关名称字符串格式的详细信息，请参阅备注。

[out] ReferencedDomains

接收指向 LSA_REFERENCED_DOMAIN_LIST 结构的指针。此结构的 Domains 成员是一个数组，其中包含在其中找到名称的每个域的条目。 Sids 数组中每个条目的 DomainIndex 成员是在其中找到名称的域的域数组项的索引。

使用完返回的指针后，通过调用释放内存
LsaFreeMemory 函数。即使函数因错误代码STATUS_NONE_MAPPED或STATUS_SOME_NOT_MAPPED而失败，也必须释放此内存

[out] Sids

接收指向 LSA_TRANSLATED_SID 结构的数组的指针。 Sids 数组中的每个条目都包含 Names 数组中相应条目的 SID 信息。

使用完返回的指针后，通过调用释放内存
LsaFreeMemory 函数。即使函数因错误代码STATUS_NONE_MAPPED或STATUS_SOME_NOT_MAPPED而失败，也必须释放此内存

返回值

如果函数成功，该函数将返回以下 NTSTATUS 值之一。

值	说明
STATUS_SOME_NOT_MAPPED	某些名称无法翻译。这是一个信息级返回值。
STATUS_SUCCESS	所有名称都已找到并成功翻译。

如果函数失败，则返回值为以下 NTSTATUS 值或 LSA 策略函数返回值之一。

值	说明
STATUS_NONE_MAPPED	没有翻译任何名字。
STATUS_TOO_MANY_NAMES	Names 数组参数太大。

使用 LsaNtStatusToWinError 函数将 NTSTATUS 代码转换为 Windows 错误代码。

注解

警告

(使用完全限定的帐户名称，例如，domain_name\user_name) ，而不是 (独立名称，例如user_name) 。完全限定的名称是明确的，在执行查找时提供更好的性能。此函数还支持完全限定的 DNS 名称 (例如，example.example.com\user_name) 和用户主体名称 (UPN) (例如 someone@example.com ，) 。

警告

有关独立名称的限制的详细信息，请参阅 LsaLookupNames2 文档。

LsaLookupNames 函数使用以下算法来转换帐户名。

转换名称

如果该名称是已知名称（如 Local 或 Interactive），则函数将返回相应的已知安全标识符 (SID) 。
如果该名称是内置域的名称，则函数将返回该域的 SID。
如果该名称是帐户域的名称，则函数将返回该域的 SID。
如果该名称是主域的名称，则函数将返回该域的 SID。
如果该名称是受信任域的名称之一，则函数将返回该域的 SID。
如果名称是内置域中的用户、组或本地组帐户，则函数将返回该帐户的 SID。
如果名称是本地系统上帐户域中的用户、组或本地组帐户，则函数将返回该帐户的 SID。
如果在缓存中找到该名称，则函数将返回该帐户的 SID。
如果名称是主域中的用户、组或本地组，则函数将返回该帐户的 SID。
在主域中查找后，主域将查找其每个受信任的域。
否则，不会转换名称。

除了查找本地帐户、本地域帐户和显式受信任的域帐户外， LsaLookupNames 还可以查找 Windows 林中任何域中任何帐户的名称。

示例

有关调用此函数的示例，请参阅在名称和 SID 之间转换。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	ntsecapi.h
Library	Advapi32.lib
DLL	Advapi32.dll