UcxIoDeviceControl 函式 (ucxcontroller.h)

允許 USB 主機控制器擴充功能 (UCX) 處理 IOCTL) 要求的使用者模式 (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 主機控制器驅動程式密鑰名稱的 IOCTLS，例如IOCTL_USB_GET_ROOT_HUB_NAME或IOCTL_GET_HCD_DRIVERKEY_NAME，UCX 會擷取 Unicode 字元串。 如果使用者模式 IOCTL IOCTL_USB_USER_REQUEST，輸入和輸出緩衝區長度必須相等，而且輸出緩衝區必須包含 USBUSER_REQUEST_HEADER 結構。 對於其餘的 IOCTLs，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;
}

規格需求

另請參閱

USB 的使用者模式 IOCTL