NetCreateProvisioningPackage-Funktion (lmjoin.h)

Artikel
08/24/2023

Die NetCreateProvisioningPackage-Funktion erstellt ein Bereitstellungspaket, das ein Computerkonto zur späteren Verwendung in einem Offlinedomänenbeitritt bereitstellt. Das Paket kann auch Informationen zu Zertifikaten und Richtlinien enthalten, die während der Bereitstellung dem Computer hinzugefügt werden sollen.

Syntax

NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
  [in]            PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
  [out, optional] PBYTE                         *ppPackageBinData,
  [out, optional] DWORD                         *pdwPackageBinDataSize,
  [out, optional] LPWSTR                        *ppPackageTextData
);

Parameter

[in] pProvisioningParams

Ein Zeiger auf eine NETSETUP_PROVISIONING_PARAMS Struktur, die Informationen zum Bereitstellungspaket enthält.

Die folgenden Werte werden für die Member dieser Struktur definiert:

Wert	Bedeutung
dwVersion	Die Version von Windows im Bereitstellungspaket. Dieser Member sollte den folgenden Wert verwenden, der in der Lmjoin.h-Headerdatei definiert ist: NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001)
lpDomain	Ein Zeiger auf eine konstante NULL-endende Zeichenfolge, die den Namen der Domäne angibt, in der das Computerkonto erstellt wird.
lpMachineName	Ein Zeiger auf eine konstante NULL-endende Zeichenfolge, die den Kurznamen des Computers angibt, von dem das Computerkonto-Attribut sAMAccountName durch Anfügen eines "$" abgeleitet wird. Dieser Parameter muss einen gültigen DNS- oder NetBIOS-Computernamen enthalten.
lpMachineAccountOU	Ein optionaler Zeiger auf eine konstante NULL-endende Zeichenfolge, die den RFC 1779-Formatnamen der Organisationseinheit (OE) enthält, in der das Computerkonto erstellt wird. 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. Wenn dieser Parameter NULL ist, wird der bekannte Computerobjektcontainer wie in der Domäne veröffentlicht verwendet.
lpDcName	Ein optionaler Zeiger auf eine konstante NULL-endende Zeichenfolge, die den Namen des Domänencontrollers für das Ziel enthält.
dwProvisionOptions	Eine Reihe von Bitflags, die Bereitstellungsoptionen definieren. Bei diesem Parameter kann es sich um einen oder mehrere der Werte handeln, die für den dwOptions-Parameter angegeben sind, der an die NetProvisionComputerAccount-Funktion übergeben wird. Diese möglichen Werte werden in der Lmjoin.h-Headerdatei definiert. Die Option NETSETUP_PROVISION_ROOT_CA_CERTS wird nur für Windows 8 und Windows Server 2012 unterstützt.
aCertTemplateNames	Ein optionaler Zeiger auf ein Array von Zertifikatvorlagennamen mit NULL-Beendigung.
cCertTemplateNames	Wenn aCertTemplateNames nicht NULL ist, stellt dieses Element eine explizite Anzahl der Elemente im Array bereit.
aMachinePolicyNames	Ein optionaler Zeiger auf ein Array mit NULL-beendeten Computerrichtliniennamen.
cMachinePolicyNames	Wenn aMachinePolicyNames nicht NULL ist, stellt dieser Member eine explizite Anzahl der Elemente im Array bereit.
aMachinePolicyPaths	Ein optionaler Zeiger auf ein Array von Zeichenfolgen. Jedes Arrayelement ist eine NULL-endende Zeichenfolge, die den vollständigen oder teilweisen Pfad zu einer Datei im Format Registrierungsrichtliniendatei angibt. Weitere Informationen zum Dateiformat der Registrierungsrichtlinie finden Sie unter Registrierungsrichtliniendateiformat. Der Pfad kann ein UNC-Pfad auf einem Remoteserver sein.
cMachinePolicyPaths	Wenn aMachinePolicyPaths nicht NULL ist, stellt dieser Member eine explizite Anzahl der Elemente im Array bereit.

[out, optional] ppPackageBinData

Ein optionaler Zeiger, der das Paket empfängt, das für die NetRequestOfflineDomainJoin-Funktion erforderlich ist, um einen Offlinedomänenbeitritt abzuschließen, wenn die NetProvisionComputerAccount-Funktion erfolgreich abgeschlossen wird. Die Daten werden als undurchsichtiger binärer Puffer zurückgegeben, der an die NetRequestOfflineDomainJoin-Funktion übergeben werden kann.

Wenn dieser Parameter NULL ist, darf der pPackageTextData-Parameter nicht NULL sein. Wenn dieser Parameter nicht NULL ist, muss der pPackageTextData-ParameterNULL sein.

