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