Função DsGetDcNameW (dsgetdc.h)

Artigo
08/23/2023

A função DsGetDcName retorna o nome de um controlador de domínio em um domínio especificado. Essa função aceita critérios de seleção de controlador de domínio adicionais para indicar a preferência por um controlador de domínio com características específicas.

Sintaxe

DSGETDCAPI DWORD DsGetDcNameW(
  [in]  LPCWSTR                  ComputerName,
  [in]  LPCWSTR                  DomainName,
  [in]  GUID                     *DomainGuid,
  [in]  LPCWSTR                  SiteName,
  [in]  ULONG                    Flags,
  [out] PDOMAIN_CONTROLLER_INFOW *DomainControllerInfo
);

Parâmetros

[in] ComputerName

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do servidor para processar essa função. Normalmente, esse parâmetro é NULL, o que indica que o computador local é usado.

[in] DomainName

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome da partição de domínio ou aplicativo a ser consultada. Esse nome pode ser um nome de estilo DNS, por exemplo, fabrikam.com ou um nome de estilo simples, por exemplo, Fabrikam. Se um nome de estilo DNS for especificado, o nome poderá ser especificado com ou sem um período à direita.

Se o parâmetro Flags contiver o sinalizador DS_GC_SERVER_REQUIRED , DomainName deverá ser o nome da floresta. Nesse caso, DsGetDcName falhará se DomainName especificar um nome que não seja a raiz da floresta.

Se o parâmetro Flags contiver o sinalizador DS_GC_SERVER_REQUIRED e DomainName for NULL, DsGetDcName tentará localizar um catálogo global na floresta do computador identificado por ComputerName, que será o computador local se ComputerName for NULL.

Se DomainName for NULL e o parâmetro Flags não contiver o sinalizador DS_GC_SERVER_REQUIRED , ComputerName será definido como o nome de domínio padrão do domínio primário do computador identificado por ComputerName.

[in] DomainGuid

Ponteiro para uma estrutura GUID que especifica o GUID do domínio consultado. Se DomainGuid não for NULL e o domínio especificado por DomainName ou ComputerName não puder ser encontrado, DsGetDcName tentará localizar um controlador de domínio no domínio com o GUID especificado por DomainGuid.

[in] SiteName

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do site em que o controlador de domínio retornado deve existir fisicamente. Se esse parâmetro for NULL, DsGetDcName tentará retornar um controlador de domínio no site mais próximo do site do computador especificado por ComputerName. Esse parâmetro deve ser NULL, por padrão.

[in] Flags

Contém um conjunto de sinalizadores que fornecem dados adicionais usados para processar a solicitação. Esse parâmetro pode ser uma combinação dos seguintes valores.

DS_AVOID_SELF

Quando chamado de um controlador de domínio, especifica que o nome do controlador de domínio retornado não deve ser o computador atual. Se o computador atual não for um controlador de domínio, esse sinalizador será ignorado. Esse sinalizador pode ser usado para obter o nome de outro controlador de domínio no domínio.

DS_BACKGROUND_ONLY

Se o sinalizador DS_FORCE_REDISCOVERY não for especificado, essa função usará dados do controlador de domínio armazenados em cache. Se os dados armazenados em cache tiverem mais de 15 minutos, o cache será atualizado executando ping no controlador de domínio. Se esse sinalizador for especificado, essa atualização será evitada mesmo se os dados armazenados em cache expirarem. Esse sinalizador deverá ser usado se a função DsGetDcName for chamada periodicamente.

DS_DIRECTORY_SERVICE_PREFERRED

DsGetDcName tenta localizar um controlador de domínio que dá suporte a funções de serviço de diretório. Se um controlador de domínio que dá suporte a serviços de diretório não estiver disponível, DsGetDcName retornará o nome de um controlador de domínio de serviço que não seja de diretório. No entanto, DsGetDcName retorna apenas um controlador de domínio de serviço que não seja de diretório após a tentativa de localizar um controlador de domínio do serviço de diretório atingir o tempo limite.

DS_DIRECTORY_SERVICE_REQUIRED

Requer que o controlador de domínio retornado dê suporte a serviços de diretório.

