Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Die ldap_init-Funktion initialisiert eine Sitzung mit einem LDAP-Server.
Syntax
WINLDAPAPI LDAP *LDAPAPI ldap_initW(
[in] const PWSTR HostName,
[in] ULONG PortNumber
);
Parameter
[in] HostName
Ein Zeiger auf eine mit Null beendete Zeichenfolge, die einen Domänennamen enthält, oder eine durch Leerzeichen getrennte Liste von Hostnamen oder gepunkteten Zeichenfolgen, die die IP-Adresse von Hosts darstellen, auf denen ein LDAP-Server ausgeführt wird, mit dem eine Verbindung hergestellt werden soll. Jeder Hostname in der Liste kann eine optionale Portnummer enthalten, die vom Host selbst durch einen Doppelpunkt (:)) getrennt ist. Weitere Informationen zur Verwendung der Option LDAP_OPT_AREC_EXCLUSIVE beim Herstellen einer Verbindung mit Active Directory-Servern finden Sie im Abschnitt "Hinweise".
[in] PortNumber
Enthält die TCP-Portnummer, mit der eine Verbindung hergestellt werden soll. Legen Sie auf LDAP_PORT fest, um den Standardport 389 abzurufen. Dieser Parameter wird ignoriert, wenn ein Hostname eine Portnummer enthält.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird ein Sitzungshandle in Form eines Zeigers auf eine LDAP- Datenstruktur zurückgegeben. Der Sitzungshandle muss mit einem Aufruf von ldap_unbind freigegeben werden, wenn er nicht mehr erforderlich ist.
Wenn die Funktion fehlschlägt, wird NULL-zurückgegeben. Verwenden Sie LdapGetLastError-, um den Fehlercode abzurufen.
Bemerkungen
Rufen Sie ldap_init auf, um einen Verbindungsblock mit einem LDAP-Server zu erstellen. Im Gegensatz zu ldap_openwird die Verbindung von einem Aufruf von ldap_init nicht geöffnet. Sie können ldap_connect explizit aufrufen, damit die Bibliothek den Server kontaktiert. Dies ist nützlich, wenn Sie ein lokales Timeout angeben möchten, in diesem Fall rufen Sie ldap_set_optionmit dem Verbindungsblock von ldap_initauf, bevor Sie ldap_connectaufrufen. In der Regel ist dieser Aufruf jedoch unnötig, da die erste Vorgangsfunktion, die eine offene Verbindung erfordert, intern ldap_connect aufruft, wenn er nicht aufgerufen wurde.
Die Funktion weist eine LDAP-Datenstruktur zu, um Zustandsdaten für die Sitzung zu verwalten, und gibt ein Handle an diese Struktur zurück. Übergeben Sie dieses Handle an LDAP-Funktionsaufrufe während der Sitzung.
Der HostName Parameter kann NULL-sein. In diesem Fall versucht die Laufzeit, den LDAP-Server "standard" zu finden. Wenn ldap_connect aufgerufen wird, werden die Hosts in der aufgeführten Reihenfolge versucht und mit der ersten erfolgreichen Verbindung beendet. Für Active Directory-Server kann die DsGetDcName--Funktion verwendet werden, um den Namen des Servers abzurufen, der dann als HostName Parameter übergeben werden kann, anstatt NULL-zu verwenden.
Auch wenn die ldap_set_option-Funktion verwendet wird, um die option LDAP_OPT_GETDSNAME_FLAGS festzulegen, die wiederum die Flags angibt, die an DsGetDCName übergeben werden, um zu ermitteln, mit welchem DC eine Verbindung hergestellt werden soll. Der LDAP-Client übergibt außerdem das DS_ONLY_LDAP_NEEDED Flag an DsGetDCName- zusätzlich zu den Flags, die LDAP_OPT_GETDSNAME_FLAGS angibt.
Wenn NULL- für den parameter HostName übergeben wird und der aufrufende Computer Mitglied einer Active Directory-Domäne ist, sucht die Laufzeit bei dem Versuch, eine Verbindung herzustellen, nach einem DC in der Domäne, in der der aktuelle Computer Mitglied ist.
Wenn NULL- für den parameter HostName übergeben wird und der aufrufende Computer ein DC einer Active Directory-Domäne ist, wechselt die Laufzeit NULL- mit 127.0.0.1 und stellt beim Versuch, eine Verbindung mit dem lokalen Computer herzustellen, mithilfe von Loopback eine Verbindung mit dem lokalen Computer her.
Wenn ein Active Directory-Domänenname für den parameter HostName übergeben wird, wird ldap_init den LDAP-Standardserver in dieser Domäne finden.
Wenn die HostName- entweder auf NULL- oder den Domänennamen festgelegt wurde, wird die automatische erneute Verbindung angewendet. Wenn der verbundene DC während der Lebensdauer der Verbindung aus irgendeinem Grund nicht mehr funktioniert, stellt LDAP automatisch eine Verbindung mit einem anderen DC in der angegebenen Domäne her. Dieses Verhalten kann deaktiviert oder aktiviert werden, indem die Option LDAP_OPT_AUTO_RECONNECT Sitzung verwendet wird, die standardmäßig aktiviert ist.
Wenn ein Active Directory-DNS-Servername für den parameter HostName übergeben wird, sollte ldap_set_option aufgerufen werden, um das LDAP_OPT_AREC_EXCLUSIVE Flag festzulegen, bevor eine LDAP-Funktion aufgerufen wird, die die tatsächliche Verbindung erstellt. Dadurch wird ein A-Datensatz-Nachschlagevorgang erzwungen und alle SRV-Datensatzsuche beim Auflösen des Hostnamens umgangen. Bei einer Zweigstelle mit einer DFÜ-Verbindung kann die Verwendung des A-Record-Nachschlagevorgangs das Erzwingen der Wählfunktion vermeiden, einen Remote-DNS-Server für SRV-Einträge abzufragen, wenn Namen aufgelöst werden.
Wenn eine Portnummer des globalen Katalogs als eines der Argumente an ldap_init übergeben wird, muss der HostName, der für diese Portnummer übergeben wird, der Name der Gesamtstruktur für den zugrunde liegenden Aufruf von DsGetDcName() sein, um die GC im Unternehmen korrekt zu finden.
Multithreading: Ein Aufruf von ldap_init ist threadsicher.
Hinweisldap_init ist die bevorzugte Methode zum Initialisieren einer LDAP-Sitzung. Die Verwendung von ldap_open ist von der aktuellen LDAP RFC stark veraltet, da sie die Verwendung von Sitzungsoptionen ausschließt.
Anmerkung
Der winldap.h-Header definiert ldap_init 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 |