função ldap_open (winldap.h)

Artigo
08/27/2023

[ldap_open está disponível para uso nos sistemas operacionais especificados na seção Requisitos; no entanto, não é recomendável. Em vez disso, use ldap_init.]

A função ldap_open cria e inicializa um bloco de conexão e abre a conexão com um servidor LDAP.

Sintaxe

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

Parâmetros

[in] HostName

Um ponteiro para uma cadeia de caracteres terminada em nulo. Um nome de domínio, uma lista de nomes de host ou cadeias de caracteres pontilhadas que representam o endereço IP dos hosts do servidor LDAP. Use um único espaço para separar os nomes de host na lista. Cada nome de host na lista pode ser seguido por um número de porta. O número da porta opcional é separado do próprio host com dois-pontos (:). O tempo de execução LDAP tenta conexão com os hosts na ordem listada, parando quando uma conexão bem-sucedida é feita. Lembre-se de que apenas ldap_open tenta fazer a conexão antes de retornar ao chamador. A função ldap_init não se conecta ao servidor LDAP.

[in] PortNumber

Contém o número da porta TCP à qual se conectar. A porta LDAP padrão, 389, pode ser obtida fornecendo a constante LDAP_PORT. Se um nome de host incluir um número de porta, esse parâmetro será ignorado.

Valor retornado

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. Libere o identificador de sessão, quando não for mais necessário, com uma chamada para ldap_unbind.

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

Comentários

Chame ldap_open para criar um bloco de conexão para um servidor LDAP. O HostName pode ser NULL , caso em que o tempo de execução tenta localizar o servidor LDAP padrão. Os nomes de host são testados 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.

Se o HostName tiver sido definido como NULL ou o nome de domínio, a reconexão automática se aplicará. Se o CONTROLADOR de domínio conectado parar de funcionar por algum motivo durante o tempo de vida da conexão, o LDAP se reconectará automaticamente a outro controlador de domínio 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.

O servidor LDAP padrão é uma opção específica da Microsoft quando você usa LDAP_OPT_HOST_NAME. Essa opção especifica o nome do host do servidor LDAP padrão e retorna o nome do host do servidor em Unicode ou ANSI, dependendo do uso de ldap_get_optionW ou ldap_get_optionA, respectivamente.

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

A função ldap_open 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 subsequentes durante a sessão.

Multithreading: as chamadas para ldap_open são thread-safe.

Observeldap_open é preterido pelo RFC LDAP atual porque abre imediatamente uma sessão para o controlador de domínio sem dar ao aplicativo de chamada a chance de configurar qualquer opção de sessão, por exemplo (e o mais importante) opções de sessão relacionadas à segurança. Os usuários são incentivados a usar ldap_init como o método preferencial de inicialização de uma sessão LDAP.

Requisitos


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