ldap_search_ext_s-Funktion (winldap.h)

Artikel
03/13/2024

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

Syntax

WINLDAPAPI ULONG LDAPAPI ldap_search_ext_s(
  [in]  LDAP          *ld,
  [in]  PSTR          base,
  [in]  ULONG         scope,
  [in]  PSTR          filter,
  [in]  PZPSTR        attrs,
  [in]  ULONG         attrsonly,
  [in]  PLDAPControlA *ServerControls,
  [in]  PLDAPControlA *ClientControls,
  [in]  l_timeval     *timeout,
  [in]  ULONG         SizeLimit,
  [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 von Zeigern auf NULL-beendete Zeichenfolgen, die angibt, 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 sollte, wenn sowohl Attributtypen als auch Werte zurückgegeben werden sollen, nonzero, wenn nur Typen erforderlich sind.

[in] ServerControls

Eine Liste von LDAP-Serversteuerelementen.

[in] ClientControls

Eine Liste der Clientsteuerelemente.

[in] timeout

Gibt sowohl den Timeoutwert für die lokale Suche in Sekunden als auch das Vorgangszeitlimit an, das innerhalb der Suchanforderung an den Server gesendet wird.

[in] SizeLimit

Ein Grenzwert für die Anzahl von Einträgen, die von der Suche zurückgegeben werden sollen. Ein Wert von null zeigt an, dass keine Grenze festgelegt ist.

[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. Frei zurückgegebene Ergebnisse mit einem Aufruf von ldap_msgfree , wenn die Anwendung sie nicht mehr benötigt.

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_ext_s kann fehlschlagen und pMsg weiterhin zuordnen. Beispielsweise werden sowohl LDAP_PARTIAL_RESULTS als auch LDAP_REFERRAL Fehlercode pMsg zugeordnet. Weitere Informationen finden Sie im folgenden Codebeispiel. Weitere Informationen finden Sie unter Rückgabewerte.

Hinweise

Die ldap_search_ext_s-Funktion initiiert einen synchronen Suchvorgang. Zu den Parametern und Auswirkungen von ldap_search_ext_s gehören die Parameter ldap_search_s. Die erweiterte Routine umfasst zusätzliche Parameter zur Unterstützung von Client- und Serversteuerelementen sowie zum Angeben von Größen- und Zeitlimits für jeden Suchvorgang.

Verwenden Sie die ldap_set_option-Funktion mit dem ld-Sitzungshandle, um die Option LDAP_OPT_DEREF festzulegen, die bestimmt, wie die Suche ausgeführt wird. Weitere Informationen finden Sie unter Sitzungsoptionen. Zwei weitere Suchoptionen, LDAP_OPT_SIZELIMIT und LDAP_OPT_TIMELIMIT, werden zugunsten der Optionsparameter SizeLimit und TimeLimit in dieser Funktion ignoriert.

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

Multithreading: Aufrufe an ldap_search_ext_s sind threadsicher.

Im folgenden Codebeispiel wird gezeigt, wie pMsg im Fall eines Fehlers von ldap_search_ext_s freigegeben wird.

// Initialize return value to NULL.
LDAPMessage *pMsg = NULL;

// Perform the search request.
dwErr = ldap_search_ext_s (i_pldap,
        i_lpszBase,
        i_ulScope,
        i_lpszSearchFilter,
        lpszAttributes,
        0,
        pServerControls,
        pClientControls,
        lpsTimeout,
        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_ext_s"));
    hr = HRESULT_FROM_WIN32(dwErr);

    // Be aware that pMsg can contain valid data, even if
    // the call to ldap_search_ext_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 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

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	winldap.h
Bibliothek	Wldap32.lib
DLL	Wldap32.dll