[out, optional] pdwPackageBinDataSize

Ein Zeiger auf einen Wert, der die Größe des Puffers in Bytes empfängt, der im Parameter pProvisionBinData zurückgegeben wird.

Dieser Parameter darf nicht NULL sein, wenn der pPackageBinData-Parameter nicht NULL ist. Dieser Parameter muss NULL sein, wenn der pPackageBinData-ParameterNULL ist.

[out, optional] ppPackageTextData

Ein optionaler Zeiger, der das Paket empfängt, das für die NetRequestOfflineDomainJoin-Funktion erforderlich ist, um einen Offlinedomänenbeitritt abzuschließen, wenn die NetProvisionComputerAccount-Funktion erfolgreich abgeschlossen wird. Die Daten werden in Zeichenfolgenform zum Einbetten in eine Unbeaufsichtigte Setupantwortdatei zurückgegeben.

Wenn dieser Parameter NULL ist, darf der pPackageBinData-Parameter nicht NULL sein. Wenn dieser Parameter nicht NULL ist, muss der pPackageBinData-ParameterNULL 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	Zugriff verweigert.“ Dieser Fehler wird zurückgegeben, wenn der Aufrufer nicht über ausreichende Berechtigungen zum Abschließen des Vorgangs verfügt.
ERROR_INVALID_DOMAIN_ROLE	Dieser Vorgang ist nur für den primären Domänencontroller der Domäne zulässig. Dieser Fehler wird zurückgegeben, wenn im lpDcName der NETSETUP_PROVISIONING_PARAMS Struktur, auf die der Parameter pProvisioningParams verweist, ein Domänencontrollername angegeben wurde, der angegebene Computer jedoch nicht als Domänencontroller für die Zieldomäne überprüft werden konnte, die in der lpDomain des NETSETUP_PROVISIONING_PARAMS angegeben ist.
ERROR_INVALID_PARAMETER	Ein Parameter ist falsch. Dieser Fehler wird auch zurückgegeben, wenn der pProvisioningParams-ParameterNULL ist. Dieser Fehler wird auch zurückgegeben, wenn das lpDomain - oder lpMachineName-Element der NETSETUP_PROVISIONING_PARAMS Struktur, auf die vom Parameter pProvisioningParams verwiesen wird, NULL 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 lpMachineAccountOU-Member in der NETSETUP_PROVISIONING_PARAMS Struktur angegeben wurde, auf die der Parameter pProvisioningParams verweist, und der Domänencontroller auf einer früheren Version von Windows ausgeführt wird, die diesen Parameter nicht unterstützt.
NERR_DS8DCRequired	Der angegebene Domänencontroller erfüllt nicht die Versionsanforderung für diesen Vorgang.
NERR_LDAPCapableDCRequired	Für diesen Vorgang ist ein Domänencontroller erforderlich, der LDAP unterstützt.
NERR_UserExists	Das Konto ist bereits in der Domäne vorhanden, und das NETSETUP_PROVISION_REUSE_ACCOUNT Bit wurde nicht im dwProvisionOptions-Member der NETSETUP_PROVISIONING_PARAMS Struktur angegeben, auf die der Parameter pProvisioningParams verweist.
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

Die NetCreateProvisioningPackage-Funktion wird für Windows 8 und Windows Server 2012 für Offlinebeitrittsvorgänge unterstützt. Verwenden Sie für Windows 7 die NetProvisionComputerAccount-Funktion .

Die NetCreateProvisioningPackage-Funktion wird verwendet, um ein Computerkonto zur späteren Verwendung in einem Offlinedomänenbeitrittsvorgang mithilfe der NetRequestProvisioningPackageInstall-Funktion bereitzustellen.

Das Szenario für den Offlinedomänenbeitritt 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 von NetCreateProvisioningPackage ist ein Paket, das für den nächsten Schritt verwendet wird.
NetRequestProvisioningPackageInstall, eine Imageinitialisierungsfunktion, wird aufgerufen, um die Ausgabe der NetCreateProvisioningPackage-Bereitstellungsfunktion zur Verwendung während der Vor- und Nachinstallation in ein Windows-Betriebssystemimage einzufügen.

Änderungen am Windows-Initialisierungscode erkennen diesen gespeicherten Zustand und wirken sich auf den rein lokalen Teil des Domänenbeitritts aus.

Wenn die Zeiger pPackageBinData und pdwPackageBinDataSize verwendet werden, legen Sie den pPackageTextData-Outzeiger auf NULL fest. Wenn pPackageTextData verwendet wird, legen Sie die Zeiger pPackageBinData und pdwPackageBinDataSize auf NULL fest.

