ldap_search_st-Funktion (winldap.h)

Die ldap_search_st-Funktion durchsucht synchron das LDAP-Verzeichnis und gibt einen angeforderten Satz von Attributen für jeden zugeordneten Eintrag zurück. Ein zusätzlicher Parameter gibt ein lokales Timeout für die Suche an. Die Funktion ist mit ldap_search_s identisch, mit Ausnahme des zusätzlichen lokalen Timeoutparameters.

Syntax

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

Parameter

[in] ld

Sitzungshandle.

[in] base

Zeiger auf eine NULL-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-Zeichenfolge, die den Suchfilter angibt. Weitere Informationen finden Sie unter Suchfiltersyntax.

[in] attrs

Ein NULL-beendetes Array mit NULL-Zeichenfolgen, die angeben, welche Attribute 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 muss, wenn sowohl Attributtypen als auch Werte zurückgegeben werden sollen, nonzero, wenn nur Typen erforderlich sind.

[in] timeout

Der Timeoutwert für die lokale Suche in Sekunden.

[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. Alle zurückgegebenen Ergebnisse müssen mit einem Aufruf von ldap_msgfree freigegeben 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_st kann fehlschlagen und pMsg weiterhin zuordnen. Beispielsweise weisen LDAP_PARTIAL_RESULTS und LDAP_REFERRAL Fehlercode pMsg zu. Weitere Informationen finden Sie im folgenden Codebeispiel. Weitere Informationen finden Sie unter Rückgabewerte.

Hinweise

Die ldap_search_st-Funktion initiiert einen synchronen Suchvorgang.

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

Nach Abschluss des Suchvorgangs kehrt ldap_search_st zum Aufrufer zurück. Verwenden Sie ldap_search oder ldap_search_ext , damit der Vorgang asynchron ausgeführt wird.

Multithreading: Aufrufe an ldap_search_st sind threadsicher.

Im folgenden Codebeispiel wird gezeigt, wie Sie pMsg freigeben, wenn ldap_search_st fehlschlägt.

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

Anforderungen

Siehe auch

Funktionen

LDAP

Rückgabewerte

Sitzungsoptionen

ldap_msgfree

ldap_search

ldap_search_ext

ldap_search_ext_s

ldap_search_s