DS_DIRECTORY_SERVICE_6_REQUIRED

Requer que o controlador de domínio retornado esteja executando o Windows Server 2008 ou posterior.

DS_DIRECTORY_SERVICE_8_REQUIRED

Requer que o controlador de domínio retornado esteja executando Windows Server 2012 ou posterior.

DS_FORCE_REDISCOVERY

Força os dados do controlador de domínio armazenados em cache a serem ignorados. Quando o sinalizador DS_FORCE_REDISCOVERY não for especificado, DsGetDcName poderá retornar dados do controlador de domínio armazenados em cache. Se esse sinalizador for especificado, DsGetDcName não usará informações armazenadas em cache (se houver), mas executará uma nova descoberta do controlador de domínio.

Esse sinalizador não deve ser usado em condições normais, pois o uso das informações do controlador de domínio armazenado em cache tem melhores características de desempenho e ajuda a garantir que o mesmo controlador de domínio seja usado consistentemente por todos os aplicativos. Esse sinalizador deve ser usado somente depois que o aplicativo determinar que o controlador de domínio retornado por DsGetDcName (quando chamado sem esse sinalizador) não está acessível. Nesse caso, o aplicativo deve repetir a chamada DsGetDcName com esse sinalizador para garantir que as informações não utilizáveis armazenadas em cache (se houver) sejam ignoradas e que um controlador de domínio acessível seja descoberto.

DS_GC_SERVER_REQUIRED

Requer que o controlador de domínio retornado seja um servidor de catálogo global para a floresta de domínios com este domínio como raiz. Se esse sinalizador estiver definido e o parâmetro DomainName não for NULL, DomainName deverá especificar um nome de floresta. Esse sinalizador não pode ser combinado com os sinalizadores DS_PDC_REQUIRED ou DS_KDC_REQUIRED .

DS_GOOD_TIMESERV_PREFERRED

DsGetDcName tenta encontrar um controlador de domínio que seja um servidor de tempo confiável. O Serviço de Horário do Windows pode ser configurado para declarar um ou mais controladores de domínio como um servidor de tempo confiável. Para obter mais informações, consulte a documentação do Serviço de Horário do Windows . Esse sinalizador destina-se a ser usado apenas pelo Serviço de Horário do Windows.

DS_IP_REQUIRED

Esse parâmetro indica que o controlador de domínio deve ter um endereço IP. Nesse caso, DsGetDcName colocará o endereço de protocolo da Internet do controlador de domínio no membro DomainControllerAddress de DomainControllerInfo.

DS_IS_DNS_NAME

Especifica que o parâmetro DomainName é um nome DNS. Esse sinalizador não pode ser combinado com o sinalizador DS_IS_FLAT_NAME .

Especifique DS_IS_DNS_NAME ou DS_IS_FLAT_NAME. Se nenhum sinalizador for especificado, DsGetDcName poderá levar mais tempo para encontrar um controlador de domínio, pois talvez seja necessário pesquisar o estilo DNS e o nome simples.

DS_IS_FLAT_NAME

Especifica que o parâmetro DomainName é um nome simples. Esse sinalizador não pode ser combinado com o sinalizador DS_IS_DNS_NAME .

DS_KDC_REQUIRED

Requer que o controlador de domínio retornado esteja atualmente executando o serviço de Centro de Distribuição de Chaves Kerberos. Esse sinalizador não pode ser combinado com os sinalizadores DS_PDC_REQUIRED ou DS_GC_SERVER_REQUIRED .

DS_ONLY_LDAP_NEEDED

Especifica que o servidor retornado é um servidor LDAP. O servidor retornado não é necessariamente um controlador de domínio. Nenhum outro serviço está implícito para estar presente no servidor. O servidor retornado não tem necessariamente um contêiner de configuração gravável nem um contêiner de esquema gravável. O servidor retornado pode não ser necessariamente usado para criar ou modificar princípios de segurança. Esse sinalizador pode ser usado com o sinalizador DS_GC_SERVER_REQUIRED para retornar um servidor LDAP que também hospeda um servidor de catálogo global. O servidor de catálogo global retornado não é necessariamente um controlador de domínio. Nenhum outro serviço está implícito para estar presente no servidor. Se esse sinalizador for especificado, os sinalizadores DS_PDC_REQUIRED, DS_TIMESERV_REQUIRED, DS_GOOD_TIMESERV_PREFERRED, DS_DIRECTORY_SERVICES_PREFERED, DS_DIRECTORY_SERVICES_REQUIRED e DS_KDC_REQUIRED serão ignorados.

