Función LsaLookupNames (ntsecapi.h)

Artículo
03/08/2023

La función LsaLookupNames recupera los identificadores de seguridad (SID) que corresponden a una matriz de nombres de usuario, grupo o grupo local.

La función LsaLookupNames se sustituye por la función LsaLookupNames2 . Las aplicaciones deben usar la función LsaLookupNames2 para garantizar la compatibilidad futura.

La función LsaLookupNames también puede recuperar cuentas de equipo.

Sintaxis

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

Parámetros

[in] PolicyHandle

Identificador de un objeto Policy . El identificador debe tener el derecho de acceso POLICY_LOOKUP_NAMES. Para obtener más información, vea Apertura de un identificador de objeto de directiva.

[in] Count

Especifica el número de nombres de la matriz Names . También es el número de entradas devueltas en la matriz Sids . Este valor debe ser menor o igual que 1000.

[in] Names

Puntero a una matriz de estructuras de LSA_UNICODE_STRING que contienen los nombres que se van a buscar. Las cadenas de estas estructuras pueden ser los nombres de las cuentas de usuario, grupo o grupo local, o los nombres de los dominios. Los nombres de dominio pueden ser nombres de dominio DNS o nombres de dominio netBIOS.

Para obtener más información sobre el formato de las cadenas de nombre, vea Comentarios.

[out] ReferencedDomains

Recibe un puntero a una estructura de LSA_REFERENCED_DOMAIN_LIST . El miembro Domains de esta estructura es una matriz que contiene una entrada para cada dominio en el que se encontró un nombre. El miembro DomainIndex de cada entrada de la matriz Sids es el índice de la entrada de la matriz Domains para el dominio en el que se encontró el nombre.

Cuando haya terminado de usar el puntero devuelto, libere la memoria llamando al
Función LsaFreeMemory . Esta memoria debe liberarse incluso cuando se produce un error en la función con los códigos de error STATUS_NONE_MAPPED o STATUS_SOME_NOT_MAPPED

[out] Sids

Recibe un puntero a una matriz de estructuras de LSA_TRANSLATED_SID . Cada entrada de la matriz Sids contiene la información del SID para la entrada correspondiente en la matriz Names .

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve uno de los siguientes valores NTSTATUS .

Valor	Descripción
STATUS_SOME_NOT_MAPPED	Algunos de los nombres no se pudieron traducir. Se trata de un valor devuelto de nivel informativo.
STATUS_SUCCESS	Todos los nombres se encontraron y se traduciron correctamente.

Si se produce un error en la función, el valor devuelto es el siguiente valor NTSTATUS o uno de los valores devueltos de la función de directiva LSA.

Valor	Descripción
STATUS_NONE_MAPPED	Ninguno de los nombres se traducía.
STATUS_TOO_MANY_NAMES	El parámetro de matriz Names era demasiado grande.

Use la función LsaNtStatusToWinError para convertir el código NTSTATUS en un código de error de Windows.

Comentarios

Advertencia

Use nombres de cuenta completos (por ejemplo, domain_name\user_name) en lugar de nombres aislados (por ejemplo, user_name). Los nombres completos no son ambiguos y proporcionan un mejor rendimiento cuando se realiza la búsqueda. Esta función también admite nombres DNS completos (por ejemplo, example.example.com\user_name) y nombres principales de usuario (UPN) (por ejemplo, someone@example.com).

Advertencia

Para obtener más información sobre las limitaciones de los nombres aislados, consulte la documentación de LsaLookupNames2 .

La función LsaLookupNames usa el siguiente algoritmo para traducir los nombres de cuenta.

Para traducir nombres

Si el nombre es un nombre conocido, como Local o Interactivo, la función devuelve el identificador de seguridad conocido (SID) correspondiente.
Si el nombre es el nombre del dominio integrado, la función devuelve el SID de ese dominio.
Si el nombre es el nombre del dominio de cuenta, la función devuelve el SID de ese dominio.
Si el nombre es el nombre del dominio principal, la función devuelve el SID de ese dominio.
Si el nombre es uno de los nombres del dominio de confianza, la función devuelve el SID de ese dominio.
Si el nombre es una cuenta de usuario, grupo o grupo local en el dominio integrado, la función devuelve el SID de esa cuenta.
Si el nombre es una cuenta de usuario, grupo o grupo local en el dominio de cuenta del sistema local, la función devuelve el SID de esa cuenta.
Si el nombre se encuentra en la memoria caché, la función devuelve el SID de esa cuenta.
Si el nombre es un usuario, un grupo o un grupo local en el dominio principal, la función devuelve el SID de esa cuenta.
Después de buscar en el dominio principal, el dominio principal busca en cada uno de sus dominios de confianza.
De lo contrario, el nombre no se traduce.

Además de buscar cuentas locales, cuentas de dominio locales y cuentas de dominio de confianza explícitamente, LsaLookupNames puede buscar el nombre de cualquier cuenta en cualquier dominio del bosque de Windows.

Ejemplos

Para obtener un ejemplo que llama a esta función, consulte Traducción entre nombres y SID.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ntsecapi.h
Library	Advapi32.lib
Archivo DLL	Advapi32.dll