Função LookupAccountSidA (winbase.h)

Artigo
03/13/2024

A função LookupAccountSid aceita um SID ( identificador de segurança ) como entrada. Ele recupera o nome da conta para esse SID e o nome do primeiro domínio no qual esse SID é encontrado.

Sintaxe

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

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o computador de destino. Essa cadeia de caracteres pode ser o nome de um computador remoto. Se esse parâmetro for NULL, a tradução do nome da conta começará no sistema local. Se o nome não puder ser resolvido no sistema local, essa função tentará resolve o nome usando controladores de domínio confiáveis pelo sistema local. Em geral, especifique um valor para lpSystemName somente quando a conta estiver em um domínio não confiável e o nome de um computador nesse domínio for conhecido.

[in] Sid

Um ponteiro para o SID pesquisar.

[out, optional] Name

Um ponteiro para um buffer que recebe uma cadeia de caracteres terminada em nulo que contém o nome da conta que corresponde ao parâmetro lpSid .

[in, out] cchName

Na entrada, especifica o tamanho, em TCHARs, do buffer lpName . Se a função falhar porque o buffer é muito pequeno ou se cchName for zero, cchName receberá o tamanho do buffer necessário, incluindo o caractere nulo de terminação.

[out, optional] ReferencedDomainName

Um ponteiro para um buffer que recebe uma cadeia de caracteres terminada em nulo que contém o nome do domínio em que o nome da conta foi encontrado.

Em um servidor, o nome de domínio retornado para a maioria das contas no banco de dados de segurança do computador local é o nome do domínio para o qual o servidor é um controlador de domínio.

Em uma estação de trabalho, o nome de domínio retornado para a maioria das contas no banco de dados de segurança do computador local é o nome do computador a partir do último início do sistema (barras invertidas são excluídas). Se o nome do computador for alterado, o nome antigo continuará a ser retornado como o nome de domínio até que o sistema seja reiniciado.

Algumas contas são predefinidas pelo sistema. O nome de domínio retornado para essas contas é BUILTIN.

[in, out] cchReferencedDomainName

Na entrada, especifica o tamanho, em TCHARs, do buffer lpReferencedDomainName . Se a função falhar porque o buffer é muito pequeno ou se cchReferencedDomainName for zero, cchReferencedDomainName receberá o tamanho do buffer necessário, incluindo o caractere nulo de terminação.

[out] peUse

Um ponteiro para uma variável que recebe um valor SID_NAME_USE que indica o tipo da conta.

Retornar valor

Se a função for bem-sucedida, a função retornará diferente de zero.

Se a função falhar, ela retornará zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

A função LookupAccountSid tenta encontrar um nome para o SID especificado verificando primeiro uma lista de SIDs conhecidos. Se o SID fornecido não corresponder a um SID conhecido, a função verificará contas locais internas e definidas administrativamente. Em seguida, a função verifica o domínio primário. Os identificadores de segurança não reconhecidos pelo domínio primário são verificados em relação aos domínios confiáveis que correspondem aos prefixos sid.

Se a função não puder encontrar um nome de conta para o SID, GetLastError retornará ERROR_NONE_MAPPED. Isso poderá ocorrer se um tempo limite de rede impedir que a função localize o nome. Também ocorre para SIDs que não têm nenhum nome de conta correspondente, como um SID de logon que identifica uma sessão de logon.

Além de pesquisar SIDs para contas locais, contas de domínio local e contas de domínio explicitamente confiáveis, o LookupAccountSid pode pesquisar SIDs para qualquer conta em qualquer domínio na floresta, incluindo SIDs que aparecem apenas no campo SIDhistory de uma conta na floresta. O campo SIDhistory armazena SIDs antigos de uma conta que foi movida de outro domínio. Para pesquisar um SID, o LookupAccountSid consulta o catálogo global da floresta.

Exemplos

Para obter um exemplo que usa essa função, consulte Pesquisando um SID em um Token de Acesso.

Observação

O cabeçalho winbase.h define LookupAccountSid como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Advapi32.lib
DLL	Advapi32.dll