DS_PDC_REQUIRED

Requer que o controlador de domínio retornado seja um controlador de domínio primário para o domínio. Esse sinalizador não pode ser combinado com os sinalizadores DS_KDC_REQUIRED ou DS_GC_SERVER_REQUIRED .

DS_RETURN_DNS_NAME

Especifica que os nomes retornados nos membros DomainControllerName e DomainName de DomainControllerInfo devem ser nomes DNS. Se um nome DNS não estiver disponível, um erro será retornado. Esse sinalizador não pode ser especificado com o sinalizador DS_RETURN_FLAT_NAME . Esse sinalizador implica o sinalizador DS_IP_REQUIRED .

DS_RETURN_FLAT_NAME

Especifica que os nomes retornados nos membros DomainControllerName e DomainName de DomainControllerInfo devem ser nomes simples. Se um nome simples não estiver disponível, um erro será retornado. Esse sinalizador não pode ser especificado com o sinalizador DS_RETURN_DNS_NAME .

DS_TIMESERV_REQUIRED

Requer que o controlador de domínio retornado esteja atualmente executando o Serviço de Tempo do Windows.

DS_TRY_NEXTCLOSEST_SITE

Quando esse sinalizador é especificado, DsGetDcName tenta encontrar um controlador de domínio no mesmo site que o chamador. Se nenhum controlador de domínio for encontrado, ele encontrará um controlador de domínio que pode fornecer informações de topologia e chamar DsBindToISTG para obter um identificador de associação e, em seguida, chamar DsQuerySitesByCost por UDP para determinar o "próximo site mais próximo" e, finalmente, armazenar em cache o nome do site encontrado. Se nenhum controlador de domínio for encontrado nesse site, DsGetDcName retornará ao método padrão de localizar um controlador de domínio.

Se esse sinalizador for usado em conjunto com um valor não NULL no parâmetro de entrada SiteName, ERROR_INVALID_FLAGS será gerado.

Além disso, o tipo de pesquisa empregada com DS_TRY_NEXT_CLOSEST_SITE é específico do site, portanto, esse sinalizador será ignorado se for usado em conjunto com DS_PDC_REQUIRED. Por fim, DS_TRY_NEXTCLOSEST_SITE é ignorado quando usado em conjunto com DS_RETURN_FLAT_NAME porque isso usa NetBIOS para resolve o nome, mas o domínio do controlador de domínio encontrado não necessariamente corresponderá ao domínio ao qual o cliente está ingressado.

Nota Esse sinalizador está Política de Grupo habilitado. Se você habilitar a configuração de política "Próximo Site Mais Próximo", o Próximo Local dc do site mais próximo será ativado para o computador em todos os adaptadores de rede disponíveis, mas não configurados. Se você desabilitar a configuração de política, o Local dc do próximo site mais próximo não será usado por padrão para o computador em todos os adaptadores de rede disponíveis, mas não configurados. No entanto, se uma chamada ao Localizador de DC for feita usando o sinalizador DS_TRY_NEXTCLOSEST_SITE explicitamente, DsGetDcName honrará o comportamento próximo site mais próximo. Se você não definir essa configuração de política, o Próximo Local dc do site mais próximo não será usado por padrão para o computador em todos os adaptadores de rede disponíveis, mas não configurados. Se o sinalizador DS_TRY_NEXTCLOSEST_SITE for usado explicitamente, o comportamento próximo site mais próximo será usado.

DS_WRITABLE_REQUIRED

Requer que o controlador de domínio retornado seja gravável; ou seja, hospede uma cópia gravável do serviço de diretório.

DS_WEB_SERVICE_REQUIRED

Exige que o controlador de domínio retornado esteja executando atualmente o serviço Web do Active Directory.

[out] DomainControllerInfo

