NetRequestProvisioningPackageInstall 函式 (lmjoin.h)

發行項
08/24/2023

NetRequestProvisioningPackageInstall函式會在本機電腦上執行，以修改掛接在磁片區上的 Windows 作業系統映射。登錄會從映射載入，而布建套件資料會寫入其中，您可以在離線網域加入作業的完成階段中擷取它。

語法

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

參數

[in] pPackageBinData

初始化 Windows 作業系統映射登錄所需的緩衝區指標，以處理離線網域加入作業完成階段期間的最終本機狀態變更。

NetCreateProvisioningPackage 函式會傳回pPackageBinData參數中所傳遞序列化中繼資料的不透明二進位 Blob。

[in] dwPackageBinDataSize

pPackageBinData參數所指向緩衝區的大小，以位元組為單位。

此參數不得為 Null。

[in] dwProvisionOptions

定義此函式選項的一組位旗標。此參數使用 Lmjoin.h 標頭檔中定義的下列一或多個值。

值	意義
NETSETUP_PROVISION_ONLINE_CALLER 0x40000000	如果 lpWindowsPath 參數參考目前執行的 Windows 作業系統目錄，而不是掛接在可存取磁片區上的離線 Windows 作業系統映射，則需要此旗標。如果指定此旗標，則必須由本機 Administrators 群組的成員叫用 NetRequestProvisioningPackageInstall 函式。

[in] lpWindowsPath

Null終止字元字串的指標，指定登錄區所在 Windows 作業系統映射的路徑。除非 dwProvisionOptions 參數包含 NETSETUP_PROVISION_ONLINE_CALLER，否則此映射必須離線且目前無法開機，在此情況下，允許本機執行的作業系統目錄。

此路徑可能是遠端伺服器上的 UNC 路徑。

pvReserved

保留供未來使用。

傳回值

如果函式成功，傳回值會NERR_Success。

如果函式失敗，傳回值可以是下列其中一個網路管理錯誤碼。

傳回碼	描述
NERR_NoOfflineJoinInfo	找不到離線聯結完成資訊。
NERR_BadOfflineJoinInfo	離線聯結完成資訊不正確。
NERR_CantCreateJoinInfo	無法建立離線聯結資訊。請確定您可以存取指定的路徑位置和修改其內容的許可權。可能需要以提升許可權的系統管理員身分執行。
NERR_BadDomainJoinInfo	正在儲存的網域加入資訊不完整或不正確。
NERR_JoinPerformedMustRestart	離線聯結作業已順利完成，但需要重新開機。
NERR_NoJoinPending	沒有擱置中的離線聯結作業。
NERR_ValuesNotSet	無法在本機電腦上設定一或多個要求的機器或功能變數名稱值。
NERR_CantVerifyHostname	無法根據聯結完成資訊中儲存的值來驗證目前電腦的主機名稱。
NERR_CantLoadOfflineHive	無法載入指定的離線登錄區。請確定您可以存取指定的路徑位置和修改其內容的許可權。可能需要以提升許可權的系統管理員身分執行。
NERR_ConnectionInsecure	不符合此作業的最低會話安全性需求。
NERR_ProvisioningBlobUnsupported	不支援電腦帳戶布建 Blob 版本。

備註

Windows 8 支援 NetRequestProvisioningPackageInstall 函式以進行離線網域加入作業。針對 Windows 7，請使用 NetRequestOfflineDomainJoin。

離線網域加入案例使用兩個函式：

NetCreateProvisioningPackage 是布建函式，會先呼叫以執行在 Active Directory 中建立和設定電腦物件所需的網路作業。 NetCreateProvisioningPackage的輸出是用於下一個步驟的套件。
系統會呼叫 NetRequestProvisioningPackageInstall映射初始化函式，將 NetCreateProvisioningPackage 布建函式的輸出插入 Windows 作業系統映射中，以在安裝期間使用。

Windows 初始化程式碼的變更會偵測到此已儲存的狀態，並影響網域加入的僅限本機部分，並安裝套件中可能已存在的任何憑證和原則資訊。

NetCreateProvisioningPackage函式會在網域中建立或重複使用電腦帳戶、收集所有必要的中繼資料，並在套件中傳回它。離線網域加入要求作業可以使用套件，提供第一次開機期間完成網域加入的所有必要輸入，而不需要任何網路作業 (本機狀態更新) 。

安全性注意事項：NetCreateProvisioningPackage函式所建立的套件包含非常敏感的資料。它應該安全地視為純文字密碼。套件包含電腦帳戶密碼和其他網域的相關資訊，包括功能變數名稱、網域控制站的名稱，以及網域的安全性識別碼 (SID) 。如果封裝是以實體方式或透過網路傳輸，則必須小心以安全方式傳輸。設計不會布建保護此資料。此問題目前有自動安裝回應檔案存在，這些檔案可以包含一些秘密，包括網域使用者密碼。呼叫端必須保護封裝。此問題的解決方案會有所不同。例如，預先交換的金鑰可用來加密取用者與布建實體之間的會話，以安全傳輸套件。

NetCreateProvisioningPackage函式在pPackageBinData參數中傳回的套件已建立版本設定，以允許不同 Windows (版本之間的互通性和服務性案例，例如加入用戶端、布建電腦，以及使用網域控制站) 。離線聯結案例目前不會限制 NetCreateProvisioningPackage 函式所傳回之封裝的存留期。

布建程式的所有階段都會附加至 本機電腦上的 NetSetup.log 檔案。布建程式最多可以包含三部不同的電腦：建立布建套件的電腦、要求安裝套件的電腦，以及安裝封裝的電腦。根據執行的作業，所有三部電腦上都會儲存 NetSetup.log 檔案資訊。檢閱這些檔案的內容是針對線上和離線布建錯誤進行疑難排解最常見的方法。系統管理員所執行的布建作業會記錄到%WINDIR%\Debug中的NetSetup.log檔案。非系統管理員執行的布建作業會記錄到%USERPROFILE%\Debug資料夾中的NetSetup.log檔案。

需求


最低支援的用戶端	Windows 8 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 [僅限傳統型應用程式]
目標平台	Windows
標頭	lmjoin.h (包含 Lm.h)
程式庫	Netapi32.lib
Dll	Netapi32.dll