Função DsGetDcOpenA (dsgetdc.h)

Artigo
08/23/2023

A função DsGetDcOpen abre uma nova operação de enumeração do controlador de domínio.

Sintaxe

DSGETDCAPI DWORD DsGetDcOpenA(
  [in]           LPCSTR  DnsName,
  [in]           ULONG   OptionFlags,
  [in, optional] LPCSTR  SiteName,
  [in, optional] GUID    *DomainGuid,
  [in, optional] LPCSTR  DnsForestName,
  [in]           ULONG   DcFlags,
  [out]          PHANDLE RetGetDcContext
);

Parâmetros

[in] DnsName

Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome DNS (sistema de nomenclatura de domínio) do domínio para o qual enumerar os controladores de domínio. Esse parâmetro não pode ser NULL.

[in] OptionFlags

Contém um conjunto de sinalizadores que modificam o comportamento da função. Isso pode ser zero ou uma combinação de um ou mais dos valores a seguir.

DS_ONLY_DO_SITE_NAME

Somente controladores de domínio específicos do site são enumerados.

DS_NOTIFY_AFTER_SITE_RECORDS

A função DsGetDcNext retornará o valor ERROR_FILEMARK_DETECTED depois que todos os controladores de domínio específicos do site forem recuperados. DsGetDcNext enumerará o segundo grupo, que contém todos os controladores de domínio no domínio, incluindo os controladores de domínio específicos do site contidos no primeiro grupo.

[in, optional] SiteName

Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome do site em que o cliente está. Esse parâmetro é opcional e pode ser NULL.

[in, optional] DomainGuid

Ponteiro para um valor GUID que contém o identificador do domínio especificado por DnsName. Esse identificador é usado para lidar com o caso de um domínio renomeado. Se esse valor for especificado e o domínio especificado em DnsName for renomeado, essa função tentará enumerar controladores de domínio no domínio que contém o identificador especificado. Esse parâmetro é opcional e pode ser NULL.

[in, optional] DnsForestName

Ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome da floresta que contém o domínio DnsName . Esse valor é usado em conjunto com DomainGuid para enumerar os controladores de domínio se o domínio tiver sido renomeado. Esse parâmetro é opcional e pode ser NULL.

[in] DcFlags

Contém um conjunto de sinalizadores que identificam o tipo de controladores de domínio a serem enumerados. Isso pode ser zero ou uma combinação de um ou mais dos valores a seguir.

DS_FORCE_REDISCOVERY

Força os dados do controlador de domínio armazenados em cache a serem ignorados. Quando esse sinalizador não é especificado, DsGetDcOpen obtém a enumeração do controlador de domínio dos dados do controlador de domínio armazenados em cache.

DS_GC_SERVER_REQUIRED

Requer que os controladores de domínio enumerados sejam servidores de catálogo global para a floresta de domínios com esse domínio como a raiz. Esse sinalizador não pode ser combinado com o sinalizador DS_PDC_REQUIRED .

DS_KDC_REQUIRED

Requer que os controladores de domínio enumerados estejam atualmente executando o serviço do 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 os servidores enumerados são servidores LDAP. Os servidores não são necessariamente controladores de domínio. Nenhum outro serviço está implícito para estar presente em cada servidor enumerado. Os servidores não têm necessariamente um contêiner de configuração gravável nem um contêiner de esquema gravável. Os servidores podem não ser necessariamente usados para criar ou modificar princípios de segurança. Esse sinalizador pode ser usado com o sinalizador DS_GC_SERVER_REQUIRED para enumerar servidores LDAP que também hospedam um servidor de catálogo global. Nesse caso, os servidores de catálogo global enumerados não são necessariamente controladores de domínio e outros serviços estão implícitos para estarem presentes em cada 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 os controladores de domínio enumerados sejam os controladores de domínio primários para o domínio. Esse sinalizador não pode ser combinado com o sinalizador DS_GC_SERVER_REQUIRED .

[out] RetGetDcContext

Ponteiro para um valor HANDLE que recebe o identificador de contexto de enumeração do controlador de domínio. Esse identificador é usado com a função DsGetDcNext para identificar a operação de enumeração do controlador de domínio. Esse identificador é passado para DsGetDcClose para fechar a operação de enumeração do controlador de domínio.

Valor retornado

Retorna ERROR_SUCCESS se tiver êxito ou um erro Win32 ou RPC caso contrário. Os valores de erro possíveis incluem o seguinte.

Comentários

Observação

O cabeçalho dsgetdc.h define DsGetDcOpen 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


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