使用 USB 设备

本主题介绍从版本2开始 Kernel-Mode Driver framework (KMDF) 或 User-Mode Driver framework (UMDF) 驱动程序的操作可以使用 Windows 项驱动程序框架 (WDF) 提供的 USB 设备对象方法执行。

它包含以下部分:

有关编写简单的基于 KMDF 的 USB 客户端驱动程序的分步说明,请参阅 如何编写第一个 usb 客户端驱动程序 (KMDF)

创建 USB 设备对象

若要使用框架的 USB i/o 目标对象 (WDFUSBDEVICE、WDFUSBINTERFACE 和 WDFUSBPIPE) ,你的客户端驱动程序必须先调用 WdfUsbTargetDeviceCreateWithParameters ,才能创建 USB 设备对象。 通常,驱动程序从其EvtDevicePrepareHardware回调函数调用WdfUsbTargetDeviceCreateWithParameters

当驱动程序调用 WdfUsbTargetDeviceCreateWithParameters时,框架会创建一个 WDFUSBDEVICE 对象,并将其与表示该 USB 设备的 FDO 相关联。 方法返回新的框架 USB 设备对象的句柄,USB 客户端驱动程序可使用该对象与物理设备通信。

调用 WdfUsbTargetDeviceCreateWithParameters之后,驱动程序可以调用 WdfUsbTargetDeviceGetDeviceDescriptorWdfUsbTargetDeviceRetrieveConfigDescriptor 从设备获取 USB 描述符。 这些描述符包含有关设备的第一个配置、其接口设置及其定义的终结点的信息。 (在官方 USB 规范中定义 USB 描述符 )

配置 USB 设备

WdfUsbTargetDeviceCreateWithParameters方法还会为设备的第一个配置所包含的每个 USB 接口创建一个框架 usb 接口对象。

调用 WdfUsbTargetDeviceCreateWithParameters之后,客户端驱动程序必须调用 WdfUsbTargetDeviceSelectConfig 来选择配置。 此方法为所选配置中接口的每个替代设置创建框架接口对象。

方法还会创建管道对象,这些对象表示在所选配置的每个接口的每个替代设置中定义的终结点。

选择配置后,如果需要,可以更改配置接口的 备用设置

你还可以调用 WdfUsbTargetDeviceSelectConfig 来 deconfigure 设备。

如需相关信息,请参阅:

获取设备信息

配置设备后,客户端驱动程序可以调用以下方法来获取有关 USB 设备的信息:

WdfUsbTargetDeviceQueryUsbCapability
确定主机控制器和 USB 驱动程序堆栈是否支持特定功能。 在调用 WdfUsbTargetDeviceQueryUsbCapability之前,驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceGetIoTarget
返回与 USB 设备关联的 i/o 目标对象的句柄。 驱动程序可以将此句柄传递给 WdfRequestSendWdfIoTargetStop

WdfUsbTargetDeviceRetrieveInformation
检索与 USB 设备关联的版本和功能信息。

WdfUsbTargetDeviceIsConnectedSynchronous (KMDF 仅)
确定设备是否已连接。

WdfUsbTargetDeviceRetrieveCurrentFrameNumber (KMDF 仅)
检索当前的 USB 帧号。

获取 USB 描述符

若要获取 USB 设备描述符中包含的 Unicode 字符串,驱动程序可以调用以下任一方法:

WdfUsbTargetDeviceGetDeviceDescriptor
获取设备的 USB 设备描述符

WdfUsbTargetDeviceRetrieveConfigDescriptor
获取设备的 USB 配置描述符、接口描述符和终结点说明符。

WdfUsbTargetDeviceQueryString
将 Unicode 字符串复制到驱动程序提供的缓冲区。

WdfUsbTargetDeviceAllocAndQueryString
将 Unicode 字符串复制到框架提供的缓冲区。

WdfUsbTargetDeviceFormatRequestForString
格式化 Unicode 字符串的请求。 驱动程序可以调用 WdfRequestSend 来同步或异步发送请求。

发送控件传输

驱动程序可以调用以下方法发送 i/o 请求,这些请求描述了标准的设备特定于设备或特定于供应商的 USB 控制传输。

WdfUsbTargetDeviceSendControlTransferSynchronously
同步发送 USB 控件传输请求。

WdfUsbTargetDeviceFormatRequestForControlTransfer
格式化 USB 控件传输请求。 驱动程序可以调用 WdfRequestSend 来同步或异步发送请求。

有关相关信息,请参阅 如何发送 USB 控件传输

重置并 Power-Cycling 设备端口

你的驱动程序可以调用以下方法来重置或重启设备连接到的 USB 端口:

WdfUsbTargetDeviceResetPortSynchronously
同步发送用于重置设备 USB 端口的请求。

WdfUsbTargetDeviceCyclePortSynchronously (KMDF 仅)
以同步方式将请求发送到设备的 USB 端口。

WdfUsbTargetDeviceFormatRequestForCyclePort (KMDF 仅)
格式化请求以对设备的 USB 端口进行电源重启。 驱动程序必须调用 WdfRequestSend 以同步或异步发送请求。

有关相关信息,请参阅 如何从 USB 管道中恢复错误

将 URB 发送到设备

如果 KMDF 驱动程序通过发送 i/o 请求(其中包含 URBs)与 USB 设备通信,则驱动程序可以调用以下方法:

WdfUsbTargetDeviceCreateUrb (KMDF 仅)
(URB) 分配 USB 请求块。 在调用 WdfUsbTargetDeviceCreateUrb之前,驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceCreateIsochUrb (KMDF 仅)
分配 (URB) 的同步 USB 请求块。 在调用 WdfUsbTargetDeviceCreateIsochUrb之前,驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceSendUrbSynchronously (KMDF 仅)
同步发送包含 URB 的 i/o 请求。

WdfUsbTargetDeviceFormatRequestForUrb (KMDF 仅)
设置包含 URB 的 i/o 请求的格式。 驱动程序必须调用 WdfRequestSend 以同步或异步发送请求。

WdfUsbTargetDeviceWdmGetConfigurationHandle (KMDF 仅)
返回设备的 USBD 配置句柄。 一些 URBs 需要此句柄。

有关 URBs 的一般概念背景,请参阅 分配和生成 URBs