NetJoinDomain-Funktion (lmjoin.h)

Artikel
08/24/2023

Die NetJoinDomain-Funktion verknüpft einen Computer mit einer Arbeitsgruppe oder Domäne.

Syntax

NET_API_STATUS NET_API_FUNCTION NetJoinDomain(
  [in] LPCWSTR lpServer,
  [in] LPCWSTR lpDomain,
  [in] LPCWSTR lpMachineAccountOU,
  [in] LPCWSTR lpAccount,
  [in] LPCWSTR lpPassword,
  [in] DWORD   fJoinOptions
);

Parameter

[in] lpServer

Ein Zeiger auf eine konstante Zeichenfolge, die den DNS- oder NetBIOS-Namen des Computers angibt, auf dem der Domänenbeitrittsvorgang ausgeführt werden soll. Wenn dieser Parameter NULL ist, wird der lokale Computer verwendet.

[in] lpDomain

Ein Zeiger auf eine konstante NULL-Zeichenfolge, die den Namen der zu verknüpfenden Domäne oder Arbeitsgruppe angibt.

Optional können Sie den bevorzugten Domänencontroller für die Durchführung des Joinvorgangs angeben. In diesem instance muss die Zeichenfolge das Format Domänenname\MachineName aufweisen, wobei DomainName der Name der zu verknüpfenden Domäne und MachineName der Name des Domänencontrollers ist, der die Verknüpfung ausführen soll.

[in] lpMachineAccountOU

Gibt optional den Zeiger auf eine konstante NULL-Zeichenfolge an, die den RFC 1779-Formatnamen der Organisationseinheit für das Computerkonto enthält. Wenn Sie diesen Parameter angeben, muss die Zeichenfolge einen vollständigen Pfad enthalten, z. B. OU=testOU,DC=domain,DC=Domain,DC=com. Andernfalls muss dieser Parameter NULL sein.

[in] lpAccount

Ein Zeiger auf eine konstante NULL-Zeichenfolge, die den Kontonamen angibt, der beim Herstellen einer Verbindung mit dem Domänencontroller verwendet werden soll. Die Zeichenfolge muss entweder einen NetBIOS-Domänennamen und ein Benutzerkonto (z. B . REDMOND\user) oder den Benutzerprinzipalnamen (UPN) des Benutzers in Form eines Anmeldenamens im Internetformat (z. B. "someone@example.com") angeben. Wenn dieser Parameter NULL ist, wird der Kontext des Aufrufers verwendet.

[in] lpPassword

Wenn der lpAccount-Parameter einen Kontonamen angibt, muss dieser Parameter auf das Kennwort verweisen, das beim Herstellen einer Verbindung mit dem Domänencontroller verwendet werden soll. Andernfalls muss dieser Parameter NULL sein.

Sie können ein Kennwort für ein lokales Computerkonto anstelle eines Benutzerkennworts für ungesicherte Joins angeben. Weitere Informationen finden Sie in der Beschreibung des NETSETUP_MACHINE_PWD_PASSED Flags, das im fJoinOptions-Parameter beschrieben wird.

[in] fJoinOptions

Eine Reihe von Bitflags, die die Verknüpfungsoptionen definieren. Bei diesem Parameter kann es sich um einen oder mehrere der folgenden Werte handeln, die in der Headerdatei Lmjoin.h definiert sind.