Ponteiro para um valor PDOMAIN_CONTROLLER_INFO que recebe um ponteiro para uma estrutura DOMAIN_CONTROLLER_INFO que contém dados sobre o controlador de domínio selecionado. Essa estrutura é alocada por DsGetDcName. O chamador deve liberar a estrutura usando a função NetApiBufferFree quando ela não for mais necessária.

Retornar valor

Se a função retornar dados do controlador de domínio, o valor retornado será ERROR_SUCCESS.

Se a função falhar, o valor retornado poderá ser um dos seguintes códigos de erro.

Comentários

A função DsGetDcName é enviada para o serviço Netlogon no computador remoto especificado por ComputerName. Se ComputerName for NULL, a função será processada no computador local.

DsGetDcName não verifica se o nome do controlador de domínio retornado é o nome de um controlador de domínio real ou catálogo global. Se a autenticação mútua for necessária, o chamador deverá executar a autenticação.

DsGetDcName não requer nenhum acesso específico ao domínio especificado. Por padrão, essa função não garante que o controlador de domínio retornado esteja disponível no momento. Em vez disso, o chamador deve tentar usar o controlador de domínio retornado. Se o controlador de domínio não estiver disponível, o chamador deverá chamar a função DsGetDcName novamente, especificando o sinalizador DS_FORCE_REDISCOVERY .

Tempo de Resposta

Ao usar DsGetDcName , lembre-se dos seguintes detalhes de tempo:

DsGetDcName faz chamadas de rede e pode levar de alguns segundos até um minuto, dependendo do tráfego de rede, topologia, carga dc e assim por diante.
NÃO é recomendável chamar DsGetDcName de uma interface do usuário ou outro thread crítico de tempo.
O Localizador dc usa a lógica otimizada para fornecer as informações de DC o mais rápido possível. Ele também usa informações armazenadas em cache no site para contatar o DC mais próximo.

Anotações sobre a stickiness do controlador de domínio

Em Active Directory Domain Services, a função de localizador do controlador de domínio é projetada para que, uma vez que um cliente encontre um controlador de domínio preferencial, o cliente não procure outro, a menos que o controlador de domínio pare de responder ou o cliente seja reiniciado. Isso é conhecido como "Stickiness do Controlador de Domínio". Como as estações de trabalho normalmente operam por meses sem um problema ou reinicialização, uma consequência não intencional desse comportamento é que, se um controlador de domínio específico ficar inativo para manutenção, todos os clientes que estavam conectados a ele mudarão suas conexões para outro controlador de domínio. Mas quando o controlador de domínio faz backup, nenhum cliente se reconecta a ele porque os clientes não reiniciam com muita frequência. Isso pode causar problemas de balanceamento de carga.

Anteriormente, a solução mais comum para esse problema era implantar um script em cada computador cliente que chama periodicamente DsGetDcName usando o DS_FORCE_REDISCOVERY sinalizador . Essa foi uma solução um pouco complicada, portanto, o Windows Server 2008 e o Windows Vista introduziram um novo mecanismo que causava problemas com a adesão do controlador de domínio.

Sempre que DsGetDcName recupera um nome de controlador de domínio de seu cache, ele verifica se essa entrada armazenada em cache expirou e, nesse caso, descarta o nome do controlador de domínio e tenta redescobrir um nome de controlador de domínio. O tempo de vida de uma entrada armazenada em cache é controlado pelo valor nas chaves do Registro a seguir

HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Serviços\Netlogon\Parâmetros\ForceRediscoveryInterval

HKEY_LOCAL_MACHINE\Software\Políticas\Microsoft\Netlogon\Parâmetros\ForceRediscoveryInterval

Os valores nessas chaves do Registro são do tipo REG_DWORD. Eles especificam o comprimento em segundos antes que DsGetDcName tente redescobrir o nome do controlador de domínio. O valor padrão é 43200 segundos (12 horas). Se o valor da entrada do Registro ForceRediscoveryInterval estiver definido como 0, o cliente sempre executará redescoberta. Se o valor for definido como 4294967295, o cache nunca expirará e o controlador de domínio armazenado em cache continuará a ser usado. Recomendamos que você não defina a entrada do Registro ForceRediscoveryInterval como um valor inferior a 3600 segundos (60 minutos).

