使用 Windows 部署服务服务器 API

在无法使用标准 Windows 部署服务 (WDS) 解决方案的环境中，WDS 服务器会公开一个 API，使开发人员能够编写插件（称为提供程序）来处理预启动执行环境 (PXE) 请求。 开发人员在为 WDS 编写 PXE 提供程序时应遵循以下准则。

在服务器上安装 WDS 角色

• Windows 部署服务 (WDS) 是远程安装服务 (RIS) 的修订版本，需要 WDS 服务器角色才能实现 WDS PXE 服务器和提供程序。
• WDS 从 Windows Server 2008 和 Windows Server 2003 开始将 RIS 替换为 Service Pack 2 (SP2) 。
• 必须使用 Service Pack 1 (SP1) 将 RIS 服务器更新到 Windows Server 2003 上的 WDS。 可以使用 Windows 自动安装工具包 (WAIK) 安装 WDS 服务器角色。

注册提供程序

• 在安装过程中 (DLL) 注册提供程序动态链接库，并将提供程序插入到已注册提供程序的有序列表中。

  注意

  安装新的或修改的提供程序时，需要重启 WDS PXE 服务才能使更改生效。

   

• 使用 PxeProviderRegister 函数注册提供程序并将其添加到列表中。 使用 PxeProviderUnRegister 函数注销已注册的提供程序并将其从列表中删除。

• 在有序列表中指定提供程序的顺序。 无法保证列表中的提供程序的索引，因为以后可能会先注册另一个提供程序。 若要在另一个已注册的提供程序之前或之后在列表中插入提供程序，请先使用 PxeProviderQueryIndex 函数获取已注册提供程序的索引，然后在指定更大或更小的索引值的同时注册新提供程序。

• 安装可以将提供程序配置信息存储在注册提供程序时返回的注册表项下。 注册表项的地址由 PxeProviderRegister 的 phProviderKey 接收。 提供程序接收此密钥的句柄，作为其 PxeProviderInitialize 回调的 hProviderKey 参数。 提供程序应存储此密钥的地址。

• 始终在服务器的“程序文件”文件夹中安装提供程序动态链接库 (DLL) 。

Initialize

• 在提供程序中包含导出 PxeProviderInitialize 回调函数的 DLL。 每个提供程序都需要 PxeProviderInitialize 回调。 当 WDS 加载提供程序时，它会调用提供程序的 PxeProviderInitialize 函数，并将句柄传递给用于在提供程序注册期间存储配置信息的同一密钥。
• 当 PxeProviderInitialize 回调返回并成功时，提供程序应已完全初始化并准备好处理请求。
• 在 处理 PxeProviderInitialize 函数期间，注册提供程序中的每个回调。 回调应注册到 PxeRegisterCallback 函数。
• 在其 PxeProviderInitialize 函数的处理中初始化提供程序的所有内部资源。

关机

• 实现 PxeProviderShutdown 回调。 每个提供程序都需要有 一个 PxeProviderShutdown回调。
• PxeProviderShutdown 回调函数应完全关闭提供程序并释放其所有资源。
• PxeProviderShutdown 回调返回后，传递给 PxeProviderInitialize 函数的 hProvider 句柄不再有效，不应用于调用 WDS。
• 在处理 PxeProviderInitialize 回调期间，使用 PXE_CALLBACK_SHUTDOWN 调用 PxeRegisterCallback 函数来注册 PxeProviderShutdown 回调。 如果 PxeProviderInitialize 函数失败，请不要调用 PxeProviderShutdown 回调。

处理请求数据包

实现提供程序的 PxeProviderRecvRequest 回调。 每个提供程序都需要有 PxeProviderRecvRequest 回调。 当 WDS 收到请求时，它会为已注册的提供程序列表中的第一个提供程序调用 PxeProviderRecvRequest 回调。

• 如果提供程序将同步处理此请求， PxeProviderRecvRequest 函数应返回 值ERROR_SUCCESS。 如果并且仅当提供程序将异步处理此请求时， PxeProviderRecvRecvRequest 回调应返回 ERROR_IO_PENDING 并在处理请求时调用 PxeAsyncRecvDone 函数。

