UcxIoDeviceControl 函数 (ucxcontroller.h)

允许 USB 主机控制器扩展 (UCX) 处理 I/O 控制代码 (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 处理下表中列出的 IOCTL： 适用于 USB 的用户模式 IOCTL。 如果 IOCTL 代码IOCTL_USB_DIAGNOSTIC_MODE_OFF或IOCTL_USB_DIAGNOSTIC_MODE_ON，UCX 将成功完成请求。 对于用于检索 USB 主机控制器驱动程序密钥名称（如 IOCTL_USB_GET_ROOT_HUB_NAME 或 IOCTL_GET_HCD_DRIVERKEY_NAME）的 IOCTLS，UCX 检索 Unicode 字符串。 如果用户模式 IOCTL IOCTL_USB_USER_REQUEST，输入和输出缓冲区长度必须相等，并且输出缓冲区必须包含 USBUSER_REQUEST_HEADER 结构。 对于剩余的 IOCTL，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
目标平台	Windows
标头	ucxcontroller.h (包括 Ucxclass.h)
IRQL	<=DISPATCH_LEVEL

另请参阅

适用于 USB 的用户模式 IOCTL