NetRequestOfflineDomainJoin-Funktion (lmjoin.h)

Artikel
08/24/2023

Die NetRequestOfflineDomainJoin-Funktion wird lokal auf einem Computer ausgeführt, um ein Windows-Betriebssystemimage zu ändern, das auf einem Volume eingebunden ist. Die Registrierung wird aus dem Image geladen, und die Bereitstellungsblobdaten werden dort geschrieben, wo sie während der Abschlussphase eines Offlinedomänenbeitritts abgerufen werden können.

Syntax

NET_API_STATUS NET_API_FUNCTION NetRequestOfflineDomainJoin(
  [in] BYTE    *pProvisionBinData,
  [in] DWORD   cbProvisionBinDataSize,
  [in] DWORD   dwOptions,
  [in] LPCWSTR lpWindowsPath
);

Parameter

[in] pProvisionBinData

Ein Zeiger auf einen Puffer, der zum Initialisieren der Registrierung eines Windows-Betriebssystemimages erforderlich ist, um die endgültige lokale Zustandsänderung während der Abschlussphase des Offlinedomänenbeitritts zu verarbeiten.

Das undurchsichtige binäre Blob serialisierter Metadaten, das im pProvisionBinData-Parameter übergeben wird, wird von der NetProvisionComputerAccount-Funktion zurückgegeben.

[in] cbProvisionBinDataSize

Die Größe des Puffers in Bytes, auf den der pProvisionBinData-Parameter verweist.

Dieser Parameter darf nicht NULL sein.

[in] dwOptions

Eine Reihe von Bitflags, die Optionen für diese Funktion 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_PROVISION_ONLINE_CALLER 0x40000000	Dieses Flag ist erforderlich, wenn der lpWindowsPath-Parameter auf das aktuell ausgeführte Windows-Betriebssystemverzeichnis verweist und nicht auf ein Windows-Offlinebetriebssystemimage, das auf einem barrierefreien Volume eingebunden ist. Wenn dieses Flag angegeben wird, muss die NetRequestOfflineDomainJoin-Funktion von einem Mitglied der lokalen Gruppe Administratoren aufgerufen werden.

[in] lpWindowsPath

Ein Zeiger auf eine konstante NULL-Zeichenfolge, die den Pfad zu einem Windows-Betriebssystemimage angibt, unter dem sich die Registrierungsstrukturen befinden. Dieses Image muss offline sein und wird derzeit nicht gestartet, es sei denn, der dwOptions-Parameter enthält NETSETUP_PROVISION_ONLINE_CALLER in diesem Fall ist das lokal ausgeführte Betriebssystemverzeichnis zulässig.

Dieser Pfad kann ein UNC-Pfad auf einem Remoteserver sein.

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 nicht über ausreichende Berechtigungen zum Abschließen des Vorgangs verfügt.
ERROR_ELEVATION_REQUIRED	Für den angeforderten Vorgang sind erhöhte Rechte erforderlich.
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn die Parameter pProvisionBinData, cbProvisionBinDataSize oder lpWindowsPathNULL sind. Dieser Fehler wird auch zurückgegeben, wenn der Puffer, auf den der pProvisionBinData-Parameter verweist, keine gültigen Daten im Blob für die Domäne, den Computerkontonamen oder das Computerkontokennwort enthält. Dieser Fehler wird auch zurückgegeben, wenn die Zeichenfolge, die auf den lpWindowsPath-Parameter verweist, den Pfad zu einem Windows-Betriebssystemimage nicht bestimmt.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der angegebene Server diesen Vorgang nicht unterstützt. Beispiel: Wenn der lpWindowsPath-Parameter auf eine Windows-Installation verweist, die als Domänencontroller konfiguriert ist.
NERR_WkstaNotStarted	Der Arbeitsstationsdienst wurde nicht gestartet.

Hinweise

Die NetRequestOfflineDomainJoin-Funktion wird unter Windows 7 für Offlinedomänenbeitrittsvorgänge unterstützt.

Die NetRequestOfflineDomainJoin-Funktion wird lokal auf einem Computer verwendet, um ein auf einem Volume eingebundenes Windows-Betriebssystemimage zu ändern. Die Registrierung wird für das Image geladen, und die Bereitstellungsblobdaten werden dort geschrieben, wo sie während der Abschlussphase eines Offlinedomänenbeitritts abgerufen werden können. Das Offlinedomänenbeitrittsszenario verwendet die folgenden Funktionen:

NetProvisionComputerAccount ist eine Bereitstellungsfunktion, die zuerst aufgerufen wird, um die Netzwerkvorgänge auszuführen, die zum Erstellen und Konfigurieren des Computerobjekts in Active Directory erforderlich sind. Die Ausgabe von NetProvisionComputerAccount ist ein undurchsichtiges binäres Blob mit serialisierten Metadaten, das für den nächsten Schritt verwendet wird.
NetRequestOfflineDomainJoin , eine Imageinitialisierungsfunktion, wird dann aufgerufen, um die Ausgabe aus der NetProvisionComputerAccount-Bereitstellungsfunktion in ein Windows-Betriebssystemimage einzufügen, das während der Installation verwendet werden soll. Änderungen am Windows-Initialisierungscode erkennen diesen gespeicherten Zustand und wirken sich auf den lokalen Teil des Domänenbeitritts aus.

Die NetProvisionComputerAccount-Funktion erstellt oder wiederverwendet das Computerkonto in der Domäne, sammelt alle erforderlichen Metadaten und gibt es in einem undurchsichtigen Binärblob oder als Text zum Einbetten in eine unbeaufsichtigte Setupantwortdatei zurück. Das undurchsichtige Binärblob kann vom Offline-Domänenbeitrittsvorgang verwendet werden, der alle erforderlichen Eingaben für den Domänenbeitritt beim ersten Start ohne Netzwerkvorgänge (nur lokale Zustandsupdates) angibt. Beachten Sie, dass das Blob das Kennwortmaterial für Computerkonten im Wesentlichen übersichtlich enthält. Der Entwurf sieht keine Vorkehrungen für die Sicherung dieser Daten vor. Dieses Problem besteht heute bei unbeaufsichtigten Setupantwortdateien, die eine Reihe von Geheimnissen enthalten können, einschließlich Domänenbenutzerkennwörtern. Der Aufrufer muss das Blob und die unbeaufsichtigten Setupdateien schützen. Die Lösungen für dieses Problem sind unterschiedlich. Als Beispiel könnte ein vorab ausgetauschter Schlüssel verwendet werden, um eine Sitzung zwischen dem Consumer und der Bereitstellungsentität zu verschlüsseln, die eine sichere Übertragung des undurchsichtigen Blobs ermöglicht.

Das undurchsichtige Blob, das im pProvisionBinData-Parameter von der NetProvisionComputerAccount-Funktion zurückgegeben wird, ist versioniert, um Interoperabilitäts- und Serviceierbarkeitsszenarien zwischen verschiedenen Versionen von Windows (Verbinden von Client, Bereitstellungscomputer und Domänencontroller) zu ermöglichen. Das Offlinebeitrittsszenario begrenzt derzeit nicht die Lebensdauer des Blobs, das von der NetProvisionComputerAccount-Funktion zurückgegeben wird.

Weitere Informationen zu Offlinedomänenbeitrittsvorgängen finden Sie in der schrittweisen Anleitung zum Offlinedomänenbeitritt.

Anforderungen


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