ldap_open, fonction (winldap.h)
[ldap_open est disponible pour une utilisation dans les systèmes d’exploitation spécifiés dans la section Configuration requise ; toutefois, il n’est pas recommandé. Utilisez plutôt ldap_init.]
La fonction ldap_open crée et initialise un bloc de connexion, puis ouvre la connexion à un serveur LDAP.
Syntaxe
WINLDAPAPI LDAP *LDAPAPI ldap_open(
[in] PSTR HostName,
[in] ULONG PortNumber
);
Paramètres
[in] HostName
Pointeur vers une chaîne terminée par null. Un nom de domaine, une liste de noms d’hôtes ou des chaînes en pointillés qui représentent l’adresse IP des hôtes de serveur LDAP. Utilisez un espace unique pour séparer les noms d’hôtes dans la liste. Chaque nom d’hôte de la liste peut être suivi d’un numéro de port. Le numéro de port facultatif est séparé de l’hôte lui-même par un signe deux-points (:). L’exécution LDAP tente la connexion avec les hôtes dans l’ordre indiqué, s’arrêtant lorsqu’une connexion réussie est établie. N’oubliez pas que seule ldap_open tente d’établir la connexion avant de revenir à l’appelant. La fonction ldap_init ne se connecte pas au serveur LDAP.
[in] PortNumber
Contient le numéro de port TCP auquel se connecter. Le port LDAP par défaut, 389, peut être obtenu en fournissant la constante LDAP_PORT. Si un nom d’hôte inclut un numéro de port, ce paramètre est ignoré.
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. Libérez le handle de session, lorsqu’il n’est plus nécessaire, avec un appel à ldap_unbind.
Si la fonction échoue, elle retourne NULL. Utilisez la fonction LdapGetLastError pour récupérer le code d’erreur.
Remarques
Appelez ldap_open pour créer un bloc de connexion à un serveur LDAP. Le hostName peut être NULL , auquel cas l’exécution tente de trouver le serveur LDAP par défaut. Les noms d’hôte sont essayés dans l’ordre indiqué, en 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.
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.
Le serveur LDAP par défaut est une option spécifique à Microsoft lorsque vous utilisez LDAP_OPT_HOST_NAME. Cette option spécifie le nom d’hôte du serveur LDAP par défaut et retourne le nom d’hôte du serveur en Unicode ou ANSI, sous réserve de l’utilisation de ldap_get_optionW ou de ldap_get_optionA, respectivement.
Si un numéro de port de catalogue global est passé à ldap_open 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.
La fonction ldap_open alloue une structure de données LDAP pour conserver les données d’état de la session et retourne un handle à cette structure. Passez ce handle aux appels de fonction LDAP suivants au cours de la session.
Multithreading : les appels à ldap_open sont thread-safe.
Configuration requise
| 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 |