fonction ldap_search_ext_s (winldap.h)
La fonction ldap_search_ext_s recherche de manière synchrone dans le répertoire LDAP et retourne un ensemble d’attributs demandé pour chaque entrée mise en correspondance.
Syntaxe
WINLDAPAPI ULONG LDAPAPI ldap_search_ext_s(
[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] l_timeval *timeout,
[in] ULONG SizeLimit,
[out] PLDAPMessage *res
);
Paramètres
[in] ld
Handle de session.
[in] base
Pointeur vers une chaîne terminée par null qui contient le nom unique de l’entrée à partir de laquelle démarrer la recherche.
[in] scope
Spécifie l’une des valeurs suivantes pour indiquer l’étendue de la recherche.
LDAP_SCOPE_BASE
Recherchez uniquement dans l’entrée de base.
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 dans l’arborescence située 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 de filtre de recherche.
[in] attrs
Tableau terminé par null de pointeurs vers des chaînes terminées par null indiquant les attributs à retourner pour chaque entrée correspondante. Passez la valeur NULL pour récupérer tous les attributs disponibles.
[in] attrsonly
Valeur booléenne qui doit être égale à zéro si les types d’attributs et les valeurs doivent être retournés, différente de zéro si seuls les types sont requis.
[in] ServerControls
Liste des contrôles serveur LDAP.
[in] ClientControls
Liste des contrôles clients.
[in] timeout
Spécifie à la fois la valeur de délai d’expiration de la recherche locale, 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] res
Contient les résultats de la recherche à la fin de l’appel. Peut également contenir des résultats partiels ou des données étendues lorsque l’appel de fonction échoue avec un code d’erreur. Les résultats retournés gratuitement avec un appel à ldap_msgfree lorsque l’application n’en a plus besoin.
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, mais ldap_search_ext_s peut échouer et peut toujours allouer pMsg. Par exemple, LDAP_PARTIAL_RESULTS et LDAP_REFERRAL code d’erreur allouent pMsg. Pour plus d’informations, consultez l’exemple de code suivant. Pour plus d’informations, consultez Valeurs de retour.
Remarques
La fonction ldap_search_ext_s lance une opération de recherche synchrone. Les paramètres et les effets de ldap_search_ext_s incluent ceux de ldap_search_s. La routine étendue inclut des paramètres supplémentaires pour prendre en charge les contrôles client et serveur, 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 recherche, LDAP_OPT_SIZELIMIT et LDAP_OPT_TIMELIMIT, sont ignorées au profit des paramètres d’option SizeLimit et TimeLimit dans cette fonction.
Une fois l’opération de recherche terminée, ldap_search_ext_s retourne à l’appelant. Utilisez ldap_search_ext pour que l’opération s’effectue de manière asynchrone.
Multithreading : les appels à ldap_search_ext_s sont thread-safe.
L’exemple de code suivant montre comment libérer pMsg en cas d’échec de ldap_search_ext_s .
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_ext_s (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
0,
pServerControls,
pClientControls,
lpsTimeout,
0,
&pMsg
);
// Cleanup calling parameters.
if (lpszAttributes != NULL)
delete [] lpszAttributes;
// Convert error code and cleanup pMsg if necessary.
if (dwErr != LDAP_SUCCESS)
{
DebugOutLDAPError(i_pldap, dwErr, _T("ldap_search_ext_s"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if
// the call to ldap_search_ext_s returned an error code.
// This can be caused by the server returning codes
// such as LDAP_RESULTS_TOO_LARGE or other codes
// that indicate that the search returned partial
// results. The user code can handle these cases
// if required, this example frees pMsg on any
// error code.
if (pMsg != NULL) ldap_msgfree(pMsg);
}
else
{
// Process the search results.
...
// Free the results when complete.
if (pMsg != NULL) ldap_msgfree(pMsg);
}
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 |