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 sinalizadores de
Se o parâmetro sinalizadores
Se
[in] DomainGuid
Ponteiro para uma estrutura de guid de
[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 ao 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 valores a seguir.
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 encontrar 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 não diretório. No entanto, DsGetDcName retorna apenas um controlador de domínio de serviço não diretório após a tentativa de localizar um controlador de domínio de 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 o 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 de 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 determina 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 armazenadas em cache não utilizadas (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 esse domínio como a raiz. Se esse sinalizador estiver definido e o parâmetro DomainName não estiver 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 Tempo 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
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 membro do 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 dos sinalizadores 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 executando o serviço do Centro de Distribuição de Chaves Kerberos no momento. 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
DS_PDC_REQUIRED
Requer que o controlador de domínio retornado seja o 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 no DomainControllerName e domainname membros 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 no DomainControllerName e Membros do DomainName do 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 executando o Serviço de Tempo do Windows no momento.
DS_TRY_NEXTCLOSEST_SITE
Quando esse sinalizador é especificado, DsGetDcName tenta localizar 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 sobre UDP para determinar o "próximo site mais próximo" e, por fim, 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á gerada.
Além disso, o tipo de pesquisa empregada com DS_TRY_NEXT_CLOSEST_SITE é específico do site, portanto, esse sinalizador será ignorado se ele 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 resolver 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
Requer que o controlador de domínio retornado esteja executando o serviço Web do Active Directory no momento.
[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.
Valor de retorno
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.
Observações
A função DsGetDcName
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 exige 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 esteja ciente 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, da topologia, da carga de DC e assim por diante.
- Não é recomendável chamar DsGetDcName de uma interface do usuário ou de outro thread crítico de tempo.
- O Localizador de 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
No 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 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 sinalizador DS_FORCE_REDISCOVERY. 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 atividade 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 seguintes chaves do Registro
HKEY_LOCAL_MACHINE\\CurrentControlSet\Services\Netlogon\Parameters\ForceRediscoveryInterval
e
Políticas de
Os valores nessas chaves do Registro são do tipo REG_DWORD. Eles especificam o comprimento em segundos antes de DsGetDcName deve tentar redescobrir o nome do controlador de domínio. O valor padrão é 43200 segundos (12 horas). Se o valor do ForceRediscoveryInterval entrada do Registro for 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 para um valor menor que 3600 segundos (60 minutos).
rastreamento ETW no DsGetDcName
Para ativar de rastreamento etw para DsGetDcName, crie a seguinte chave do Registro:HKEY_LOCAL_MACHINE\\\Services\DCLocator\Tracing
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. pid só é necessário quando existem vários processos com o mesmo nome. Se 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-31c9b555b962d -f <filename> -flag <traceFlags>
nome de sessão é o nome fornecido para a sessão de rastreamento. O guid para o provedor de rastreamento DCLocator é "cfaaa5446-c6c4-4f5c-866f-31c9b55b962d". nome de arquivo é 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:
| Bandeira | Valor hex | Descrição |
|---|---|---|
| DCLOCATOR_MISC | 0x00000002 | Depuração diversa |
| DCLOCATOR_MAILSLOT | 0x00000010 | Mensagens de Emaillot |
| 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 <> de nome de sessão
nome de sessão é o mesmo nome que você usou ao iniciar a sessão.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows Vista |
| servidor com suporte mínimo | Windows Server 2008 |
| da Plataforma de Destino |
Windows |
| cabeçalho | dsgetdc.h |
| biblioteca | NetApi32.lib |
| de DLL |
NetApi32.dll |
Consulte também
Funções de serviço de diretório
guid do
NetApiBufferFree