ldap_search_s, fonction (winldap.h)
La fonction ldap_search_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_s(
[in] LDAP *ld,
[in] PSTR base,
[in] ULONG scope,
[in] PSTR filter,
[in] PZPSTR attrs,
[in] ULONG attrsonly,
[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’exception 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 indiquant 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.
[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 gratuits retournés avec un appel à ldap_msgfree lorsqu’ils ne sont plus requis par l’application.
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_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_s lance une recherche synchrone.
Utilisez la fonction ldap_set_option avec le handle de session ld pour définir les options LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT et LDAP_OPT_DEREF qui déterminent la façon dont la recherche est effectuée. Pour plus d’informations, consultez Options de session.
Une fois l’opération de recherche terminée, ldap_search_s retourne à l’appelant. Utilisez ldap_search pour effectuer l’opération de manière asynchrone.
Multithreading : les appels à ldap_search_s sont thread-safe.
L’exemple de code suivant montre comment libérer pMsg en cas d’échec de ldap_search_s .
// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;
// Perform the search request.
dwErr = ldap_search_s (i_pldap,
i_lpszBase,
i_ulScope,
i_lpszSearchFilter,
lpszAttributes,
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_s"));
hr = HRESULT_FROM_WIN32(dwErr);
// Be aware that pMsg can contain valid data, even if the
// call to ldap_search_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 just frees pMsg on any
// error code.
if (pMsg != NULL)
ldap_msgfree(pMsg);
}
else
{
// Process the search results.
...
// Free the results when no longer required.
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 |