función ldap_init (winldap.h)

Artículo
03/13/2024

La función ldap_init inicializa una sesión con un servidor LDAP.

Sintaxis

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

Parámetros

[in] HostName

Puntero a una cadena terminada en null que contiene un nombre de dominio o una lista separada por espacios de nombres de host o cadenas de puntos que representan la dirección IP de los hosts que ejecutan un servidor LDAP al que se va a conectar. Cada nombre de host de la lista puede incluir un número de puerto opcional que está separado del propio host con dos puntos (:). Para obtener más información sobre el uso de la opción LDAP_OPT_AREC_EXCLUSIVE al conectarse a servidores de Active Directory, vea la sección Comentarios.

[in] PortNumber

Contiene el número de puerto TCP al que se va a conectar. Establezca en LDAP_PORT para obtener el puerto predeterminado, 389. Este parámetro se omite si un nombre de host incluye un número de puerto.

Valor devuelto

Si la función se ejecuta correctamente, devuelve un identificador de sesión, en forma de puntero a una estructura de datos LDAP . El identificador de sesión debe liberarse con una llamada a ldap_unbind cuando ya no sea necesario.

Si se produce un error en la función, devuelve NULL. Use LdapGetLastError para recuperar el código de error.

Comentarios

Llame a ldap_init para crear un bloque de conexión en un servidor LDAP. A diferencia de ldap_open, una llamada a ldap_init no abre la conexión. Puede llamar a ldap_connect explícitamente para que la biblioteca se comunique con el servidor. Esto resulta útil cuando desea especificar un tiempo de espera local en cuyo caso llamaría a ldap_set_option, con el bloque de conexión de ldap_init, antes de llamar a ldap_connect. Sin embargo, esta llamada no es necesaria porque la primera función de operación que requiere una conexión abierta llama a ldap_connect internamente si no se ha llamado.

La función asigna una estructura de datos LDAP para mantener los datos de estado de la sesión y devuelve un identificador a esta estructura. Pase este identificador a las llamadas de función LDAP durante la sesión.

El parámetro HostName puede ser NULL, en cuyo caso el tiempo de ejecución intenta encontrar el servidor LDAP "predeterminado". Cuando se llama a ldap_connect , los hosts se intentan en el orden indicado, deteniendo con la primera conexión correcta. En el caso de los servidores de Active Directory, la función DsGetDcName se puede usar para obtener el nombre del servidor, que luego se puede pasar como parámetro HostName en lugar de usar NULL.

Incluso cuando la función ldap_set_option se usa para establecer la opción LDAP_OPT_GETDSNAME_FLAGS , que a su vez especifica las marcas que se pasarán a DsGetDCName para detectar a qué controlador de dominio se va a conectar. El cliente LDAP también pasa la marca DS_ONLY_LDAP_NEEDED a DsGetDCName además de las marcas que LDAP_OPT_GETDSNAME_FLAGS especifica.

Si se pasa NULL para el parámetro HostName y el equipo que realiza la llamada es miembro de un dominio de Active Directory, el tiempo de ejecución buscará un controlador de dominio en el dominio en el que el equipo actual es miembro al intentar conectarse.

Si se pasa NULL para el parámetro HostName y el equipo que realiza la llamada es un controlador de dominio de Active Directory, el runtime cambiará NULL con 127.0.0.1 y se conectará al equipo local mediante bucle invertido al intentar conectarse.

Si se pasa un nombre de dominio de Active Directory para el parámetro HostName , ldap_init encontrará el servidor LDAP "predeterminado" en ese dominio.

Si hostName se estableció en NULL o en el nombre de dominio, se aplica la reconexión automática. Si el controlador de dominio conectado deja de funcionar por algún motivo durante la duración de la conexión, LDAP se volverá a conectar automáticamente a otro controlador de dominio en el dominio especificado. Este comportamiento se puede desactivar o activar mediante la opción LDAP_OPT_AUTO_RECONNECT sesión, que está activada de forma predeterminada.

Si se pasa un nombre de servidor DNS de Active Directory para el parámetro HostName , se debe llamar a ldap_set_option para establecer la marca de LDAP_OPT_AREC_EXCLUSIVE en antes de llamar a cualquier función LDAP que cree la conexión real. Esto fuerza una búsqueda de registros A y omite cualquier búsqueda de registros SRV al resolver el nombre de host. En el caso de una sucursal con una conexión de acceso telefónico, el uso de la búsqueda A-Record puede evitar forzar el marcado para consultar un servidor DNS remoto para los registros SRV al resolver nombres.

Si se pasa un número de puerto del catálogo global a ldap_init como uno de los argumentos, el nombre de host pasado para ese número de puerto debe ser el nombre del bosque de la llamada subyacente a DsGetDcName() para encontrar correctamente el GC en la empresa.

Multithreading: una llamada a ldap_init es segura para subprocesos.

Notaldap_init es el método preferido para inicializar una sesión LDAP. El uso de ldap_open está en desuso en gran medida por el RFC LDAP actual, ya que impide el uso de la configuración de cualquier opción de sesión.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	winldap.h
Library	Wldap32.lib
Archivo DLL	Wldap32.dll