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
);

parameters

[in] pPackageBinData

指向初始化 Windows 操作系统映像注册表以在脱机域加入操作完成阶段处理最终本地状态更改所需的缓冲区的指针。

NetCreateProvisioningPackage 函数返回 pPackageBinData 参数中传递的序列化元数据的不透明二进制 Blob。

[in] dwPackageBinDataSize

pPackageBinData 参数指向的缓冲区的大小（以字节为单位）。

此参数不得为 NULL。

[in] dwProvisionOptions

一组位标志，用于定义此函数的选项。此参数使用 Lmjoin.h 头文件中定义的以下一个或多个值。

值	含义
NETSETUP_PROVISION_ONLINE_CALLER 0x40000000	如果 lpWindowsPath 参数引用当前运行的 Windows 操作系统目录，而不是装载在可访问卷上的脱机 Windows 操作系统映像，则此标志是必需的。如果指定了此标志，则 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) (安全 ID。如果正在以物理方式或通过网络传输包，则必须注意安全地传输它。该设计不对保护此数据作出任何规定。目前，无人参与安装答案文件存在此问题，这些文件可能携带大量机密，包括域用户密码。调用方必须保护包。此问题的解决方案各不相同。例如，预交换的密钥可用于加密使用者和预配实体之间的会话，从而启用包的安全传输。

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)
Library	Netapi32.lib
DLL	Netapi32.dll