Freigeben über


NetRequestProvisioningPackageInstall-Funktion (lmjoin.h)

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

Syntax

NET_API_STATUS NET_API_FUNCTION NetRequestProvisioningPackageInstall(
  [in] BYTE    *pPackageBinData,
  [in] DWORD   dwPackageBinDataSize,
  [in] DWORD   dwProvisionOptions,
  [in] LPCWSTR lpWindowsPath,
       PVOID   pvReserved
);

Parameter

[in] pPackageBinData

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 pPackageBinData-Parameter übergeben wird, wird von der NetCreateProvisioningPackage-Funktion zurückgegeben.

[in] dwPackageBinDataSize

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

Dieser Parameter darf nicht NULL sein.

[in] dwProvisionOptions

Eine Reihe von Bitflags, die Optionen für diese Funktion definieren. Dieser Parameter verwendet mindestens einen der folgenden Werte, 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 ist, muss die NetRequestProvisioningPackageInstall-Funktion von einem Mitglied der lokalen Gruppe Administratoren aufgerufen werden.

[in] lpWindowsPath

Ein Zeiger auf eine NULL-beendete 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 dwProvisionOptions-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.

pvReserved

Für die zukünftige Verwendung reserviert.

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 für die Netzwerkverwaltung sein.

Rückgabecode Beschreibung
NERR_NoOfflineJoinInfo
Die Informationen zur Vervollständigung des Offlinebeitritts wurden nicht gefunden.
NERR_BadOfflineJoinInfo
Die Offlinebeitrittsabschlussinformationen waren fehlerhaft.
NERR_CantCreateJoinInfo
Offlinebeitrittsinformationen können nicht erstellt werden. Stellen Sie sicher, dass Sie Zugriff auf den angegebenen Pfadspeicherort und die Berechtigungen zum Ändern des Inhalts haben. Die Ausführung als Administrator mit erhöhten Rechten ist möglicherweise erforderlich.
NERR_BadDomainJoinInfo
Die zu speichernden Domänenbeitrittsinformationen waren unvollständig oder fehlerhaft.
NERR_JoinPerformedMustRestart
Der Offlinebeitrittsvorgang wurde erfolgreich abgeschlossen, aber ein Neustart ist erforderlich.
NERR_NoJoinPending
Es war kein Offlinebeitrittsvorgang ausstehend.
NERR_ValuesNotSet
Ein oder mehrere angeforderte Computer- oder Domänennamenwerte auf dem lokalen Computer können nicht festgelegt werden.
NERR_CantVerifyHostname
Der Hostname des aktuellen Computers konnte nicht anhand des gespeicherten Werts in den Join-Vervollständigungsinformationen überprüft werden.
NERR_CantLoadOfflineHive
Die angegebene Offlineregistrierungsstruktur kann nicht geladen werden. Stellen Sie sicher, dass Sie Zugriff auf den angegebenen Pfadspeicherort und die Berechtigungen zum Ändern des Inhalts haben. Die Ausführung als Administrator mit erhöhten Rechten ist möglicherweise erforderlich.
NERR_ConnectionInsecure
Die Mindestanforderungen an die Sitzungssicherheit für diesen Vorgang wurden nicht erfüllt.
NERR_ProvisioningBlobUnsupported
Die Blobversion für die Bereitstellung von Computerkonten wird nicht unterstützt.

Hinweise

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

Das Offlinedomänenbeitrittsszenario verwendet zwei Funktionen:

  • NetCreateProvisioningPackage 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 des NetCreateProvisioningPackage ist ein Paket, das für den nächsten Schritt verwendet wird.
  • NetRequestProvisioningPackageInstall, eine Imageinitialisierungsfunktion, wird aufgerufen, um die Ausgabe aus der NetCreateProvisioningPackage-Bereitstellungsfunktion in ein Windows-Betriebssystemimage zur Verwendung während der Installation einzufügen.
Änderungen am Windows-Initialisierungscode erkennen diesen gespeicherten Zustand und wirken sich auf den lokalen Teil des Domänenbeitritts aus und installieren alle Zertifikat- und Richtlinieninformationen, die möglicherweise im Paket vorhanden waren.

Die NetCreateProvisioningPackage-Funktion erstellt oder wiederverwendet das Computerkonto in der Domäne, sammelt alle erforderlichen Metadaten und gibt es in einem Paket zurück. Das Paket kann vom Offline-Domänenbeitrittsanforderungsvorgang verwendet werden, der alle erforderlichen Eingaben zum Abschließen des Domänenbeitritts beim ersten Start ohne Netzwerkvorgänge (nur lokale Zustandsupdates) angibt.

Sicherheitshinweis: Das von der NetCreateProvisioningPackage-Funktion erstellte Paket enthält sehr vertrauliche Daten. Es sollte genauso sicher wie ein Klartextkennwort behandelt werden. Das Paket enthält das Computerkontokennwort und andere Informationen zur Domäne, einschließlich des Domänennamens, des Namens eines Domänencontrollers und der Sicherheits-ID (SID) der Domäne. Wenn das Paket physisch oder über das Netzwerk transportiert wird, muss darauf geachtet werden, dass es sicher transportiert wird. 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 Paket sichern. Die Lösungen für dieses Problem sind unterschiedlich. Beispielsweise 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 Pakets ermöglicht.

Das Paket, das im pPackageBinData-Parameter von der NetCreateProvisioningPackage-Funktion zurückgegeben wird, ist versioniert, um Interoperabilitäts- und Serviceierbarkeitsszenarien zwischen verschiedenen Versionen von Windows zu ermöglichen (z. B. das Hinzufügen eines Clients, die Bereitstellung eines Computers und die Verwendung eines Domänencontrollers). Das Offlinebeitrittsszenario begrenzt derzeit nicht die Lebensdauer des pakets, das von der NetCreateProvisioningPackage-Funktion zurückgegeben wird.

Alle Phasen des Bereitstellungsprozesses werden an eine NetSetup.log-Datei auf dem lokalen Computer angefügt. Der Bereitstellungsprozess kann bis zu drei verschiedene Computer umfassen: den Computer, auf dem das Bereitstellungspaket erstellt wird, den Computer, der die Installation des Pakets anfordert, und den Computer, auf dem das Paket installiert ist. Auf allen drei Computern werden gemäß dem ausgeführten Vorgang Informationen zur NetSetup.log-Datei gespeichert. Das Überprüfen des Inhalts dieser Dateien ist die häufigste Methode zur Problembehandlung bei Online- und Offlinebereitstellungsfehlern. Von Administratoren durchgeführte Bereitstellungsvorgänge werden in der Datei NetSetup.log in %WINDIR%\Debug protokolliert. Bereitstellungsvorgänge, die von Nichtadministratoren ausgeführt werden, werden in der Datei NetSetup.log im Ordner %USERPROFILE%\Debug protokolliert.

Anforderungen

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

Weitere Informationen

NETSETUP_PROVISIONING_PARAMS

NetCreateProvisioningPackage

NetJoinDomain

NetProvisionComputerAccount

NetRenameMachineInDomain

NetRequestOfflineDomainJoin

NetUnjoinDomain

Netzwerkverwaltungsfunktionen

Übersicht über die Netzwerkverwaltung