ldap_search_st, fonction (winldap.h)
La fonction ldap_search_st recherche de manière synchrone dans le répertoire LDAP et retourne un ensemble d’attributs demandé pour chaque entrée mise en correspondance. Un paramètre supplémentaire spécifie un délai d’attente local pour la recherche. La fonction est identique à ldap_search_s, à l’exception du paramètre de délai d’attente local supplémentaire.
Syntaxe
WINLDAPAPI ULONG LDAPAPI ldap_search_st(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[in] l_timeval *timeout,
[out] PLDAPMessage *res
);
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. Passez 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] timeout
Valeur de délai d’attente de recherche locale, en secondes.
[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. Tous les résultats retournés doivent être libérés par 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_st 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_st lance une opération de recherche synchrone.
Utilisez la fonction ldap_set_option avec le handle de session ld pour définir les options LDAP_OPT_SIZELIMIT et LDAP_OPT_DEREF qui déterminent la façon dont la recherche est effectuée. Pour plus d’informations, consultez Options de session. Le paramètre de délai d’expiration dans ldap_search_st remplace le LDAP_OPT_TIMELIMIT.
Une fois l’opération de recherche terminée, ldap_search_st retourne à l’appelant. Utilisez ldap_search ou ldap_search_ext pour effectuer l’opération de manière asynchrone.
Multithreading : les appels à ldap_search_st sont thread-safe.
L’exemple de code suivant montre comment libérer pMsg si ldap_search_st échoue.
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_st (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
0,
lpsTimeout,
&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_st"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if the
// call to ldap_search_st 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 just 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 |