Функция LsaLookupNames (ntsecapi.h)

Статья
03/08/2023

Функция LsaLookupNames извлекает идентификаторы безопасности (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

Указывает количество имен в массиве Name . Это также количество записей, возвращаемых в массиве Sids . Это значение должно быть меньше или равно 1000.

[in] Names

Указатель на массив LSA_UNICODE_STRING структур, содержащих имена для поиска. Строки в этих структурах могут быть именами учетных записей пользователей, групп или локальных групп или доменов. Доменные имена могут быть доменными именами DNS или NetBIOS.

Дополнительные сведения о формате строк имен см. в разделе Примечания.

[out] ReferencedDomains

Получает указатель на структуру LSA_REFERENCED_DOMAIN_LIST . ЭлементОм Domains этой структуры является массив, содержащий запись для каждого домена, в котором было найдено имя. Элемент DomainIndex каждой записи в массиве Sids является индексом записи массива Domains для домена, в котором было найдено имя.

Завершив использование возвращаемого указателя, освободите память, вызвав
Функция LsaFreeMemory. Эта память должна быть освобождена, даже если функция завершается сбоем с использованием любого из кодов ошибок STATUS_NONE_MAPPED или STATUS_SOME_NOT_MAPPED

[out] Sids

Получает указатель на массив LSA_TRANSLATED_SID структур. Каждая запись в массиве Sids содержит сведения о идентификаторе безопасности для соответствующей записи в массиве Имен .

Возвращаемое значение

Если функция выполнена успешно, функция возвращает одно из следующих значений 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 использует следующий алгоритм для перевода имен учетных записей.

Перевод имен

Если имя является хорошо известным, например Локальный или Интерактивный, функция возвращает соответствующий хорошо известный идентификатор безопасности (SID).
Если имя является именем встроенного домена, функция возвращает идентификатор безопасности этого домена.
Если имя является именем домена учетной записи, функция возвращает идентификатор безопасности этого домена.
Если имя является именем основного домена, функция возвращает идентификатор безопасности этого домена.
Если имя является одним из имен доверенного домена, функция возвращает идентификатор безопасности этого домена.
Если имя является учетной записью пользователя, группы или локальной группы во встроенном домене, функция возвращает идентификатор безопасности этой учетной записи.
Если имя является учетной записью пользователя, группы или локальной группы в домене учетной записи в локальной системе, функция возвращает идентификатор безопасности этой учетной записи.
Если имя найдено в кэше, функция возвращает идентификатор безопасности этой учетной записи.
Если имя является пользователем, группой или локальной группой в основном домене, функция возвращает идентификатор безопасности этой учетной записи.
После просмотра основного домена основной домен выполняет поиск в каждом из своих доверенных доменов.
В противном случае имя не преобразуется.

Помимо поиска локальных учетных записей, учетных записей локального домена и явно доверенных учетных записей доменов, LsaLookupNames может искать имя любой учетной записи в любом домене в лесу Windows.

Примеры

Пример вызова этой функции см. в разделе Преобразование между именами и идентификаторами БЕЗОПАСНОСТИ.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	ntsecapi.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll