ldap_search_s-Funktion (winldap.h)

Die ldap_search_s-Funktion durchsucht synchron das LDAP-Verzeichnis und gibt einen angeforderten Satz von Attributen für jeden übereinstimmenen Eintrag zurück.

Syntax

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
);

Parameter

[in] ld

Sitzungshandle.

[in] base

Zeiger auf eine NULL-endende Zeichenfolge, die den distinguished Name des Eintrags enthält, an dem die Suche gestartet werden soll.

[in] scope

Gibt einen der folgenden Werte an, um den Suchbereich anzugeben.

LDAP_SCOPE_BASE

Suchen Sie nur den Basiseintrag.

LDAP_SCOPE_ONELEVEL

Durchsuchen Sie alle Einträge in der ersten Ebene unterhalb des Basiseintrags, mit Ausnahme des Basiseintrags.

LDAP_SCOPE_SUBTREE

Durchsuchen Sie den Basiseintrag und alle Einträge in der Struktur unterhalb der Basis.

[in] filter

Zeiger auf eine NULL-endende Zeichenfolge, die den Suchfilter angibt. Weitere Informationen finden Sie unter Suchfiltersyntax.

[in] attrs

Ein Array mit NULL-Terminierung von NULL-Zeichenfolgen, die die Attribute angeben, die für jeden übereinstimmenden Eintrag zurückgegeben werden sollen. Übergeben Sie NULL , um alle verfügbaren Attribute abzurufen.

[in] attrsonly

Boolescher Wert, der null sein sollte, wenn sowohl Attributtypen als auch Werte zurückgegeben werden sollen, ungleich null, wenn nur Typen erforderlich sind.

[out] res

Enthält die Ergebnisse der Suche nach Abschluss des Aufrufs. Kann auch Teilergebnisse oder erweiterte Daten enthalten, wenn der Funktionsaufruf mit einem Fehlercode fehlschlägt. Kostenlose Ergebnisse, die mit einem Aufruf von ldap_msgfree zurückgegeben werden, wenn sie von der Anwendung nicht mehr benötigt werden.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert LDAP_SUCCESS.

Wenn die Funktion fehlschlägt, gibt sie einen Fehlercode zurück, aber ldap_search_s kann fehlschlagen und pMsg weiterhin zuordnen. Beispielsweise weisen sowohl LDAP_PARTIAL_RESULTS als auch LDAP_REFERRAL Fehlercode pMsg zu. Weitere Informationen finden Sie im folgenden Codebeispiel. Weitere Informationen finden Sie unter Rückgabewerte.

Hinweise

Die funktion ldap_search_s initiiert eine synchrone Suche.

Verwenden Sie die ldap_set_option-Funktion mit dem ld-Sitzungshandle, um die Optionen LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMIT und LDAP_OPT_DEREF festzulegen, die bestimmen, wie die Suche ausgeführt wird. Weitere Informationen finden Sie unter Sitzungsoptionen.

Nach Abschluss des Suchvorgangs kehrt ldap_search_s zum Aufrufer zurück. Verwenden Sie ldap_search , um den Vorgang asynchron ausführen zu lassen.

Multithreading: Aufrufe von ldap_search_s sind threadsicher.

Im folgenden Codebeispiel wird gezeigt, wie pMsg freigegeben wird, wenn ldap_search_s fehlschlägt.

// 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);
}

Anforderungen

Siehe auch

Funktionen

LDAP

Rückgabewerte

Sitzungsoptionen

ldap_msgfree

ldap_search

ldap_search_ext

ldap_search_ext_s

ldap_search_st