NetCreateProvisioningPackage 函式 (lmjoin.h)
NetCreateProvisioningPackage 函式會建立布建套件，以布建計算機帳戶以供稍後在離線網域加入作業中使用。 套件也可能包含在布建期間新增至計算機之憑證和原則的相關信息。
語法
NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
[in] PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
[out, optional] PBYTE *ppPackageBinData,
[out, optional] DWORD *pdwPackageBinDataSize,
[out, optional] LPWSTR *ppPackageTextData
);
參數
[in] pProvisioningParams
包含布建套件相關信息 之NETSETUP_PROVISIONING_PARAMS 結構的指標。
下列值會針對這個 結構的成員定義：
| 值 | 意義 |
|---|---|
|
布建套件中的 Windows 版本。 此成員應該使用 Lmjoin.h 頭檔中定義的下列值： NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001) |
|
常數 Null 終止字元字串的指標，指定計算機帳戶建立所在的網域名稱。 |
|
常數 Null 終止字元字串的指標，指定計算機帳戶屬性 sAMAccountName 衍生來源之電腦的簡短名稱，方法是附加 『$』。 此參數必須包含有效的 DNS 或 NetBIOS 機器名稱。 |
|
固定 Null 終止字元字串的選擇性指標，其中包含要在其中建立電腦帳戶之組織單位的 RFC 1779 格式名稱 (OU) 。 如果您指定此參數，字串必須包含完整路徑，例如 OU=testOU，DC=domain，DC=Domain，DC=com。 否則，此參數必須是 NULL。
如果此參數為 NULL，則已知計算機物件容器將作為在網域中發佈。 |
|
包含要鎖定之域控制器名稱的常數 Null 終止字元字串選擇性指標。 |
|
定義布建選項的一組位旗標。 此參數可以是傳遞至 NetProvisionComputerAccount 函式之 dwOptions 參數所指定的一或多個值。
這些可能的值定義於 Lmjoin.h 頭檔中。 Windows 8 和 Windows Server 2012 僅支援NETSETUP_PROVISION_ROOT_CA_CERTS選項。 |
|
NULL 終止證書範本名稱數位的選擇性指標。 |
|
當 aCertTemplateNames 不是 NULL 時，這個成員會提供數位中項目的明確計數。 |
|
NULL 終止計算機原則名稱陣列的選擇性指標。 |
|
當 aMachinePolicyNames 不是 NULL 時，此成員會提供數位中項目的明確計數。 |
|
字元字串數位的選擇性指標。 每個陣列元素都是NULL終止的字元字串，指定登錄原則檔格式之檔案的完整或部分路徑。 如需登錄原則檔格式的詳細資訊，請參閱 登錄原則檔格式
路徑可能是遠端伺服器上的 UNC 路徑。 |
|
當 aMachinePolicyPaths 不是 NULL 時，此成員會提供數位中項目的明確計數。 |
[out, optional] ppPackageBinData
選擇性指標，如果 NetProvisionComputerAccount 函式成功完成，將會收到 NetRequestOfflineDomainJoin 函式所需的套件，以完成離線網域聯結。 數據會以不透明二進位緩衝區的形式傳回，此緩衝區可能會傳遞至 NetRequestOfflineDomainJoin 函式。
如果此參數為 NULL，則 pPackageTextData 參數不得為 NULL。 如果此參數不是 NULL， 則 pPackageTextData 參數必須是 NULL。
[out, optional] pdwPackageBinDataSize
值的指標，這個值會接收 pProvisionBinData 參數中傳回之緩衝區的大小，以位元組為單位。
如果 pPackageBinData 參數不是 NULL，這個參數不得為 NULL。 當 pPackageBinData 參數為 NULL 時，此參數必須是 NULL。
[out, optional] ppPackageTextData
選擇性指標，如果 NetProvisionComputerAccount 函式成功完成，將會收到 NetRequestOfflineDomainJoin 函式所需的套件，以完成離線網域聯結。 數據會以字串形式傳回，以便內嵌在自動安裝響應檔案中。
如果此參數為 NULL， 則 pPackageBinData 參數不得為 NULL。 如果此參數不是 NULL， 則 pPackageBinData 參數必須是 NULL。
傳回值
如果函式成功，傳回值會NERR_Success。
如果函式失敗，傳回值可以是下列其中一個錯誤碼或其中一個 系統錯誤碼。
| 傳回碼 | Description |
|---|---|
|
存取遭到拒絕。 如果呼叫端沒有足夠的許可權來完成作業，就會傳回此錯誤。 |
|
此作業僅適用於網域的主要域控制器。 如果在 pProvisioningParams 參數所指向之NETSETUP_PROVISIONING_PARAMS結構的 lpDcName 中指定域控制器名稱，但指定的電腦無法驗證為NETSETUP_PROVISIONING_PARAMS之 lpDomain 中指定的目標網域的域控制器，就會傳回此錯誤。 |
|
參數不正確。 如果 pProvisioningParams 參數都是 NULL，也會傳回此錯誤。 如果 pProvisioningParams 參數所指向之NETSETUP_PROVISIONING_PARAMS結構的 lpDomain 或 lpMachineName 成員為 NULL，也會傳回此錯誤。 |
|
指定的網域不存在。 |
|
不支援此要求。 如果 pProvisioningParams 參數所指向的 NETSETUP_PROVISIONING_PARAMS 結構中指定了 lpMachineAccountOU 成員，而且域控制器正在不支援此參數的舊版 Windows 上執行，就會傳回此錯誤。 |
|
指定的域控制器不符合此作業的版本需求。 |
|
這項作業需要支援LDAP的域控制器。 |
|
帳戶已存在於網域中，而且 pProvisioningParams 參數所指向之NETSETUP_PROVISIONING_PARAMS結構的 dwProvisionOptions 成員中未指定NETSETUP_PROVISION_REUSE_ACCOUNT位。 |
|
工作站服務尚未啟動。 |
|
此線程已經在進行遠端過程調用。 |
|
不支援遠端過程調用通訊協定序列。 |
備註
離線聯結作業支援 Windows 8和 Windows Server 2012 NetCreateProvisioningPackage 函式。 針對 Windows 7，請使用 NetProvisionComputerAccount 函式。
NetCreateProvisioningPackage 函式可用來布建計算機帳戶，以便稍後使用 NetRequestProvisioningPackageInstall 函式在離線網域加入作業中使用。
離線網域加入案例使用兩個函式：
- NetCreateProvisioningPackage 是布建函式，會先呼叫以執行在 Active Directory 中建立和設定計算機物件所需的網路作業。 NetCreateProvisioningPackage 的輸出是用於下一個步驟的套件。
- 系統會呼叫 NetRequestProvisioningPackageInstall 映射，將 NetCreateProvisioningPackage 布建函式的輸出插入 Windows 操作系統映像，以在安裝前和安裝後使用。
使用 pPackageBinData 和 pdwPackageBinDataSize out 指標時，請將 pPackageTextData out 指標設定為 NULL。 使用 pPackageTextData 時，請將 pPackageBinData 和 pdwPackageBinDataSize out 指標設定為 NULL。
pProvisioningParams 參數會指定要包含在布建套件中的數據。 套件包含與網域加入相關的資訊，也可以包含要安裝在計算機上的原則和憑證的相關信息。 布建套件可以使用四種方式：
- 網域加入
- 加入網域並安裝憑證
- 網域加入和安裝原則
- 加入網域及安裝憑證和原則
NetCreateProvisioningPackage 函式會在網域中建立或重複使用計算機帳戶、收集所有必要的元數據，並在套件中傳回它。 離線網域加入要求作業可以使用套件，提供第一次開機期間完成網域加入的所有必要輸入，而不需要任何網路作業 (本機狀態更新) 。
安全性注意事項： NetCreateProvisioningPackage 函式所傳回的套件包含非常敏感的數據。 它應該安全地視為純文本密碼。 套件包含計算機帳戶密碼和其他網域的相關信息，包括功能變數名稱、域控制器的名稱，以及網域的安全性標識碼 (SID) 。 如果封裝是以實體方式或透過網路傳輸，則必須小心以安全方式傳輸。 設計不會布建保護此數據。 此問題目前有自動安裝回應檔案存在，這些檔案可以包含一些秘密，包括網域用戶密碼。 呼叫端必須保護封裝。 此問題的解決方案會有所不同。 例如，預先交換的密鑰可用來加密取用者與布建實體之間的會話，以安全傳輸套件。
NetCreateProvisioningPackage 函式在 pPackageBinData 參數中傳回的套件已建立版本設定，以允許不同 Windows (版本之間的互操作性和服務性案例，例如加入用戶端、布建計算機，以及使用域控制器) 。 在 Windows 8 或 Windows Server 2012 上建立的套件可以使用 Windows 7 或 Windows Server 2008 R2，不過只有網域加入資訊才會生效， (憑證和原則不受支援) 。 離線聯結案例目前不會限制 NetCreateProvisioningPackage 函式所傳回之封裝的存留期。
針對離線網域加入，執行的存取檢查取決於網域的設定。 使用三種方法開啟電腦帳戶建立：
- 網域系統管理員有權建立計算機帳戶。
- 容器上的 SD 可以委派建立電腦帳戶的許可權。
- 根據預設，已驗證的使用者可能會依許可權建立計算機帳戶。 已驗證的使用者僅限於建立在網域上指定為配額的有限帳戶數目， (預設值為10) 。 如需詳細資訊，請參閱 Active Directory 架構中的 ms-DS-MachineAccountQuota 屬性。
NetCreateProvisioningPackage 函式只適用於可寫入的域控制器，而且不適用於唯讀域控制器。 針對可寫入的域控制器進行布建且帳戶複寫至只讀域控制器之後，離線網域加入作業的其他部分就不需要存取域控制器。
如果 NetCreateProvisioningPackage 函式成功，則 pPackageBinData 或 pPackageTextData 參數中的指標 (取決於哪個參數不是 NULL) 會隨著串行化數據傳回，以便用於脫機聯結作業或自動安裝檔案中的文字。
布建程式的所有階段都會附加至 本機計算機上的NetSetup.log 檔案。 布建程式最多可以包含三部不同的計算機：建立布建套件的計算機、要求安裝套件的計算機，以及安裝封裝的計算機。 根據執行的作業，所有三部計算機上都會儲存 NetSetup.log 檔案資訊。 檢閱這些檔案的內容是針對在線和離線布建錯誤進行疑難解答最常見的方法。 系統管理員所執行的布建作業會記錄到 %WINDIR%\Debug 中的NetSetup.log檔案。 非系統管理員執行的布建作業會記錄到 %USERPROFILE%\Debug 資料夾中的NetSetup.log檔案。
如需脫機網域加入作業的詳細資訊，請參閱 脫機網域加入逐步指南。
使用 NetJoinDomain 和 NetUnjoinDomain 將電腦加入網域 (和取消加入) 只會由目標電腦上的 Administrators 本地組成員執行。 請注意，網域系統管理員可以使用委派和指派許可權來設定加入網域的其他需求。
規格需求
| 最低支援的用戶端 | Windows 8 [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2012 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | lmjoin.h (包含 Lm.h) |
| 程式庫 | Netapi32.lib |
| Dll | Netapi32.dll |