• PxeProviderRecvRequest 回调和 PxeAsyncRecvDone 函数返回PXE_BOOT_ACTION枚举的地址，该枚举描述提供程序为处理请求而执行的操作。

  提供程序可通过四种方式处理请求：

  • 提供程序使用包含网络启动程序路径的标准 DHCP 响应数据包回复客户端。 返回枚举 的PXE_BA_NBP 值意味着提供程序已成功处理请求数据包，并通过调用 PxePacketAllocate 和 PxeSendReply 函数发送响应数据包来完成请求。
  • 提供程序使用不符合 DHCP 的自定义响应数据包回复客户端。 返回枚举的 PXE_BA_CUSTOM 值意味着提供程序已成功处理请求数据包，并通过调用 PxePacketAllocate 和 PxeSendReply 函数发送自定义响应数据包来完成请求。
  • 提供程序确定应忽略请求。 返回 枚举PXE_BA_IGNORE 值表示提供程序已释放与请求关联的所有资源，并且请求不会传递到已注册提供程序列表中的下一个提供程序。 如果提供程序检测到请求数据包无效，则可能会使用此选项。
  • 提供程序拒绝为请求提供服务。 返回枚举 的PXE_BA_REJECT 值指示系统将请求传递给已注册提供程序列表中的下一个提供程序。 如果这是列表中的最后一个提供程序，则会释放与请求关联的所有资源，并且请求将被忽略。
  • 在处理 PxeProviderInitialize 回调期间，使用 PXE_CALLBACK_RECV_REQUEST 调用 PxeRegisterCallback 函数来注册 PxeProviderRecvRequest 回调。

生成响应数据包

• 使用 API 编写提供程序来处理 DHCP 请求并生成响应数据包。
• PxeProviderSetAttribute 函数指定提供程序用于筛选数据包的属性。 可以指定提供程序的属性，以便提供程序查看所有数据包，提供程序只看到 DHCP 数据包，或者提供程序只看到将 DHCP 供应商类标识符选项指定为“PXEClient” (60) 的 DHCP 数据包。
• PxeDhcpIsValid 函数检查数据包是否为有效的 DHCP 数据包。 当使用 PxeProviderSetAttribute 函数设置的筛选器设置为接收所有数据包以确定指定的数据包是否为有效的 DHCP 数据包时，提供程序可以使用 PxeDhcpIsValid 函数来检查来自客户端的数据包是否为 DHCP 数据包。
• PxeDhcpInitialize 函数根据从客户端接收的数据包中的信息，将响应数据包初始化为 DHCP 回复数据包。 PxeProviderInitialize 函数采用 PxeProviderRecvRequest 回调中从客户端接收的有效 DHCP 数据包的地址。 PxeDhcpInitialize 函数采用指向使用 PxePacketAllocate 函数分配的答复数据包的指针。
• PxeDhcpGetOptionValue 函数从 DHCP 数据包中检索选项值。 PxeDhcpGetVendorOptionValue 函数从 DHCP 数据包 (43) 的“供应商特定信息”字段中检索选项值。
• 然后，提供程序可以使用信息填充回复数据包，并使用 PxeSendReply 函数将答复数据包发送到客户端。 PxeDhcpAppendOption 函数将 DHCP 选项追加到回复数据包。
• 通过发送数据包响应客户端请求的提供程序必须使用 PxePacketAllocate 函数分配响应数据包。 然后，提供程序可以使用信息填充回复数据包，并使用 PxeSendReply 函数将答复数据包发送到客户端。
• 当不再需要分配的内存时，提供程序应使用 PxePacketFree 函数释放它。

枚举已注册的提供程序

• 使用 API 编写枚举和检查列表中其他已注册提供程序的提供程序。
• PxeGetServerInfo 函数返回有关 PXE 服务器的信息。 PxeGetServerInfo 函数返回一个 BOOL，指示是否为服务器启用跟踪。 TRUE 表示已启用跟踪。
• PxeProviderEnumFirst 函数在已注册的提供程序列表中启动提供程序的枚举。 PxeProviderEnumFirst 函数启动枚举并返回调用 PxeProviderEnumNext 函数时应使用的句柄的地址。 PxeProviderEnumNext 函数返回包含提供程序相关信息的PXE_PROVIDER结构。 PxeProviderFreeInfo 函数释放 PxeProviderEnumNext 函数为 PXE_PROVIDER 结构分配的内存。 PxeProviderEnumClose 函数关闭已注册提供程序列表中的提供程序枚举。

处理服务控制代码

• 收到服务控制消息时，WDS 将调用 PxeProviderServiceControl 回调。
• 提供程序可以定义 PxeProviderServiceControl 回调函数来处理服务控制消息。
• 在处理 PxeProviderInitialize 回调期间，使用 PXE_CALLBACK_SERVICE_CONTROL 调用 PxeRegisterCallback 函数来注册 PxeProviderServiceControl 回调。

将跟踪条目添加到 PXE 日志

• PxeTrace 函数将跟踪条目添加到 PXE 日志。 WDSPXE 提供跟踪来帮助管理员进行故障排除。 提供程序可以记录不同严重级别的跟踪条目。 管理员可以将 WDSPXE 配置为仅记录特定严重级别的条目。

相关主题

关于 Windows 部署服务 API

使用 Windows 部署服务客户端 API