função ldap_init (winldap.h)

Artigo
08/27/2023

A função ldap_init inicializa uma sessão com um servidor LDAP.

Sintaxe

WINLDAPAPI LDAP *LDAPAPI ldap_init(
  [in] PSTR  HostName,
  [in] ULONG PortNumber
);

Parâmetros

[in] HostName

Um ponteiro para uma cadeia de caracteres terminada em nulo que contém um nome de domínio ou uma lista separada por espaço de nomes de host ou cadeias de caracteres pontilhadas que representam o endereço IP dos hosts que executam um servidor LDAP ao qual se conectar. Cada nome de host na lista pode incluir um número de porta opcional que é separado do próprio host com dois-pontos (:). Para obter mais informações sobre o uso da opção LDAP_OPT_AREC_EXCLUSIVE ao se conectar a servidores do Active Directory, consulte a seção Comentários.

[in] PortNumber

Contém o número da porta TCP ao qual se conectar. Defina como LDAP_PORT para obter a porta padrão, 389. Esse parâmetro será ignorado se um nome de host incluir um número de porta.

Retornar valor

Se a função for bem-sucedida, ela retornará um identificador de sessão, na forma de um ponteiro para uma estrutura de dados LDAP . O identificador de sessão deve ser liberado com uma chamada para ldap_unbind quando não for mais necessário.

Se a função falhar, ela retornará NULL. Use LdapGetLastError para recuperar o código de erro.

Comentários

Chame ldap_init para criar um bloco de conexão para um servidor LDAP. Ao contrário de ldap_open, uma chamada para ldap_init não abre a conexão. Você pode chamar ldap_connect explicitamente para que a biblioteca entre em contato com o servidor. Isso é útil quando você deseja especificar um tempo limite local nesse caso, você chamaria ldap_set_option, com o bloco de conexão de ldap_init, antes de chamar ldap_connect. Normalmente, no entanto, essa chamada é desnecessária porque a primeira função de operação que requer uma conexão aberta chama ldap_connect internamente se ela não tiver sido chamada.

A função aloca uma estrutura de dados LDAP para manter dados de estado para a sessão e retorna um identificador para essa estrutura. Passe esse identificador para chamadas de função LDAP durante a sessão.

O parâmetro HostName pode ser NULL, nesse caso, o tempo de execução tenta localizar o servidor LDAP "padrão". Quando ldap_connect é chamado, os hosts são tentados na ordem listada, parando com a primeira conexão bem-sucedida. Para servidores do Active Directory, a função DsGetDcName pode ser usada para obter o nome do servidor, que pode ser passado como o parâmetro HostName em vez de usar NULL.

Mesmo quando a função ldap_set_option é usada para definir a opção LDAP_OPT_GETDSNAME_FLAGS , que, por sua vez, especifica os sinalizadores que serão passados para DsGetDCName para descobrir a qual DC se conectar. O cliente LDAP também passa o sinalizador DS_ONLY_LDAP_NEEDED para DsGetDCName , além dos sinalizadores que LDAP_OPT_GETDSNAME_FLAGS especifica.

Se NULL for passado para o parâmetro HostName e o computador de chamada for membro de um domínio do Active Directory, o runtime procurará um DC no domínio no qual o computador atual é membro ao tentar se conectar.

Se NULL for passado para o parâmetro HostName e o computador de chamada for um DC de um domínio do Active Directory, o runtime alternará NULL com 127.0.0.1 e se conectará ao computador local usando loopback ao tentar se conectar.

Se um nome de domínio do Active Directory for passado para o parâmetro HostName , ldap_init encontrará o servidor LDAP "padrão" nesse domínio.

Se o HostName foi definido como NULL ou o nome de domínio, a reconexão automática se aplica. Se o DC conectado parar de funcionar por algum motivo durante o tempo de vida da conexão, o LDAP se reconectará automaticamente a outro DC no domínio especificado. Esse comportamento pode ser desativado ou ativado usando a opção de sessão LDAP_OPT_AUTO_RECONNECT , que está ativada por padrão.

Se um nome de servidor DNS do Active Directory for passado para o parâmetro HostName , ldap_set_option deverá ser chamado para definir o sinalizador LDAP_OPT_AREC_EXCLUSIVE antes de chamar qualquer função LDAP que crie a conexão real. Isso força uma pesquisa de registro A e ignora qualquer pesquisa de registro SRV ao resolver o nome do host. No caso de uma filial com uma conexão discada, o uso da pesquisa A-Record pode evitar forçar a discagem a consultar um servidor DNS remoto para registros SRV ao resolver nomes.

Se um número de porta do Catálogo Global for passado para ldap_init como um dos argumentos, o HostName passado para esse número de porta deverá ser o nome da floresta para que a chamada subjacente a DsGetDcName() localize corretamente o GC na empresa.

Multithreading: uma chamada para ldap_init é thread-safe.

Observeldap_init é o método preferencial de inicializar uma sessão LDAP. O uso de ldap_open é fortemente preterido pelo RFC LDAP atual porque impede o uso da configuração de todas as opções de sessã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	winldap.h
Biblioteca	Wldap32.lib
DLL	Wldap32.dll