Функция UcxIoDeviceControl (ucxcontroller.h)

Статья
02/07/2025

Позволяет расширению контроллера узла USB (UCX) обрабатывать запрос кода управления ввода-вывода (IOCTL) из пользовательского режима.

Синтаксис

BOOLEAN UcxIoDeviceControl(
  [in] WDFDEVICE  Device,
  [in] WDFREQUEST Request,
  [in] size_t     OutputBufferLength,
  [in] size_t     InputBufferLength,
  [in] ULONG      IoControlCode
);

Параметры

[in] Device

Дескриптор объекта устройства платформы, полученный драйвером клиента в предыдущем вызове WdfDeviceCreate.

[in] Request

Дескриптор объекта запроса платформы, представляющий запрос IOCTL в пользовательском режиме.

[in] OutputBufferLength

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

[in] InputBufferLength

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

[in] IoControlCode

Определяемый драйвером или системный IOCTL, связанный с запросом.

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

Если операция выполнена успешно, метод возвращает ЗНАЧЕНИЕ TRUE. В противном случае возвращает значение FALSE.

Замечания

Драйвер клиента может вызвать этот метод, чтобы разрешить UCX обрабатывать ioCTLs, перечисленные в этой таблице: User-Mode IOCTLs для USB-. Если код IOCTL IOCTL_USB_DIAGNOSTIC_MODE_OFF или IOCTL_USB_DIAGNOSTIC_MODE_ON, UCX успешно завершает запрос. Для IOCTLS, которые используются для получения имени ключа драйвера контроллеров USB-узла, например IOCTL_USB_GET_ROOT_HUB_NAME или IOCTL_GET_HCD_DRIVERKEY_NAME, UCX извлекает строку Юникода. Если IOCTL в пользовательском режиме IOCTL_USB_USER_REQUEST, длина входного и выходного буфера должна быть равной, а выходной буфер должен содержать структуру USBUSER_REQUEST_HEADER. Для остальных операций ввода-вывода UCX возвращает FALSE, а драйвер клиента может предоставлять собственную логику обработки.

Примеры

VOID
Controller_WdfEvtIoDeviceControl(
    WDFQUEUE    WdfQueue,
    WDFREQUEST  WdfRequest,
    size_t      OutputBufferLength,
    size_t      InputBufferLength,
    ULONG       IoControlCode
)
/*++

Routine Description:

    This routine is a callback function which is called by WDF when a driver
    receives an I/O control request from the queue this callback is registered
    with.

    The controller driver calls UcxIoDeviceControl() to allow UCX to try and
    handle the IOCTL.  If UCX cannot handle the IOCTL, the controller driver
    must handle it, perhaps by failing it.

    The default queue only expects to receive IOCTLs from user mode (via the
    interface defined by GUID_DEVINTERFACE_USB_HOST_CONTROLLER).

Arguments:

    WdfQueue - A handle to the framework I/O queue object.

    WdfRequest - A handle to the framework request object that contains the IOCTL.

    OutputBufferLength - Length of the IOCTL output buffer, if an output buffer
        is available.

    InputBufferLength - Length of the IOCTL input buffer, if an input buffer
        is available.

    IoControlCode - I/O control code associated with the request.

Return Value:

    None.

--*/
{
    KPROCESSOR_MODE requestorMode;

    //
    // Allow UCX to try and handle the request
    //
    if (UcxIoDeviceControl(WdfIoQueueGetDevice(WdfQueue),
                           WdfRequest,
                           OutputBufferLength,
                           InputBufferLength,
                           IoControlCode)) {
        DbgTrace(TL_VERBOSE, Controller, "IoControlCode 0x%x was handled by UCX", IoControlCode);
        goto WdfEvtIoDeviceControlEnd;
    }

    //
    // Check that the request is coming from user mode
    //
    requestorMode = WdfRequestGetRequestorMode(WdfRequest);

    if (requestorMode != UserMode) {
        DbgTrace(TL_WARNING, Controller, "Invalid RequestorMode %d", requestorMode);
    }

    //
    // UCX could not handle the request, so handle it here
    //
    switch (IoControlCode) {

    default:
        DbgTrace(TL_WARNING, Controller, "Unsupported IoControlCode 0x%x", IoControlCode);
        WdfRequestComplete(WdfRequest, STATUS_INVALID_DEVICE_REQUEST);
    }

WdfEvtIoDeviceControlEnd:

    return;
}

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 10
целевая платформа	Виндоус
заголовка	ucxcontroller.h (include Ucxclass.h)
IRQL	<=DISPATCH_LEVEL

См. также

User-Mode ioCTLs для USB-

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