Función LookupAccountSidA (winbase.h)

Artículo
03/08/2023

La función LookupAccountSid acepta un identificador de seguridad (SID) como entrada. Recupera el nombre de la cuenta de este SID y el nombre del primer dominio en el que se encuentra este SID.

Sintaxis

BOOL LookupAccountSidA(
  [in, optional]  LPCSTR        lpSystemName,
  [in]            PSID          Sid,
  [out, optional] LPSTR         Name,
  [in, out]       LPDWORD       cchName,
  [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 equipo de destino. Esta cadena puede ser el nombre de un equipo remoto. Si este parámetro 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 se encuentra en un dominio que no es de confianza y se conoce el nombre de un equipo de ese dominio.

[in] Sid

Puntero al SID que se va a buscar.

[out, optional] Name

Puntero a un búfer que recibe una cadena terminada en null que contiene el nombre de cuenta que corresponde al parámetro lpSid .

[in, out] cchName

En la entrada, especifica el tamaño, en TCHARs, del búfer lpName . Si se produce un error en la función porque el búfer es demasiado pequeño o si cchName es cero, cchName recibe el tamaño de búfer necesario, incluido el carácter nulo de terminación.

[out, optional] ReferencedDomainName

Puntero a un búfer que recibe una cadena terminada en null que contiene el nombre del dominio donde se encontró el nombre de la cuenta.

En un servidor, el nombre de dominio devuelto para la mayoría de las cuentas de la base de datos de seguridad del equipo local es el nombre del dominio para el que el servidor es un controlador de dominio.

En una estación de trabajo, el nombre de dominio devuelto para la mayoría de las cuentas de la base de datos de seguridad del equipo local es el nombre del equipo a partir del último inicio del sistema (se excluyen las barras diagonales inversas). Si cambia el nombre del equipo, el nombre anterior continúa devolviéndose como nombre de dominio hasta que se reinicie el sistema.

Algunas cuentas están predefinidas por el sistema. El nombre de dominio devuelto para estas cuentas es BUILTIN.

[in, out] cchReferencedDomainName

En la entrada, especifica el tamaño, en TCHARs, del búfer lpReferencedDomainName . Si se produce un error en la función porque el búfer es demasiado pequeño o si cchReferencedDomainName es cero, cchReferencedDomainName recibe el tamaño de búfer necesario, incluido el carácter nulo de terminación.

[out] peUse

Puntero a una variable que recibe un valor de SID_NAME_USE que indica el tipo de la cuenta.

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 LookupAccountSid intenta buscar un nombre para el SID especificado comprobando primero una lista de SID conocidos. Si el SID proporcionado 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. Los identificadores de seguridad no reconocidos por el dominio principal se comprueban con los dominios de confianza que corresponden a sus prefijos de SID.

Si la función no encuentra un nombre de cuenta para el SID, GetLastError devuelve ERROR_NONE_MAPPED. Esto puede ocurrir si un tiempo de espera de red impide que la función encuentre el nombre. También se produce para los SID que no tienen ningún nombre de cuenta correspondiente, como un SID de inicio de sesión que identifica una sesión de inicio de sesión.

Además de buscar SID para cuentas locales, cuentas de dominio locales y cuentas de dominio de confianza explícita, LookupAccountSid puede buscar SID para cualquier cuenta de cualquier dominio del bosque, incluidos los SID que aparecen solo en el campo SIDhistory de una cuenta del bosque. El campo SIDhistory almacena antiguos SID de una cuenta que se ha movido de otro dominio. Para buscar un SID, LookupAccountSid consulta el catálogo global del bosque.

Ejemplos

Para obtener un ejemplo que usa esta función, vea Buscar un SID en un token de acceso.

Nota

El encabezado winbase.h define LookupAccountSid 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o 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 (incluye Windows.h)
Library	Advapi32.lib
Archivo DLL	Advapi32.dll