ldap_search_ext-Funktion (winldap.h)
Die ldap_search_ext-Funktion durchsucht das LDAP-Verzeichnis und gibt einen angeforderten Satz von Attributen für jeden übereinstimmenen Eintrag zurück.
Syntax
WINLDAPAPI ULONG LDAPAPI ldap_search_ext(
[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] ULONG TimeLimit,
[in] ULONG SizeLimit,
[out] ULONG *MessageNumber
);
Parameter
[in] ld
Das Sitzungshandle.
[in] base
Ein 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
Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Suchfilter angibt. Weitere Informationen finden Sie unter Suchfiltersyntax.
[in] attrs
Ein Array mit NULL-Terminierung von Zeichenfolgen mit NULL-Beendigung, die angeben, welche Attribute für jeden übereinstimmenden Eintrag zurückgegeben werden sollen. Übergeben Sie NULL, um alle verfügbaren Attribute abzurufen.
[in] attrsonly
Ein boolescher Wert, der null sein sollte, wenn sowohl Attributtypen als auch Werte zurückgegeben werden sollen, ungleich null, wenn nur Typen zurückgegeben werden sollen.
[in] ServerControls
Eine Liste der LDAP-Serversteuerelemente.
[in] ClientControls
Eine Liste der Clientsteuerelemente.
[in] TimeLimit
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] MessageNumber
Die ID der Anforderungsnachricht.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert LDAP_SUCCESS.
Wenn die Ausführung der Funktion fehlschlägt, wird ein Fehlercode zurückgegeben. Weitere Informationen finden Sie unter Rückgabewerte.
Hinweise
Die funktion ldap_search_ext initiiert einen asynchronen Suchvorgang. Zu den Parametern und Effekten von ldap_search_ext gehören die Parameter ldap_search. Die erweiterte Funktion enthält zusätzliche Parameter zur Unterstützung von Client- und Serversteuerelementen sowie zur Threadsicherheit sowie zum Angeben von Größen- und Zeitlimits für jeden Suchvorgang.
Verwenden Sie die funktion ldap_set_option mit dem ld session handle, um die option LDAP_OPT_DEREF festzulegen, die bestimmt, wie die Suche ausgeführt wird. Weitere Informationen finden Sie unter Sitzungsoptionen. Zwei weitere Sitzungsoptionen, LDAP_OPT_SIZELIMIT und LDAP_OPT_TIMELIMIT, werden zugunsten der Parameter SizeLimit und TimeLimit in dieser Funktion ignoriert.
Wenn der Vorgang erfolgreich ist, übergibt ldap_search_ext die Meldungs-ID als Parameter an den Aufrufer, wenn der Vorgang erfolgreich zurückgegeben wird. Rufen Sie ldap_result mit der Nachrichten-ID auf, um das Ergebnis des Vorgangs zu erhalten.
Eine LDAP-Clientanwendung, die die Rate steuern muss, mit der Ergebnisse zurückgegeben werden, kann die Suchanforderung angeben, um ein Steuerelement für ausgelagerte Ergebnisse bereitzustellen, dessen Größe auf die gewünschte Seitengröße festgelegt ist und das Cookie auf die leere Zeichenfolge festgelegt ist. Die angegebene Seitengröße kann größer als null und kleiner als der in der Suchanforderung angegebene SizeLimit-Wert sein.
Wenn die Seitengröße größer oder gleich der unter Sitzungsoptionen beschriebenen SizeLimit-Wertoption ist, sollte der Server das Steuerelement ignorieren, da die Anforderung auf einer einzelnen Seite erfüllt werden kann. Wenn der Server dieses Steuerelement nicht unterstützt, muss der Server einen Fehler der nicht unterstützten kritischen Erweiterung zurückgeben, wenn der Client sie als kritisch angefordert hat. Andernfalls sollte der Server das Steuerelement ignorieren. Im weiteren Verlauf dieses Abschnitts wird davon ausgegangen, dass der Server das Auslagerungsergebnissteuerelement des Clients nicht ignoriert.
Der Client sendet dem Server eine Suchanforderung mit dem einfachen Auslagerungsergebnissteuerelement zusammen mit einem leeren vorherigen Enumerationsschlüssel, der auch als "Cookie" bezeichnet wird, und der anfänglichen Seitengröße. Der Server gibt dann die Anzahl der Einträge zurück, die durch die Seitengröße angegeben ist, und gibt auch ein Cookie zurück, das bei der nächsten Clientanforderung ausgegeben wurde, um die nächste Seite mit Ergebnissen zu erhalten. Der Client gibt dann eine Suche mit dem enthaltenen Cookie aus, wobei optional die Seitengröße zurückgesetzt wird. Der Server antwortet dann, indem er die Ergebnisse bis zur angegebenen Anzahl von Einträgen zurückgibt. Um die Funktion anzuweisen, die Ergebnisse direkt zurückzugeben, verwenden Sie die synchrone Routine ldap_search_ext_s.
Multithreading: Aufrufe von ldap_search_ext sind threadsicher.
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 |