USBD_SelectInterfaceUrbAllocateAndBuild 函数 (usbdlib.h)

  • 项目

USBD_SelectInterfaceUrbAllocateAndBuild例程分配和格式化请求选择接口或更改其备用设置所需的 URB 结构。

语法

NTSTATUS USBD_SelectInterfaceUrbAllocateAndBuild(
  [in]  USBD_HANDLE                USBDHandle,
  [in]  USBD_CONFIGURATION_HANDLE  ConfigurationHandle,
        PUSBD_INTERFACE_LIST_ENTRY InterfaceListEntry,
  [out] PURB                       *Urb
);

参数

[in] USBDHandle

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

[in] ConfigurationHandle

驱动程序堆栈完成选择配置请求后，URB 结构的 UrbSelectConfiguration.ConfigurationHandle 成员中的 USB 驱动程序堆栈返回的句柄。

InterfaceListEntry

指向调用方分配 的USBD_INTERFACE_LIST_ENTRY 结构的指针。 有关详细信息，请参阅“备注”。

[out] Urb

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

返回值

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

返回代码 说明
STATUS_SUCCESS
 例程调用成功。
STATUS_INVALID_PARAMETER
 调用方在任何参数中传递 NULL。
STATUS_INSUFFICIENT_RESOURCES
 可用内存不足，无法完成调用。

注解

在设备中选择配置后，客户端驱动程序必须调用 USBD_SelectInterfaceUrbAllocateAndBuild 例程。 选择配置请求完成后，客户端驱动程序会在 URB 的 UrbSelectConfiguration.ConfigurationHandle 成员中收到配置句柄。 必须在 USBD_SelectInterfaceUrbAllocateAndBuild 的 ConfigurationHandle 参数中指定该句柄。

客户端驱动程序调用 USBD_SelectInterfaceUrbAllocateAndBuild 为选择接口请求分配和生成 URB，以在所选配置中更改接口的备用设置。 在调用 USBD_SelectInterfaceUrbAllocateAndBuild 时，客户端驱动程序必须分配并提供指向 USBD_INTERFACE_LIST_ENTRY 结构的指针。 客户端驱动程序必须按如下所示设置结构成员：

  • InterfaceDescriptor 成员必须指向USB_INTERFACE_DESCRIPTOR结构，该结构包含接口描述符以及要选择的备用设置。 接口描述符是在上一个请求中获取的，用于获取配置描述符以及关联的接口和终结点描述符。
  • 接口成员必须为 NULL。
USBD_SelectInterfaceUrbAllocateAndBuild 分配 URB 结构，并在其中填充有关指定接口设置和终结点的信息。 例程还分配 USBD_INTERFACE_INFORMATION 结构。 除了管道信息 (结构成员) 根据指定的接口描述符进行填充。 USBD_SelectInterfaceUrbAllocateAndBuild将 USBD_INTERFACE_LIST_ENTRY 的 Interface 成员设置为 URB 中USBD_INTERFACE_INFORMATION的地址。 客户端驱动程序可以将此 URB 发送到 USB 驱动程序堆栈，以选择接口中的备用设置。

客户端驱动程序无法在单个选择接口请求中更改多个接口中的备用设置。 每个请求仅面向一个接口。

选择接口请求完成后，USB 驱动程序堆栈将使用为所选备用设置中定义的终结点打开的管道的信息填充 USBD_INTERFACE_INFORMATION 。 客户端驱动程序可以通过检查 USBD_INTERFACE_INFORMATION 的 Pipes 成员指向的数组来获取这些管道 句柄，并存储句柄以供将来的数据传输请求使用。

客户端驱动程序只能对同一备用设置的另一个选择接口请求重复使用USBD_SelectInterfaceUrbAllocateAndBuild分配的 URB。 客户端驱动程序 不得 将 URB 用于任何其他类型的请求，或针对其他备用设置的另一个选择接口请求重复使用 URB。 在某些情况下，重用现有 URB 是首选方法，而不是分配新的 URB。 假设 USB 音频设备具有具有两个备用设置的接口，这些设置是针对两个带宽要求定义的。 设置 0 是为零带宽定义的;设置 1 定义为使用一定数量的带宽。 客户端驱动程序希望在两个设置之间频繁切换，具体取决于设备是否正在使用。 若要实现此方案，客户端驱动程序可以为选择接口请求分配两个 URL，每个设置一个。 客户端驱动程序可以使用 (，并重复使用) URB 进行选择接口请求，以便在有声音要发送到设备时选择“设置 1”。 为了在没有任何声音时节省带宽，客户端驱动程序可以使用 (并重复使用) 另一个 URB 切换到“设置 0”。 此实现可防止客户端驱动程序每次需要更改设置时，为每个选择接口请求分配 URL。

要求

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

另请参阅

USBD_CreateHandle

USBD_SelectConfigUrbAllocateAndBuild