USBD_SelectConfigUrbAllocateAndBuild函数 (usbdlib.h)

USBD_SelectConfigUrbAllocateAndBuild 例程分配并设置 URB 结构的格式,该结构是选择 USB 设备配置所必需的。

注释 在 Windows 8 中,USBD_SelectConfigUrbAllocateAndBuild 替换 USBD_CreateConfigurationRequestExUSBD_CreateConfigurationRequest
 

语法

NTSTATUS USBD_SelectConfigUrbAllocateAndBuild(
  [in]  USBD_HANDLE                   USBDHandle,
  [in]  PUSB_CONFIGURATION_DESCRIPTOR ConfigurationDescriptor,
  [in]  PUSBD_INTERFACE_LIST_ENTRY    InterfaceList,
  [out] PURB                          *Urb
);

参数

[in] USBDHandle

客户端驱动程序在对 USBD_CreateHandle 例程的上一次调用中检索的 USBD 句柄。

[in] ConfigurationDescriptor

指向调用方分配 USB_CONFIGURATION_DESCRIPTOR 结构的指针,该结构包含要选择的配置描述符。 通常,客户端驱动程序提交类型为 URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE(请参阅 _URB_CONTROL_DESCRIPTOR_REQUEST)的 URB,以从 USB 设备检索有关配置、接口、终结点、供应商和特定于类的描述符的信息。 当客户端驱动程序将USB_CONFIGURATION_DESCRIPTOR_TYPE指定为描述符类型时,请求将检索 USB_CONFIGURATION_DESCRIPTOR 结构中的所有设备信息。 然后,驱动程序将收到的指针传递给 ConfigurationDescriptor 参数中的 USB_CONFIGURATION_DESCRIPTOR 结构。

[in] InterfaceList

指向调用方分配的 USBD_INTERFACE_LIST_ENTRY 结构数组的第一个元素的指针。 数组的长度取决于配置描述符中的接口数。 有关详细信息,请参阅“备注”。

[out] Urb

指向接收由 USBD_SelectConfigUrbAllocateAndBuild分配的 URB 的 URB 结构的指针。 当驱动程序通过调用 USBD_UrbFree完成使用它时,客户端驱动程序必须释放 URB。

返回值

USBD_SelectConfigUrbAllocateAndBuild 例程返回 NT 状态代码。

可能的值包括但不限于下表中列出的状态代码。

返回代码 描述
STATUS_SUCCESS
请求成功。
STATUS_INVALID_PARAMETER
调用方传递的参数值无效。 USBDHandleUrb 为 NULL。
STATUS_INSUFFICIENT_RESOURCES
内存不足,无法完成请求。

言论

在调用 USBD_SelectConfigUrbAllocateAndBuild之前,客户端驱动程序必须执行以下任务:

  1. 获取配置中的接口数。 此信息包含在 ConfigurationDescriptor指向的 USB_CONFIGURATION_DESCRIPTOR 结构的 bNumInterfaces 成员中。
  2. 创建 USBD_INTERFACE_LIST_ENTRY 结构的数组。 数组中的元素数必须多于接口数。 通过调用 RtlZeroMemory初始化数组。
  3. 获取配置中每个接口(或其备用设置)的接口描述符。 可以通过调用 USBD_ParseConfigurationDescriptorEx来获取这些接口描述符。
  4. 对于数组中的每个元素(最后一个元素除外),请将 InterfaceDescriptor 成员设置为接口描述符的地址。 对于数组中的第一个元素,请将 InterfaceDescriptor 成员设置为表示配置中第一个接口的接口描述符的地址。 同样,对于数组中 n 个元素,请将 InterfaceDescriptor 成员设置为表示配置中 n接口的接口描述符的地址。
  5. 必须将最后一个元素的 InterfaceDescriptor 成员设置为 NULL。
USBD_SelectConfigUrbAllocateAndBuild 执行以下任务:
  • 创建一个 URB,并使用有关指定配置、其接口和终结点的信息填充它,并将请求类型设置为URB_FUNCTION_SELECT_CONFIGURATION。
  • 为每个接口填充 URB 中的 USBD_INTERFACE_INFORMATION 结构。
  • 将调用方提供的 USBD_INTERFACE_LIST_ENTRY 数组的第 个元素的 Interface 成员设置为 URB 中相应 USBD_INTERFACE_INFORMATION 结构的地址。
可以使用收到的指向 URB 结构的指针将选择配置请求提交到 USB 驱动程序堆栈以设置指定的配置。 此外,可以使用数组中每个 USBD_INTERFACE_INFORMATION 结构的 接口 成员来获取有关接口的信息。 在每个 USBD_INTERFACE_INFORMATION 结构中,管道 成员是 USBD_PIPE_INFORMATION 结构的数组。 每个 USBD_PIPE_INFORMATION 结构都包含有关该接口中终结点打开的管道(由 USB 驱动程序堆栈)的信息。 可以从数组获取管道句柄,并存储这些句柄,以便将来向设备发出 I/O 请求。

要求

要求 价值
最低支持的客户端 需要适用于 Windows 8 的 WDK。 面向 Windows Vista 和更高版本的 Windows作系统。
目标平台 桌面
标头 usbdlib.h
Usbdex.lib
IRQL DISPATCH_LEVEL

另请参阅

USBD_CreateConfigurationRequestEx

USBD_CreateHandle