Nota As configurações do Registro de ForceRediscoveryInterval são habilitadas para a política de grupo. Se você desabilitar a configuração de política, o Force Rediscovery será usado por padrão para o computador a cada intervalo de 12 horas. Se você não definir essa configuração de política, o Force Rediscovery será usado por padrão para o computador a cada intervalo de 12 horas, a menos que a configuração do computador local no Registro seja um valor diferente.

Observe que, se o sinalizador DS_BACKGROUND_ONLY for especificado, DsGetDcName nunca tentará redescobrir o nome do controlador de domínio, uma vez que o ponto desse sinalizador é forçar DsGetDcName a usar o nome do controlador de domínio armazenado em cache mesmo que ele tenha expirado.

Rastreamento ETW em DsGetDcName

Para ativar o Rastreamento ETW para DsGetDcName, crie a seguinte chave do Registro:

HKEY_LOCAL_MACHINE\Sistema\Currentcontrolset\Serviços\DCLocator\Rastreamento

A chave terá uma estrutura da seguinte maneira:

String ProcessName
  DWORD  PID <optional>

ProcessName deve ser o nome completo, incluindo a extensão do processo para o qual você deseja obter informações de rastreamento. O PID só é necessário quando existem vários processos com o mesmo nome. Se ele for definido, somente o processo com esse PID será habilitado para rastreamento. Não é possível rastrear apenas 2 de 3 (ou mais) processos com o mesmo nome. Você pode habilitar uma instância ou todas as instâncias (quando várias instâncias com o mesmo nome de processo existirem e o PID não for especificado, todas as instâncias serão habilitadas para rastreamento).

Por exemplo, isso rastrearia todas as instâncias de App1.exe e App2.exe, mas apenas a instância de App3.exe que tem um PID de 999:

App1.exe 
App2.exe
App3.exe
     PID 999

Execute o seguinte comando para iniciar a sessão de rastreamento:

tracelog.exe -start <sessionname> -guid #cfaa5446-c6c4-4f5c-866f-31c9b55b962d -f <filename> -flag <traceFlags>

sessionname é o nome fornecido para a sessão de rastreamento. O guid para o provedor de rastreamento DCLocator é "cfaaa5446-c6c4-4f5c-866f-31c9b55b962d". filename é o nome do arquivo de log no qual os eventos são gravados. traceFlags é um ou mais dos seguintes sinalizadores que significam quais áreas rastrear:

Sinalizador	Valor hexadecimais	Descrição
DCLOCATOR_MISC	0x00000002	Depuração diversa
DCLOCATOR_MAILSLOT	0x00000010	Mensagens do Maillot
DCLOCATOR_SITE	0x00000020	Sites
DCLOCATOR_CRITICAL	0x00000100	Erros importantes
DCLOCATOR_SESSION_SETUP	0x00000200	Manutenção de domínio confiável
DCLOCATOR_DNS	0x00004000	Registro de nome
DCLOCATOR_DNS_MORE	0x00020000	Registro de nome detalhado
DCLOCATOR_MAILBOX_TEXT	0x02000000	Mensagens detalhadas da caixa de correio
DCLOCATOR_SITE_MORE	0x08000000	Sites detalhados

Execute o seguinte comando para interromper a sessão de rastreamento:

tracelog.exe -stop <sessionname>

sessionname é o mesmo nome que o nome usado ao iniciar a sessão.

Nota A chave do Registro para o processo que está sendo rastreado deve estar presente no registro no momento em que a sessão de rastreamento for iniciada. Quando a sessão for iniciada, o processo verificará se deve ou não gerar mensagens de rastreamento (com base na presença ou ausência de uma chave do Registro para esse nome de processo e PID opcional). O processo verifica o registro somente no início da sessão. As alterações no registro que ocorrerem depois disso não terão nenhum efeito sobre o rastreamento.

Observação

O cabeçalho dsgetdc.h define DsGetDcName 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 Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	dsgetdc.h
Biblioteca	NetApi32.lib
DLL	NetApi32.dll