ldap_init, fonction (winldap.h)
La fonction ldap_init initialise une session avec un serveur LDAP.
Syntaxe
WINLDAPAPI LDAP *LDAPAPI ldap_init(
[in] PSTR HostName,
[in] ULONG PortNumber
);
Paramètres
[in] HostName
Pointeur vers une chaîne terminée par null qui contient un nom de domaine ou une liste séparée par des espaces de noms d’hôtes ou de chaînes en pointillés qui représentent l’adresse IP des hôtes exécutant un serveur LDAP auquel se connecter. Chaque nom d’hôte de la liste peut inclure un numéro de port facultatif qui est séparé de l’hôte lui-même par un signe deux-points (:). Pour plus d’informations sur l’utilisation de l’option LDAP_OPT_AREC_EXCLUSIVE lors de la connexion à des serveurs Active Directory, consultez la section Remarques.
[in] PortNumber
Contient le numéro de port TCP auquel se connecter. Définissez sur LDAP_PORT pour obtenir le port par défaut, 389. Ce paramètre est ignoré si un nom d’hôte inclut un numéro de port.
Valeur retournée
Si la fonction réussit, elle retourne un handle de session, sous la forme d’un pointeur vers une structure de données LDAP . Le handle de session doit être libéré avec un appel à ldap_unbind lorsqu’il n’est plus nécessaire.
Si la fonction échoue, elle retourne NULL. Utilisez LdapGetLastError pour récupérer le code d’erreur.
Remarques
Appelez ldap_init pour créer un bloc de connexion à un serveur LDAP. Contrairement à ldap_open, un appel à ldap_init n’ouvre pas la connexion. Vous pouvez appeler ldap_connect explicitement pour que la bibliothèque contacte le serveur. Cela est utile lorsque vous souhaitez spécifier un délai d’expiration local, auquel cas vous appelez ldap_set_option, avec le bloc de connexion de ldap_init, avant d’appeler ldap_connect. En règle générale, toutefois, cet appel est inutile, car la première fonction d’opération qui nécessite une connexion ouverte appelle ldap_connect en interne si elle n’a pas été appelée.
La fonction alloue une structure de données LDAP pour gérer les données d’état de la session et retourne un handle à cette structure. Passez ce handle aux appels de fonction LDAP pendant la session.
Le paramètre HostName peut être NULL, auquel cas l’exécution tente de trouver le serveur LDAP « par défaut ». Lorsque ldap_connect est appelé, les hôtes sont tentés dans l’ordre indiqué, en s’arrêtant avec la première connexion réussie. Pour les serveurs Active Directory, la fonction DsGetDcName peut être utilisée pour obtenir le nom du serveur, qui peut ensuite être passé en tant que paramètre HostName au lieu d’utiliser NULL.
Même lorsque la fonction ldap_set_option est utilisée pour définir l’option LDAP_OPT_GETDSNAME_FLAGS , qui spécifie à son tour les indicateurs qui seront passés à DsGetDCName pour découvrir à quel contrôleur de domaine se connecter. Le client LDAP transmet également l’indicateur DS_ONLY_LDAP_NEEDED à DsGetDCName en plus des indicateurs que LDAP_OPT_GETDSNAME_FLAGS spécifie.
Si null est passé pour le paramètre HostName et que l’ordinateur appelant est membre d’un domaine Active Directory, le runtime recherche un contrôleur de domaine dans le domaine dans lequel l’ordinateur actuel est membre lors de la tentative de connexion.
Si NULL est passé pour le paramètre HostName et que l’ordinateur appelant est un contrôleur de domaine d’un domaine Active Directory, le runtime bascule NULL avec 127.0.0.1 et se connecte à l’ordinateur local à l’aide d’un bouclage lors de la tentative de connexion.
Si un nom de domaine Active Directory est passé pour le paramètre HostName , ldap_init trouverez le serveur LDAP « par défaut » dans ce domaine.
Si hostName a été défini sur NULL ou le nom de domaine, la reconnexion automatique s’applique. Si le contrôleur de domaine connecté cesse de fonctionner pour une raison quelconque pendant la durée de vie de la connexion, LDAP se reconnecte automatiquement à un autre contrôleur de domaine dans le domaine spécifié. Ce comportement peut être désactivé ou activé à l’aide de l’option LDAP_OPT_AUTO_RECONNECT session, qui est activée par défaut.
Si un nom de serveur DNS Active Directory est passé pour le paramètre HostName , ldap_set_option devez être appelée pour définir l’indicateur LDAP_OPT_AREC_EXCLUSIVE sur avant d’appeler une fonction LDAP qui crée la connexion réelle. Cela force une recherche d’enregistrement A et contourne toute recherche d’enregistrement SRV lors de la résolution du nom d’hôte. Dans le cas d’une filiale disposant d’une connexion d’accès à distance, l’utilisation de la recherche A-Record peut éviter de forcer la numérotation à interroger un serveur DNS distant pour les enregistrements SRV lors de la résolution des noms.
Si un numéro de port de catalogue global est passé à ldap_init comme argument, le nom d’hôte transmis pour ce numéro de port doit être le nom de la forêt pour l’appel sous-jacent à DsGetDcName() pour trouver correctement le gc dans l’entreprise.
Multithreading : un appel à ldap_init est thread-safe.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista |
| Serveur minimal pris en charge | Windows Server 2008 |
| Plateforme cible | Windows |
| En-tête | winldap.h |
| Bibliothèque | Wldap32.lib |
| DLL | Wldap32.dll |