ldap_search_ext, fonction (winldap.h)
La fonction ldap_search_ext recherche le répertoire LDAP et retourne un ensemble d’attributs demandé pour chaque entrée correspondante.
Syntaxe
WINLDAPAPI ULONG LDAPAPI ldap_search_ext(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[in] PLDAPControlA *ServerControls,
[in] PLDAPControlA *ClientControls,
[in] ULONG TimeLimit,
[in] ULONG SizeLimit,
[out] ULONG *MessageNumber
);
Paramètres
[in] ld
Handle de session.
[in] base
Pointeur vers une chaîne terminée par un caractère Null qui contient le nom unique de l’entrée à partir de laquelle commencer la recherche.
[in] scope
Spécifie l’une des valeurs suivantes pour indiquer l’étendue de recherche.
LDAP_SCOPE_BASE
Recherchez l’entrée de base uniquement.
LDAP_SCOPE_ONELEVEL
Recherchez toutes les entrées du premier niveau sous l’entrée de base, à l’exclusion de l’entrée de base.
LDAP_SCOPE_SUBTREE
Recherchez l’entrée de base et toutes les entrées de l’arborescence sous la base.
[in] filter
Pointeur vers une chaîne terminée par null qui spécifie le filtre de recherche. Pour plus d’informations, consultez Syntaxe des filtres de recherche.
[in] attrs
Tableau de chaînes terminées par null qui indiquent les attributs à retourner pour chaque entrée correspondante. Pour récupérer tous les attributs disponibles, transmettez NULL.
[in] attrsonly
Valeur booléenne qui doit être égale à zéro si les types d’attributs et les valeurs doivent être retournés, une valeur différente de zéro si seuls les types doivent être retournés.
[in] ServerControls
Liste des contrôles serveur LDAP.
[in] ClientControls
Liste des contrôles clients.
[in] TimeLimit
Spécifie à la fois la valeur du délai d’attente de recherche local en secondes et la limite de temps d’opération envoyée au serveur dans la demande de recherche.
[in] SizeLimit
Limite du nombre d’entrées à retourner à partir de la recherche. La valeur 0 indique l'absence de limite.
[out] MessageNumber
ID du message de demande.
Valeur retournée
Si la fonction réussit, la valeur de retour est LDAP_SUCCESS.
Si la fonction échoue, elle retourne un code d'erreur. Pour plus d’informations, consultez Valeurs de retour.
Remarques
La fonction ldap_search_ext lance une opération de recherche asynchrone. Les paramètres et les effets de ldap_search_ext incluent ceux de ldap_search. La fonction étendue inclut des paramètres supplémentaires pour prendre en charge les contrôles client et serveur et la sécurité des threads, et pour spécifier des limites de taille et de temps pour chaque opération de recherche.
Utilisez la fonction ldap_set_option avec le handle de session ld pour définir l’option LDAP_OPT_DEREF qui détermine la façon dont la recherche est effectuée. Pour plus d’informations, consultez Options de session. Deux autres options de session, LDAP_OPT_SIZELIMIT et LDAP_OPT_TIMELIMIT, sont ignorées au profit des paramètres SizeLimit et TimeLimit dans cette fonction.
Si l’opération réussit, ldap_search_ext transmet l’ID de message à l’appelant en tant que paramètre lorsque l’opération est retournée avec succès. Appelez ldap_result avec l’ID de message pour obtenir le résultat de l’opération.
Une application cliente LDAP qui doit contrôler la vitesse à laquelle les résultats sont retournés peut spécifier la demande de recherche pour fournir un contrôle de résultats paginés dont la taille est définie sur la taille de page souhaitée et le cookie défini sur la chaîne de longueur nulle. La taille de page spécifiée peut être supérieure à zéro et inférieure à la valeur SizeLimit spécifiée dans la demande de recherche.
Si la taille de la page est supérieure ou égale à l’option de valeur SizeLimit décrite dans Options de session, le serveur doit ignorer le contrôle, car la demande peut être satisfaite dans une seule page. Si le serveur ne prend pas en charge ce contrôle, le serveur doit retourner une erreur d’extension critique non prise en charge si le client l’a demandée comme critique. Sinon, le serveur doit ignorer le contrôle. Le reste de cette section suppose que le serveur n’ignore pas le contrôle des résultats paginés du client.
Le client envoie au serveur une demande de recherche avec le contrôle de résultats paginés simple, ainsi qu’une clé d’énumération précédente vide, également appelée « cookie », et la taille de page initiale. Le serveur retourne ensuite le nombre d’entrées spécifiées par la taille de la page et retourne également un cookie émis lors de la demande cliente suivante pour obtenir la page de résultats suivante. Le client émet ensuite une recherche, avec le cookie inclus, réinitialisant éventuellement la taille de la page. Le serveur répond ensuite en retournant les résultats, jusqu’au nombre spécifié d’entrées. Pour demander à la fonction de retourner directement les résultats, utilisez la routine synchrone ldap_search_ext_s.
Multithreading : les appels à ldap_search_ext sont 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 |