ldap_search_ext_sW-Funktion (winldap.h)
Die ldap_search_ext_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_ext_sW(
[in] LDAP *ld,
[in] const PWSTR base,
[in] ULONG scope,
[in] const PWSTR filter,
[in] PZPWSTR attrs,
[in] ULONG attrsonly,
[in] PLDAPControlW *ServerControls,
[in] PLDAPControlW *ClientControls,
[in] l_timeval *timeout,
[in] ULONG SizeLimit,
[out] PLDAPMessage *res
);
Parameter
[in] ld
Sitzungshandle.
[in] base
Zeigen Sie auf eine mit Null beendete Zeichenfolge, die den distinguishierten Namen 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 auf 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
Zeigen Sie auf eine mit Null beendete Zeichenfolge, die den Suchfilter angibt. Weitere Informationen finden Sie unter Suchfiltersyntax.
[in] attrs
Ein null-beendetes Array von Zeigern auf mit Null beendete 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 soll, wenn sowohl Attributtypen als auch Werte zurückgegeben werden sollen, nonzero, wenn nur Typen erforderlich sind.
[in] ServerControls
Eine Liste der LDAP-Serversteuerelemente.
[in] ClientControls
Eine Liste der Clientsteuerelemente.
[in] timeout
Gibt sowohl den Lokalen Suchtimeoutwert in Sekunden als auch den Zeitlimit für den Vorgang an, der innerhalb der Suchanforderung an den Server gesendet wird.
[in] SizeLimit
Ein Grenzwert für die Anzahl der Einträge, die von der Suche zurückgegeben werden sollen. Ein Wert von Null gibt keinen Grenzwert an.
[out] res
Enthält die Ergebnisse der Suche nach Abschluss des Anrufs. Kann auch Teilergebnisse oder erweiterte Daten enthalten, wenn der Funktionsaufruf mit einem Fehlercode fehlschlägt. Kostenlose zurückgegebene Ergebnisse mit einem Aufruf von ldap_msgfree, wenn die Anwendung nicht mehr benötigt wird.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert LDAP_SUCCESS.
Wenn die Funktion fehlschlägt, wird jedoch ein Fehlercode zurückgegeben, ldap_search_ext_s fehlschlagen kann und weiterhin pMsgzuordnen kann. 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.
Bemerkungen
Die ldap_search_ext_s-Funktion initiiert einen synchronen Suchvorgang. Zu den Parametern und Effekten von ldap_search_ext_s gehören die Parameter ldap_search_s. Die erweiterte Routine enthält zusätzliche Parameter zur Unterstützung von Client- und Serversteuerelementen und 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 SizeLimit- und TimeLimit Optionsparameter in dieser Funktion ignoriert.
Nach Abschluss des Suchvorgangs kehrt ldap_search_ext_s zum Aufrufer zurück. Verwenden Sie ldap_search_ext, um den Vorgang asynchron auszuführen.
Multithreading: Aufrufe von ldap_search_ext_s sind threadsicher.
Im folgenden Codebeispiel wird gezeigt, wie sie pMsg- freigeben, wenn ldap_search_ext_s fehlschlägt.
// 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);
}
Anmerkung
Der winldap.h-Header definiert ldap_search_ext_s als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows Vista |
| mindestens unterstützte Server- | Windows Server 2008 |
| Zielplattform- | Fenster |
| Header- | winldap.h |
| Library | Wldap32.lib |
| DLL- | Wldap32.dll |