通过

EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY回调函数 （ucxcontroller.h）

  • 项目

用于确定控制器是否支持特定功能的客户端驱动程序实现。

语法

EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY EvtUcxControllerQueryUsbCapability;

NTSTATUS EvtUcxControllerQueryUsbCapability(
  [in]            UCXCONTROLLER UcxController,
  [in]            PGUID CapabilityType,
  [in]            ULONG OutputBufferLength,
  [out, optional] PVOID OutputBuffer,
  [out]           PULONG ResultLength
)
{...}

参数

[in] UcxController

客户端驱动程序在对 UcxControllerCreate 方法的上一次调用中收到的 UCX 控制器的句柄。

[in] CapabilityType

指向指定所请求功能的 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
  • GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL
    • 对于典型的主机控制器，查询必须失败（STATUS_NOT_SUPPORTED）。 如果控制器成功使用此功能，则会在取消已发送到 TT 中心的低速/全速异步（批量或控制）传输时请求清除 TT 缓冲区。
有关详细信息，请参阅 USBD_QueryUsbCapability 的“备注”部分。

[in] OutputBufferLength

如果输出缓冲区可用，则请求的输出缓冲区的长度（以字节为单位）。

[out, optional] OutputBuffer

指向接收缓冲区地址的位置的指针。 某些功能可能需要在此缓冲区中向 UCX 提供其他信息。

[out] ResultLength

返回时的位置包含回调函数存储在 outputBuffer 中的信息的大小（以字节为单位）。

返回值

如果作成功，回调函数必须返回STATUS_SUCCESS，或NT_SUCCESS（status） 等于 TRUE 的另一个状态值。 否则，它必须返回NT_SUCCESS（status）等于 FALSE 的状态值。

返回代码 描述
STATUS_SUCCESS
 支持请求的 USB 功能。
STATUS_NOT_IMPLEMENTED
 请求的 USB 功能未知，不受支持。
STATUS_NOT_SUPPORTED
 控制器不支持请求的 USB 功能。

对于GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL，控制器在取消发送到 TT 中心的低速/全速异步（批量或控制）传输时，控制器未请求清除 TT 缓冲区。

言论

UCX 客户端驱动程序通过调用 UcxControllerCreate 方法向 USB 主机控制器扩展（UCX）注册其 EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY 实现。

例子

NTSTATUS
Controller_EvtControllerQueryUsbCapability(
    UCXCONTROLLER   UcxController,
    PGUID           CapabilityType,
    ULONG           OutputBufferLength,
    PVOID           OutputBuffer,
    PULONG          ResultLength
)

{
    NTSTATUS status;

    UNREFERENCED_PARAMETER(UcxController);
    UNREFERENCED_PARAMETER(OutputBufferLength);
    UNREFERENCED_PARAMETER(OutputBuffer);

    *ResultLength = 0;

    if (RtlCompareMemory(CapabilityType,
                         &GUID_USB_CAPABILITY_CHAINED_MDLS,
                         sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_CHAINED_MDLS supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_CHAINED_MDLS not supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_STATIC_STREAMS,
                              sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_STATIC_STREAMS supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_STATIC_STREAMS supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_FUNCTION_SUSPEND,
                              sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_FUNCTION_SUSPEND supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_FUNCTION_SUSPEND not supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_SELECTIVE_SUSPEND,
                              sizeof(GUID)) == sizeof(GUID)) {

        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_SELECTIVE_SUSPEND supported");
        status = STATUS_SUCCESS;
    }
    else if (RtlCompareMemory(CapabilityType,
                              &GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL,
                              sizeof(GUID)) == sizeof(GUID)) {

        //
        // TODO: Is GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL supported?
        //
        DbgTrace(TL_INFO, Controller, "GUID_USB_CAPABILITY_CLEAR_TT_BUFFER_ON_ASYNC_TRANSFER_CANCEL not supported");
        status = STATUS_NOT_SUPPORTED;
    }
    else {
        DbgTrace(TL_INFO, Controller, "Unhandled USB capability");
        status = STATUS_NOT_IMPLEMENTED;
    }

    return status;
}

要求

要求 价值
目标平台 窗户
最低 KMDF 版本 1.0
最低 UMDF 版本 2.0
标头 ucxcontroller.h （include Ucxclass.h）
IRQL PASSIVE_LEVEL

另请参阅

UcxControllerCreate