使用 USB 设备

  • 项目

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

它包含以下部分：

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

创建 USB 设备对象

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

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

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

配置 USB 设备

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

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

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

选择配置后，可以根据需要更改配置接口的 备用设置 。

还可以调用 WdfUsbTargetDeviceSelectConfig 来取消配置设备。

如需相关信息，请参阅：

获取设备信息

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

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

WdfUsbTargetDeviceGetIoTarget
返回与 USB 设备关联的 I/O 目标对象的句柄。 驱动程序可以将此句柄传递给 WdfRequestSend 或 WdfIoTargetStop。

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 驱动程序通过发送包含 URB 的 I/O 请求与其 USB 设备通信，则驱动程序可以调用以下方法：

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

WdfUsbTargetDeviceCreateIsochUrb 仅 (KMDF)
分配常时等量 USB 请求块 (URB) 。 在调用 WdfUsbTargetDeviceCreateIsochUrb 之前，驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters。

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

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

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

有关 URB 的一般概念性背景，请参阅 分配和生成 URL。