Wert	Bedeutung
NETSETUP_JOIN_DOMAIN 0x00000001	Verknüpft den Computer mit einer Domäne. Wenn dieser Wert nicht angegeben wird, wird der Computer mit einer Arbeitsgruppe verknüpft.
NETSETUP_ACCT_CREATE 0x00000002	Erstellt das Konto für die Domäne.
NETSETUP_WIN9X_UPGRADE 0x00000010	Der Joinvorgang erfolgt im Rahmen eines Upgrades.
NETSETUP_DOMAIN_JOIN_IF_JOINED 0x00000020	Ermöglicht eine Verknüpfung mit einer neuen Domäne, auch wenn der Computer bereits einer Domäne zugeordnet ist.
NETSETUP_JOIN_UNSECURE 0x00000040	Führt einen unsicheren Beitritt durch. Diese Option fordert einen Domänenbeitritt zu einem vorab erstellten Konto an, ohne sich mit Domänenbenutzeranmeldeinformationen zu authentifizieren. Diese Option kann in Verbindung mit NETSETUP_MACHINE_PWD_PASSED Option verwendet werden. In diesem Fall ist lpPassword das Kennwort des vorab erstellten Computerkontos. Vor Windows Vista mit SP1 und Windows Server 2008 wurde eine unsichere Verknüpfung nicht beim Domänencontroller authentifiziert. Die gesamte Kommunikation wurde mit einer NULL-Sitzung (nicht authentifiziert) durchgeführt. Ab Windows Vista mit SP1 und Windows Server 2008 werden der Computerkontoname und das Kennwort zur Authentifizierung beim Domänencontroller verwendet.
NETSETUP_MACHINE_PWD_PASSED 0x00000080	Gibt an, dass der lpPassword-Parameter anstelle eines Benutzerkennworts ein Kennwort für ein lokales Computerkonto angibt. Dieses Flag gilt nur für ungesicherte Joins, die Sie durch Festlegen des NETSETUP_JOIN_UNSECURE-Flags angeben müssen. Wenn Sie dieses Flag festlegen, wird das Computerkennwort nach erfolgreichem Joinvorgang auf den Wert von lpPassword festgelegt, wenn es sich bei diesem Wert um ein gültiges Computerkennwort handelt.
NETSETUP_DEFER_SPN_SET 0x00000100	Gibt an, dass der Dienstprinzipalname (Service Principal Name, SPN) und die DnsHostName-Eigenschaften auf dem Computerobjekt zu diesem Zeitpunkt nicht aktualisiert werden sollten. In der Regel werden diese Eigenschaften während des Joinvorgangs aktualisiert. Stattdessen sollten diese Eigenschaften während eines nachfolgenden Aufrufs der NetRenameMachineInDomain-Funktion aktualisiert werden. Diese Eigenschaften werden während des Umbenennungsvorgangs immer aktualisiert. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
NETSETUP_JOIN_DC_ACCOUNT 0x00000200	Lassen Sie den Domänenbeitritt zu, wenn das vorhandene Konto ein Domänencontroller ist. Hinweis Dieses Flag wird unter Windows Vista und höher unterstützt.
NETSETUP_JOIN_WITH_NEW_NAME 0x00000400	Verknüpfen Sie den im lpServer-Parameter angegebenen Zielcomputer mit einem neuen Namen, der von der Registrierung auf dem im lpServer-Parameter angegebenen Computer abgefragt wird. Diese Option wird verwendet, wenn SetComputerNameEx vor dem Neustart des Computers aufgerufen wurde. Der neue Computername wird erst bei einem Neustart wirksam. Mit dieser Option weist der Aufrufer die NetJoinDomain-Funktion an, den neuen Namen während des Domänenbeitrittsvorgangs zu verwenden. Nach dem erfolgreichen Aufruf von NetJoinDomain ist ein Neustart erforderlich, zu dem sich sowohl die Änderung des Computernamens als auch die Änderung der Domänenmitgliedschaft auswirken. Hinweis Dieses Flag wird unter Windows Vista und höher unterstützt.
NETSETUP_JOIN_READONLY 0x00000800	Verknüpfen Sie den im lpServer-Parameter angegebenen Zielcomputer mithilfe eines vorab erstellten Kontos, ohne dass ein beschreibbarer Domänencontroller erforderlich ist. Diese Option bietet die Möglichkeit, einen Computer mit einer Domäne zu verknüpfen, wenn ein Konto bereits bereitgestellt und auf einen schreibgeschützten Domänencontroller repliziert wurde. Der schreibgeschützte Zieldomänencontroller wird als Teil des lpDomain-Parameters angegeben, nachdem der Domänenname durch ein "\"-Zeichen getrennt ist. Diese Bereitstellung muss den Geheimen Computer enthalten. Das Computerkonto muss über die Gruppenmitgliedschaft der Liste zulässiger Kennwortreplikationsrichtlinien hinzugefügt werden, und das Kontokennwort muss vor dem Joinvorgang auf den schreibgeschützten Domänencontroller repliziert werden. Weitere Informationen finden Sie in den Informationen zur Verwaltung der Kennwortreplikationsrichtlinien. Ab Windows 7 besteht ein alternativer Mechanismus darin, den Offlinedomänenbeitrittsmechanismus zu verwenden. Weitere Informationen finden Sie in den Funktionen NetProvisionComputerAccount und NetRequestOfflineDomainJoin . Hinweis Dieses Flag wird unter Windows Vista und höher unterstützt.
NETSETUP_AMBIGUOUS_DC 0x00001000	Versuchen Sie beim Beitritt zur Domäne nicht, den bevorzugten Domänencontroller in der Registrierung festzulegen. Hinweis Dieses Flag wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.
NETSETUP_NO_NETLOGON_CACHE 0x00002000	Erstellen Sie beim Beitritt zur Domäne nicht den Netlogon-Cache. Hinweis Dieses Flag wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.
NETSETUP_DONT_CONTROL_SERVICES 0x00004000	Wenn Sie der Domäne beitreten, erzwingen Sie den Start des Netlogon-Diensts nicht. Hinweis Dieses Flag wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.
NETSETUP_SET_MACHINE_NAME 0x00008000	Wenn Sie der Domäne nur für offline beitreten, legen Sie den Hostnamen des Zielcomputers und den NetBIOS-Namen fest. Hinweis Dieses Flag wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.
NETSETUP_FORCE_SPN_SET 0x00010000	Wenn Sie der Domäne beitreten, überschreiben Sie während des Domänenbeitritts andere Einstellungen, und legen Sie den Dienstprinzipalnamen (Service Principal Name, SPN) fest. Hinweis Dieses Flag wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.
NETSETUP_NO_ACCT_REUSE 0x00020000	Wenn Sie der Domäne beitreten, verwenden Sie kein vorhandenes Konto wieder. Hinweis Dieses Flag wird unter Windows 7, Windows Server 2008 R2 und höher unterstützt.
NETSETUP_IGNORE_UNSUPPORTED_FLAGS 0x10000000	Wenn dieses Bit festgelegt ist, werden nicht erkannte Flags von der NetJoinDomain-Funktion ignoriert, und NetJoinDomain verhält sich so, als wären die Flags nicht festgelegt.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NERR_Success.

