Função DsGetDcNameW (dsgetdc.h)
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.
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
e
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).
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.
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 |