WdfUsbTargetDeviceQueryUsbCapability function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF and UMDF]

The WdfUsbTargetDeviceQueryUsbCapability method determines whether the host controller and USB driver stack support a specific capability.

Syntax

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

Parameters

[in] UsbDevice

A handle to a USB device object.

[in] CapabilityType

A pointer to a GUID that represents the capability about which the client driver wants to retrieve information. The possible PGUID values are as follows:

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

See more information in Remarks.

[in] CapabilityBufferLength

Length, in bytes, of the buffer pointed to by CapabilityBuffer.

[out, optional] CapabilityBuffer

A pointer to a caller-allocated buffer to receive the requested USB capability. This parameter is optional. If CapabilityBufferLength is zero, this parameter must be NULL. Similarly, if CapabilityBufferLength is nonzero, this parameter must be supplied. This parameter corresponds to the OutputBuffer parameter of the USBD_QueryUsbCapability routine.

[out, optional] ResultLength

A pointer to a location containing the size, in bytes, of the returned capability. This parameter is optional.

Return value

WdfUsbTargetDeviceQueryUsbCapability returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:

Return code	Description
STATUS_INVALID_DEVICE_STATE	The USB device object handle is not valid.
STATUS_INSUFFICIENT_RESOURCES	Insufficient memory was available.
STATUS_INVALID_PARAMETER	The caller passed an invalid parameter value. UsbDevice or CapabilityType is NULL. CapabilityBuffer is NULL but CapabilityBufferLength contains a nonzero value. Conversely, the caller provided a CapabilityBuffer but CapabilityBufferLength is zero.
STATUS_NOT_IMPLEMENTED	The specified capability is not supported by the underlying USB driver stack.
STATUS_NOT_SUPPORTED	The specified capability is not supported by the host controller hardware.

This method also might return other NTSTATUS values.

Remarks

Before calling WdfUsbTargetDeviceQueryUsbCapability, the driver must call WdfUsbTargetDeviceCreateWithParameters to register with the underlying USB driver stack.

WdfUsbTargetDeviceQueryUsbCapability must be called after the driver's EvtDevicePrepareHardware callback function has been called.

The following table describes the USB-specific capabilities that a KMDF-based USB client driver can query through a WdfUsbTargetDeviceQueryUsbCapability call.

Capability GUID	Description
GUID_USB_CAPABILITY_CHAINED_MDLS	The new USB driver stack in Windows 8 is capable of accepting a chained MDL (see MDL) from the a KMDF-based USB client driver. For more information about the chained MDLs capability in the USB driver stack, see How to Send Chained MDLs. This GUID applies to KMDF drivers only.
GUID_USB_CAPABILITY_STATIC_STREAMS	Whereas USB 2.0 and earlier supports sending only a single data stream through a bulk endpoint, USB 3.0 permits sending and receiving multiple data streams through a bulk endpoint. For more information about opening streams, see How to Open and Close Static Streams in a USB Bulk Endpoint. This GUID applies to KMDF drivers only.
GUID_USB_CAPABILITY_FUNCTION_SUSPEND	The Universal Serial Bus (USB) 3.0 specification defines a new feature called function suspend. The feature enables an individual function of a composite device to enter a low-power state, independently of other functions. For more information about function suspend, see How to Implement Function Suspend in a Composite Driver. This GUID applies to KMDF drivers only.
GUID_USB_CAPABILITY_SELECTIVE_SUSPEND	For information about selective suspend, see USB Selective Suspend. This GUID applies to KMDF drivers only.
GUID_USB_CAPABILITY_DEVICE_CONNECTION_HIGH_SPEED_COMPATIBLE	Determines whether the bus is operating at high-speed or higher. This GUID applies to KMDF and UMDF drivers.
GUID_USB_CAPABILITY_DEVICE_CONNECTION_SUPER_SPEED_COMPATIBLE	Determines whether the bus is operating at SuperSpeed or higher. This GUID applies to KMDF and UMDF drivers.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Target Platform	Universal
Minimum KMDF version	1.11
Minimum UMDF version	2.0
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI compliance rules	DriverCreate(kmdf)