функция обратного вызова EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY (ucxcontroller.h)

Статья
02/07/2025

Реализация драйвера клиента, чтобы определить, поддерживает ли контроллер определенную возможность.

Синтаксис

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

Дескриптор контроллера UCX, полученного драйвером клиента в предыдущем вызове метода UcxControllerCreate.

[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 clear TT при отмене асинхронной асинхронной передачи с низкой скоростью или полной скоростью (массовой или контрольной) передачи, отправленной в концентратор TT.

Дополнительные сведения см. в разделе "Примечания" USBD_QueryUsbCapability.

[in] OutputBufferLength

Длина в байтах выходного буфера запроса, если выходной буфер доступен.

[out, optional] OutputBuffer

Указатель на расположение, которое получает адрес буфера. Некоторые возможности могут потребоваться предоставить дополнительные сведения в UCX в этом буфере.

[out] ResultLength

Расположение, которое, возвращаемое, содержит размер (в байтах) сведений о функции обратного вызова, хранящейся в OutputBuffer.

Возвращаемое значение

Если операция выполнена успешно, функция обратного вызова должна возвращать STATUS_SUCCESS или другое значение состояния, для которого NT_SUCCESS(состояние) равно 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 регистрирует свою реализацию EVT_UCX_CONTROLLER_QUERY_USB_CAPABILITY с расширением контроллера USB-узла (UCX), вызвав метод UcxControllerCreate.

Примеры

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

Поделиться через