Função LookupAccountNameA (winbase.h)

Artigo
08/27/2023

A função LookupAccountName aceita o nome de um sistema e uma conta como entrada. Ele recupera um SID ( identificador de segurança ) para a conta e o nome do domínio no qual a conta foi encontrada.

A função LsaLookupNames também pode recuperar contas de computador.

Sintaxe

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

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do sistema. Essa cadeia de caracteres pode ser o nome de um computador remoto. Se essa cadeia de caracteres 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] lpAccountName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome da conta.

Use uma cadeia de caracteres totalmente qualificada no formato domain_name\user_name para garantir que LookupAccountName encontre a conta no domínio desejado.

[out, optional] Sid

Um ponteiro para um buffer que recebe a estrutura sid que corresponde ao nome da conta apontado pelo parâmetro lpAccountName . Se esse parâmetro for NULL, cbSid deverá ser zero.

[in, out] cbSid

Um ponteiro para uma variável. Na entrada, esse valor especifica o tamanho, em bytes , do buffer sid. Se a função falhar porque o buffer é muito pequeno ou se cbSid for zero, essa variável receberá o tamanho do buffer necessário.

[out, optional] ReferencedDomainName

Um ponteiro para um buffer que recebe o nome do domínio em que o nome da conta é encontrado. Para computadores que não estão ingressados em um domínio, esse buffer recebe o nome do computador. Se esse parâmetro for NULL, a função retornará o tamanho do buffer necessário.

[in, out] cchReferencedDomainName

Um ponteiro para uma variável. Na entrada, esse valor especifica o tamanho, em TCHARs, do buffer ReferencedDomainName . Se a função falhar porque o buffer é muito pequeno, essa variável receberá o tamanho do buffer necessário, incluindo o caractere nulo de terminação. Se o parâmetro ReferencedDomainName for NULL, esse parâmetro deverá ser zero.

[out] peUse

Um ponteiro para um SID_NAME_USE tipo enumerado que indica o tipo da conta quando a função retorna.

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 LookupAccountName tenta localizar um SID para o nome especificado verificando primeiro uma lista de SIDs conhecidos. Se o nome 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. Se o nome não for encontrado lá, os domínios confiáveis serão verificados.

Use nomes de conta totalmente qualificados (por exemplo, domain_name\user_name) em vez de nomes isolados (por exemplo, user_name). Nomes totalmente qualificados são inequívoco e fornecem melhor desempenho quando a pesquisa é executada. Essa função também dá suporte a nomes DNS totalmente qualificados (por exemplo, example.example.com\user_name ) e nomes upn (por exemplo, someone@example.com).

Além de pesquisar contas locais, contas de domínio local e contas de domínio explicitamente confiáveis, LookupAccountName pode pesquisar o nome de qualquer conta em qualquer domínio na floresta.

Observação

O cabeçalho winbase.h define LookupAccountName 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