Função LsaLookupNames (ntsecapi.h)

Artigo
03/08/2023

A função LsaLookupNames recupera os SIDs ( identificadores de segurança ) que correspondem a uma matriz de nomes de usuário, grupo ou grupo local.

A função LsaLookupNames é substituída pela função LsaLookupNames2 . Os aplicativos devem usar a função LsaLookupNames2 para garantir a compatibilidade futura.

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

Sintaxe

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

Um identificador para um objeto Policy . O identificador deve ter o direito de acesso POLICY_LOOKUP_NAMES. Para obter mais informações, consulte Abrindo um identificador de objeto de política.

[in] Count

Especifica o número de nomes na matriz Names . Esse também é o número de entradas retornadas na matriz Sids . Esse valor deve ser menor ou igual a 1000.

[in] Names

Ponteiro para uma matriz de estruturas LSA_UNICODE_STRING que contêm os nomes a serem pesquisados. As cadeias de caracteres nessas estruturas podem ser os nomes de contas de usuário, grupo ou grupo local ou os nomes de domínios. Os nomes de domínio podem ser nomes de domínio DNS ou nomes de domínio NetBIOS.

Para obter mais informações sobre o formato das cadeias de caracteres de nome, consulte Comentários.

[out] ReferencedDomains

Recebe um ponteiro para uma estrutura LSA_REFERENCED_DOMAIN_LIST . O membro Domínios dessa estrutura é uma matriz que contém uma entrada para cada domínio no qual um nome foi encontrado. O membro DomainIndex de cada entrada na matriz Sids é o índice da entrada de matriz Domains para o domínio no qual o nome foi encontrado.

Quando terminar de usar o ponteiro retornado, libere a memória chamando o
Função LsaFreeMemory . Essa memória deve ser liberada mesmo quando a função falha com um dos códigos de erro STATUS_NONE_MAPPED ou STATUS_SOME_NOT_MAPPED

[out] Sids

Recebe um ponteiro para uma matriz de estruturas LSA_TRANSLATED_SID . Cada entrada na matriz Sids contém as informações de SID para a entrada correspondente na matriz Names .

Retornar valor

Se a função for bem-sucedida, a função retornará um dos seguintes valores NTSTATUS .

Valor	Descrição
STATUS_SOME_NOT_MAPPED	Alguns dos nomes não puderam ser traduzidos. Esse é um valor retornado de nível informativo.
STATUS_SUCCESS	Todos os nomes foram encontrados e traduzidos com êxito.

Se a função falhar, o valor retornado será o seguinte valor NTSTATUS ou um dos valores retornados da função de política LSA.

Valor	Descrição
STATUS_NONE_MAPPED	Nenhum dos nomes foi traduzido.
STATUS_TOO_MANY_NAMES	O parâmetro de matriz Names era muito grande.

Use a função LsaNtStatusToWinError para converter o código NTSTATUS em um código de erro do Windows.

Comentários

Aviso

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ívocas 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 upn (nomes upn) (por exemplo, someone@example.com).

Aviso

Para obter mais informações sobre as limitações de nomes isolados, consulte a documentação LsaLookupNames2 .

A função LsaLookupNames usa o algoritmo a seguir para traduzir nomes de conta.

Para traduzir nomes

Se o nome for um nome conhecido, como Local ou Interativo, a função retornará o SID ( identificador de segurança ) conhecido correspondente.
Se o nome for o nome do domínio interno, a função retornará o SID desse domínio.
Se o nome for o nome do domínio da conta, a função retornará o SID desse domínio.
Se o nome for o nome do domínio primário, a função retornará o SID desse domínio.
Se o nome for um dos nomes do domínio confiável, a função retornará o SID desse domínio.
Se o nome for uma conta de usuário, grupo ou grupo local no domínio interno, a função retornará o SID dessa conta.
Se o nome for uma conta de usuário, grupo ou grupo local no domínio da conta no sistema local, a função retornará o SID dessa conta.
Se o nome for encontrado no cache, a função retornará o SID dessa conta.
Se o nome for um usuário, um grupo ou um grupo local no domínio primário, a função retornará o SID dessa conta.
Depois de examinar o domínio primário, o domínio primário examina cada um de seus domínios confiáveis.
Caso contrário, o nome não será traduzido.

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

Exemplos

Para obter um exemplo que chama essa função, consulte Traduzindo entre nomes e SIDs.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	ntsecapi.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll