WdfUsbTargetDeviceQueryUsbCapability 函数 (wdfusb.h)

  • 项目

[适用于 KMDF 和 UMDF]

WdfUsbTargetDeviceQueryUsbCapability 方法确定主机控制器和 USB 驱动程序堆栈是否支持特定功能。

语法

NTSTATUS WdfUsbTargetDeviceQueryUsbCapability(
  [in]            WDFUSBDEVICE UsbDevice,
  [in]            const GUID   *CapabilityType,
  [in]            ULONG        CapabilityBufferLength,
  [out, optional] PVOID        CapabilityBuffer,
  [out, optional] PULONG       ResultLength
);

参数

[in] UsbDevice

USB 设备对象的句柄。

[in] CapabilityType

指向 GUID 的指针，该 GUID 表示客户端驱动程序要检索其信息的功能。 可能的 PGUID 值如下所示：

  • GUID_USB_CAPABILITY_CHAINED_MDLS
  • GUID_USB_CAPABILITY_STATIC_STREAMS
  • GUID_USB_CAPABILITY_SELECTIVE_SUSPEND
  • GUID_USB_CAPABILITY_FUNCTION_SUSPEND
  • GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE
  • GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE
有关详细信息，请参阅“备注”。

[in] CapabilityBufferLength

CapabilityBuffer 指向的缓冲区的长度（以字节为单位）。

[out, optional] CapabilityBuffer

指向调用方分配的缓冲区的指针，用于接收请求的 USB 功能。 此参数是可选的。 如果 CapabilityBufferLength 为零，则此参数必须为 NULL。 同样，如果 CapabilityBufferLength 不为零，则必须提供此参数。 此参数对应于 USBD_QueryUsbCapability 例程的 OutputBuffer 参数。

[out, optional] ResultLength

指向包含返回的功能的大小（以字节为单位）的位置的指针。 此参数可选。

返回值

如果操作成功，WdfUsbTargetDeviceQueryUsbCapability 将返回STATUS_SUCCESS。 否则，此方法可以返回以下值之一：

返回代码 说明
STATUS_INVALID_DEVICE_STATE
 USB 设备对象句柄无效。
STATUS_INSUFFICIENT_RESOURCES
 可用内存不足。
STATUS_INVALID_PARAMETER
 调用方传递的参数值无效。
  • UsbDevice 或 CapabilityType 为 NULL。
  • CapabilityBuffer 为 NULL，但 CapabilityBufferLength 包含非零值。 相反，调用方提供了 CapabilityBuffer， 但 CapabilityBufferLength 为零。
STATUS_NOT_IMPLEMENTED
 基础 USB 驱动程序堆栈不支持指定的功能。
STATUS_NOT_SUPPORTED
 主机控制器硬件不支持指定的功能。
 

此方法还可能返回其他 NTSTATUS 值。

注解

在调用 WdfUsbTargetDeviceQueryUsbCapability 之前，驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters 以向基础 USB 驱动程序堆栈注册。

必须在调用驱动程序的 EvtDevicePrepareHardware 回调函数后调用 WdfUsbTargetDeviceQueryUsbCapability。

下表描述了基于 KMDF 的 USB 客户端驱动程序可以通过 WdfUsbTargetDeviceQueryUsbCapability 调用查询的 USB 特定功能。

功能 GUID 说明
GUID_USB_CAPABILITY_CHAINED_MDLS Windows 8 中的新 USB 驱动程序堆栈能够接受链式 MDL (查看基于 KMDF 的 USB 客户端驱动程序中的 MDL) 。

有关 USB 驱动程序堆栈中链接的 MDL 功能的详细信息，请参阅 如何发送链接的 MDL。

此 GUID 仅适用于 KMDF 驱动程序。
GUID_USB_CAPABILITY_STATIC_STREAMS USB 2.0 及更早版本仅支持通过批量终结点发送单个数据流，而 USB 3.0 允许通过批量终结点发送和接收多个数据流。

有关打开流的详细信息，请参阅 如何在 USB 批量终结点中打开和关闭静态流。

此 GUID 仅适用于 KMDF 驱动程序。
GUID_USB_CAPABILITY_FUNCTION_SUSPEND 通用串行总线 (USB) 3.0 规范定义了一项称为函数暂停的新功能。 该功能使复合设备的单个功能能够独立于其他功能进入低功耗状态。

有关函数挂起的详细信息，请参阅 如何在复合驱动程序中实现函数挂起。

此 GUID 仅适用于 KMDF 驱动程序。
GUID_USB_CAPABILITY_SELECTIVE_SUSPEND 有关选择性挂起的信息，请参阅 USB 选择性挂起。

此 GUID 仅适用于 KMDF 驱动程序。
GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE 确定总线是高速运行还是以更高速度运行。

此 GUID 适用于 KMDF 和 UMDF 驱动程序。
GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE 确定总线是否以 SuperSpeed 或更高速度运行。

此 GUID 适用于 KMDF 和 UMDF 驱动程序。

要求

要求 值
最低受支持的客户端 Windows Vista
目标平台 通用
最低 KMDF 版本 1.11
最低 UMDF 版本 2.0
标头 wdfusb.h (包括 Wdfusb.h)
Library Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf)

另请参阅

USBD_QueryUsbCapability

WdfUsbTargetDeviceRetrieveInformation