EVT_UDECX_WDF_DEVICE_QUERY_USB_CAPABILITY callback function (udecxwdfdevice.h)

  • Article

The UDE client driver's implementation to determine the capabilities that are supported by the emulated USB host controller.

Syntax

EVT_UDECX_WDF_DEVICE_QUERY_USB_CAPABILITY EvtUdecxWdfDeviceQueryUsbCapability;

NTSTATUS EvtUdecxWdfDeviceQueryUsbCapability(
  [in]            WDFDEVICE UdecxWdfDevice,
  [in]            PGUID CapabilityType,
  [in]            ULONG OutputBufferLength,
  [out, optional] PVOID OutputBuffer,
  [out]           PULONG ResultLength
)
{...}

Parameters

[in] UdecxWdfDevice

A handle to a framework device object that represents the controller. The client driver initialized this object in the previous call to UdecxWdfDeviceAddUsbDeviceEmulation.

[in] CapabilityType

Pointer to a GUID specifying the requested capability. The possible PGUID values are as follows:

  • GUID_USB_CAPABILITY_CHAINED_MDLS
  • 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
For information about the capabilities, see the Remarks section of USBD_QueryUsbCapability.

[in] OutputBufferLength

The length, in bytes, of the request's output buffer, if an output buffer is available.

[out, optional] OutputBuffer

A pointer to a location that receives the buffer's address. Certain capabilities may need to provide additional information to the USB device emulation class extension (UdeCx) in this buffer.

[out] ResultLength

A location that, on return, contains the size, in bytes, of the information that the callback function stored in OutputBuffer.

Return value

If the operation is successful, the callback function must return STATUS_SUCCESS, or another status value for which NT_SUCCESS(status) equals TRUE. If a capability is not supported, the client driver can return NT_SUCCESS(status) equals FALSE, such as STATUS_UNSUCCESSFUL.

Remarks

The class extension invokes this callback function implemented by the client driver when the class extension receives a request to determine the emulated controller's capabilities. The callback is invoked only after EvtDriverDeviceAdd has returned, typically in EvtDevicePrepareHardware. This callback cannot be invoked after EvtDeviceReleaseHardware has returned.

The class extension reports these capability GUIDs, as not supported:

  • GUID_USB_CAPABILITY_STATIC_STREAMS
  • GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL
The class extension reports the GUID_USB_CAPABILITY_SELECTIVE_SUSPEND capability GUID as supported without even invoking the callback function.

For other GUIDs, the class extension invokes the client driver's implementation, such as GUID_USB_CAPABILITY_CHAINED_MDLS. The client driver is expected to determine support for I/O requests that use a chained MDL. If this capability is supported then, the TransferBufferMdl member of the URB contains the request buffer. If chained MDL is not supported, the client driver does not receive TransferBufferMdl values that point to chained MDLs.

Requirements

Requirement Value
Minimum supported client Windows 10
Minimum supported server Windows Server 2016
Target Platform Windows
Minimum KMDF version 1.15
Header udecxwdfdevice.h (include Udecx.h)
IRQL PASSIVE_LEVEL

See also

Architecture: USB Device Emulation (UDE)

Write a UDE client driver