Wenn die Funktion fehlschlägt, kann der Rückgabewert einer der folgenden Fehlercodes oder einer der Systemfehlercodes sein.

Rückgabecode	Beschreibung
ERROR_ACCESS_DENIED	Der Zugriff wird verweigert. Dieser Fehler wird zurückgegeben, wenn der Aufrufer kein Mitglied der lokalen Gruppe Administratoren auf dem Zielcomputer war.
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn der lpDomain-ParameterNULL ist.
ERROR_NO_SUCH_DOMAIN	Die angegebene Domäne war nicht vorhanden.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der im parameter lpServer angegebene Computer einige der im Parameter fJoinOptions übergebenen Optionen nicht unterstützt.
NERR_InvalidWorkgroupName	Der angegebene Arbeitsgruppenname ist ungültig.
NERR_SetupAlreadyJoined	Der Computer ist bereits mit einer Domäne verbunden.
NERR_WkstaNotStarted	Der Arbeitsstationsdienst wurde nicht gestartet.
RPC_S_CALL_IN_PROGRESS	Für diesen Thread wird bereits ein Remoteprozeduraufruf ausgeführt.
RPC_S_PROTSEQ_NOT_SUPPORTED	Die Protokollsequenz des Remoteprozeduraufrufs wird nicht unterstützt.

Hinweise

Das Verknüpfen (und Aufheben der Verknüpfung) eines Computers mit einer Domäne oder Arbeitsgruppe kann nur von einem Mitglied der lokalen Gruppe Administratoren auf dem Zielcomputer durchgeführt werden. Beachten Sie, dass der Domänenadministrator zusätzliche Anforderungen für den Domänenbeitritt durch Delegierung und Zuweisung von Berechtigungen festlegen kann.

Wenn Sie die NetJoinDomain-Funktion remote aufrufen, müssen Sie Anmeldeinformationen angeben, da Sie anmeldeinformationen unter diesen Umständen nicht delegieren können.

Verschiedene Prozesse oder unterschiedliche Threads desselben Prozesses sollten die NetJoinDomain-Funktion nicht gleichzeitig aufrufen. Diese Situation kann den Computer in einem inkonsistenten Zustand belassen.

Wenn während eines Joinvorgangs ein Problem auftritt, sollten Sie ein Computerkonto nicht löschen und dem Löschvorgang sofort einen weiteren Joinversuch folgen. Dies kann zu Replikationsproblemen führen, die schwer zu untersuchen sind. Wenn Sie ein Computerkonto löschen, warten Sie, bis die Änderung auf alle Domänencontroller repliziert wurde, bevor Sie versuchen, einen weiteren Joinvorgang durchzuführen.

Nach dem Aufrufen der NetJoinDomain-Funktion ist ein Systemneustart erforderlich, damit der Vorgang abgeschlossen werden kann.

Windows Server 2003 und Windows XP: Wenn ein Aufruf der NetJoinDomain-Funktion einem Aufruf der NetRenameMachineInDomain-Funktion vorangestellt wird, sollten Sie die Aktualisierung der Eigenschaften SPN und DnsHostName für das Computerobjekt bis zum Umbenennungsvorgang zurückstellen. Dies liegt daran, dass der Joinvorgang in bestimmten Situationen fehlschlagen kann. Ein Beispiel für eine solche Situation ist, wenn der vom aktuellen Computernamen abgeleitete SPN in der neuen Domäne, der der Computer beitritt, ungültig ist, aber der SPN, der von dem neuen Namen abgeleitet wird, den der Computer nach dem Umbenennungsvorgang haben wird, in der neuen Domäne gültig ist. In diesem Fall schlägt der Aufruf von NetJoinDomain fehl, es sei denn, Sie verzögern die Aktualisierung der beiden Eigenschaften bis zum Umbenennungsvorgang, indem Sie das flag NETSETUP_DEFER_SPN_SET im fJoinOptions-Parameter angeben, wenn Sie NetJoinDomain aufrufen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	lmjoin.h (lm.h einschließen)
Bibliothek	Netapi32.lib
DLL	Netapi32.dll