ldap_search_sW-Funktion (winldap.h)

2024-11-20

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_sW(
  [in]  LDAP        *ld,
  [in]  const PWSTR base,
  [in]  ULONG       scope,
  [in]  const PWSTR filter,
  [in]  PZPWSTR     attrs,
  [in]  ULONG       attrsonly,
  [out] LDAPMessage **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 mit null-beendeten 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 soll, wenn sowohl Attributtypen als auch Werte zurückgegeben werden sollen, nonzero, wenn nur Typen erforderlich sind.

[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 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 einen Fehlercode zurückgibt, kann jedoch ldap_search_s fehlschlagen und weiterhin pMsg-zuordnen. Beispielsweise weisen sowohl LDAP_PARTIAL_RESULTS als auch LDAP_REFERRAL Fehlercode pMsgzu. Weitere Informationen finden Sie im folgenden Codebeispiel. Weitere Informationen finden Sie unter Rückgabewerte.

Bemerkungen

Die ldap_search_s-Funktion initiiert eine synchrone Suche.

Verwenden Sie die ldap_set_option-Funktion mit dem ld Sitzungshandle, um die Optionen LDAP_OPT_SIZELIMIT, LDAP_OPT_TIMELIMITund 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, damit der Vorgang asynchron ausgeführt wird.

Multithreading: Aufrufe von ldap_search_s sind threadsicher.

Im folgenden Codebeispiel wird gezeigt, wie sie pMsg- freigeben, 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);
}

Anmerkung

Der winldap.h-Header definiert ldap_search_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