Der Parameter pProvisioningParams gibt Daten an, die in das Bereitstellungspaket eingeschlossen werden sollen. Das Paket enthält Informationen, die für den Domänenbeitritt relevant sind, und es kann auch Informationen zu Richtlinien und Zertifikaten enthalten, die auf dem Computer installiert werden sollen. Das Bereitstellungspaket kann auf vier Arten verwendet werden:

Domänenbeitritt
Domänenbeitritt und Installation von Zertifikaten
Domänenbeitritt und Installation von Richtlinien
Domänenbeitritt und Installation von Zertifikaten und Richtlinien

Die NetCreateProvisioningPackage-Funktion erstellt oder verwendet das Computerkonto in der Domäne, sammelt alle erforderlichen Metadaten und gibt es in einem Paket zurück. Das Paket kann vom Anforderungsvorgang für den Offlinedomänenbeitritt verwendet werden, der alle erforderlichen Eingaben zum Abschließen des Domänenbeitritts während des ersten Starts ohne Netzwerkvorgänge (nur aktualisierungen des lokalen Zustands) liefert.

Sicherheitshinweis: Das von der NetCreateProvisioningPackage-Funktion zurückgegebene Paket enthält sehr vertrauliche Daten. Es sollte genauso sicher behandelt werden wie ein Klartextkennwort. 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 tritt heute bei Unbeaufsichtigten Setupantwortdateien auf, 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 vielfältig. Beispielsweise könnte ein vorab ausgetauschter Schlüssel verwendet werden, um eine Sitzung zwischen dem Consumer und der Bereitstellungsentität zu verschlüsseln, was 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 Serviceability-Szenarien zwischen verschiedenen Versionen von Windows zu ermöglichen (z. B. Das Einbinden eines Clients, die Bereitstellung eines Computers und die Verwendung eines Domänencontrollers). Ein auf Windows 8 oder Windows Server 2012 erstelltes Paket kann unter Windows 7 oder Windows Server 2008 R2 verwendet werden. Es werden jedoch nur Informationen zum Domänenbeitritt wirksam (Zertifikate und Richtlinien werden nicht unterstützt). Das Offlinebeitrittsszenario begrenzt derzeit nicht die Lebensdauer des Pakets, das von der NetCreateProvisioningPackage-Funktion zurückgegeben wird.

Bei Offlinedomänenbeitritten hängt die durchgeführte Zugriffsüberprüfung von der Konfiguration der Domäne ab. Die Computerkontoerstellung wird mithilfe von drei Methoden aktiviert:

Domänenadministratoren verfügen über Rechte zum Erstellen von Computerkonten.
Die SD in einem Container kann die Rechte zum Erstellen von Computerkonten delegieren.
Standardmäßig können authentifizierte Benutzer Computerkonten nach Berechtigungen erstellen. Authentifizierte Benutzer sind auf das Erstellen einer begrenzten Anzahl von Konten beschränkt, die als Kontingent für die Domäne angegeben werden (der Standardwert ist 10). Weitere Informationen finden Sie unter dem Attribut ms-DS-MachineAccountQuota im Active Directory-Schema.

Die NetCreateProvisioningPackage-Funktion funktioniert nur mit einem schreibbaren Domänencontroller und nicht mit einem schreibgeschützten Domänencontroller. Nachdem die Bereitstellung für einen beschreibbaren Domänencontroller erfolgt ist und das Konto auf einen schreibgeschützten Domänencontroller repliziert wird, ist für die anderen Teile des Offlinedomänenbeitritts kein Zugriff auf einen Domänencontroller erforderlich.

Wenn die NetCreateProvisioningPackage-Funktion erfolgreich ist, wird der Zeiger im pPackageBinData - oder pPackageTextData-Parameter (je nachdem, welcher Parameter nicht NULL war) mit den serialisierten Daten zur Verwendung in einem Offlineeinbindungsvorgang oder als Text in einer unbeaufsichtigten Setupdatei zurückgegeben.

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 NetSetup.log Dateiinformationen gespeichert. Das Überprüfen der Inhalte dieser Dateien ist das häufigste Mittel zur Problembehandlung bei Online- und Offlinebereitstellungsfehlern. Von Administratoren durchgeführte Bereitstellungsvorgänge werden in der NetSetup.log-Datei in %WINDIR%\Debug protokolliert. Bereitstellungsvorgänge, die von Nichtadministratoren ausgeführt werden, werden in der NetSetup.log-Datei im Ordner %USERPROFILE%\Debug protokolliert.

Weitere Informationen zu Offline-Domänenbeitrittsvorgängen finden Sie in der Schritt-für-Schritt-Anleitung zum Offlinedomänenbeitritt.

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

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