ldap_search_s, fonction (winldap.h)

Article
08/27/2023

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