Función LookupAccountNameA (winbase.h)

Artículo
08/27/2023

La función LookupAccountName acepta el nombre de un sistema y una cuenta como entrada. Recupera un identificador de seguridad (SID) para la cuenta y el nombre del dominio en el que se encontró la cuenta.

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

Sintaxis

BOOL LookupAccountNameA(
  [in, optional]  LPCSTR        lpSystemName,
  [in]            LPCSTR        lpAccountName,
  [out, optional] PSID          Sid,
  [in, out]       LPDWORD       cbSid,
  [out, optional] LPSTR         ReferencedDomainName,
  [in, out]       LPDWORD       cchReferencedDomainName,
  [out]           PSID_NAME_USE peUse
);

Parámetros

[in, optional] lpSystemName

Puntero a una cadena de caracteres terminada en null que especifica el nombre del sistema. Esta cadena puede ser el nombre de un equipo remoto. Si esta cadena es NULL, la traducción del nombre de cuenta comienza en el sistema local. Si el nombre no se puede resolver en el sistema local, esta función intentará resolver el nombre mediante controladores de dominio de confianza para el sistema local. Por lo general, especifique un valor para lpSystemName solo cuando la cuenta esté en un dominio que no sea de confianza y se conozca el nombre de un equipo de ese dominio.

[in] lpAccountName

Puntero a una cadena terminada en null que especifica el nombre de la cuenta.

Use una cadena completa en el formato domain_name\user_name para asegurarse de que LookupAccountName encuentra la cuenta en el dominio deseado.

[out, optional] Sid

Puntero a un búfer que recibe la estructura de SID que corresponde al nombre de cuenta al que apunta el parámetro lpAccountName . Si este parámetro es NULL, cbSid debe ser cero.

[in, out] cbSid

Puntero a una variable. En la entrada, este valor especifica el tamaño, en bytes, del búfer sid . Si se produce un error en la función porque el búfer es demasiado pequeño o si cbSid es cero, esta variable recibe el tamaño de búfer necesario.

[out, optional] ReferencedDomainName

Puntero a un búfer que recibe el nombre del dominio donde se encuentra el nombre de la cuenta. Para los equipos que no están unidos a un dominio, este búfer recibe el nombre del equipo. Si este parámetro es NULL, la función devuelve el tamaño de búfer necesario.

[in, out] cchReferencedDomainName

Puntero a una variable. En la entrada, este valor especifica el tamaño, en TCHARs, del búfer ReferencedDomainName . Si se produce un error en la función porque el búfer es demasiado pequeño, esta variable recibe el tamaño de búfer necesario, incluido el carácter nulo de terminación. Si el parámetro ReferencedDomainName es NULL, este parámetro debe ser cero.

[out] peUse

Puntero a un tipo enumerado SID_NAME_USE que indica el tipo de la cuenta cuando la función devuelve.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

Si se produce un error en la función, devuelve cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La función LookupAccountName intenta buscar un SID para el nombre especificado comprobando primero una lista de SID conocidos. Si el nombre no corresponde a un SID conocido, la función comprueba las cuentas locales integradas y definidas administrativamente. A continuación, la función comprueba el dominio principal. Si no se encuentra el nombre, se comprueban los dominios de confianza.

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

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

Nota

El encabezado winbase.h define LookupAccountName como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winbase.h (incluya Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll