ldap_init-Funktion (winldap.h)

Artikel
03/06/2024

Die funktion ldap_init initialisiert eine Sitzung mit einem LDAP-Server.

Syntax

WINLDAPAPI LDAP *LDAPAPI ldap_init(
  [in] PSTR  HostName,
  [in] ULONG PortNumber
);

Parameter

[in] HostName

Ein Zeiger auf eine NULL-endende 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, die einen LDAP-Server ausführen, mit dem eine Verbindung hergestellt werden soll. Jeder Hostname in der Liste kann eine optionale Portnummer enthalten, die vom Host selbst durch einen Doppelpunkt (:). 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. Das Sitzungshandle muss mit einem Aufruf von ldap_unbind freigegeben werden, wenn es nicht mehr benötigt wird.

Wenn bei der Funktion ein Fehler auftritt, gibt sie NULL zurück. Verwenden Sie LdapGetLastError , um den Fehlercode abzurufen.

Hinweise

Rufen Sie ldap_init auf, um einen Verbindungsblock mit einem LDAP-Server zu erstellen. Im Gegensatz zu ldap_open wird die Verbindung bei 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_option mit dem Verbindungsblock von ldap_init auf, bevor Sie ldap_connect aufrufen. In der Regel ist dieser Aufruf jedoch unnötig, da die erste Vorgangsfunktion, die eine offene Verbindung erfordert, intern ldap_connect aufruft, wenn sie nicht aufgerufen wurde.

Die Funktion ordnet 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 während der Sitzung an LDAP-Funktionsaufrufe.

Der HostName-Parameter kann NULL sein. In diesem Fall versucht die Laufzeit, den LDAP-Standardserver 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 zusätzlich zu den von LDAP_OPT_GETDSNAME_FLAGS angegebenen Flags auch das flag DS_ONLY_LDAP_NEEDED an DsGetDCName.

Wenn NULL für den HostName-Parameter übergeben wird und der aufrufende Computer Mitglied einer Active Directory-Domäne ist, sucht die Laufzeit nach einem DC in der Domäne, in der der aktuelle Computer Mitglied ist, wenn versucht wird, eine Verbindung herzustellen.

Wenn NULL für den HostName-Parameter ü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 Herstellen einer Verbindung mithilfe von Loopback eine Verbindung mit dem lokalen Computer her.

Wenn ein Active Directory-Domänenname für den HostName-Parameter übergeben wird, finden ldap_init den LDAP-Standardserver in dieser Domäne.

Wenn 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 wieder eine Verbindung mit einem anderen DC in der angegebenen Domäne her. Dieses Verhalten kann mithilfe der Option LDAP_OPT_AUTO_RECONNECT Sitzung deaktiviert oder aktiviert werden, die standardmäßig aktiviert ist.

Wenn ein Active Directory-DNS-Servername für den HostName-Parameter übergeben wird, sollte ldap_set_option aufgerufen werden, um das flag LDAP_OPT_AREC_EXCLUSIVE festzulegen, bevor eine LDAP-Funktion aufgerufen wird, die die tatsächliche Verbindung herstellt. Dies erzwingt eine A-Datensatzsuche und umgeht beim Auflösen des Hostnamens jede SRV-Datensatzsuche. Im Fall einer Filiale mit DFÜ-Verbindung kann die Verwendung der A-Record-Suche vermeiden, dass die Wählverbindung erzwingt, einen DNS-Remoteserver nach SRV-Einträgen abzufragen, wenn Namen aufgelöst werden.

Wenn eine Portnummer des globalen Katalogs als eines der Argumente an ldap_init übergeben wird, muss der für diese Portnummer übergebene HostName der Name der Gesamtstruktur für den zugrunde liegenden Aufruf von DsGetDcName() sein, um den GC im Unternehmen ordnungsgemäß zu finden.

Multithreading: Ein Aufruf von ldap_init ist threadsicher.

Beachten Sieldap_init die bevorzugte Methode zum Initialisieren einer LDAP-Sitzung ist. Die Verwendung von ldap_open ist vom aktuellen LDAP RFC stark veraltet, da sie das Festlegen von Sitzungsoptionen verhindert.

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