UcxIoDeviceControl 함수(ucxcontroller.h)

UCX(USB 호스트 컨트롤러 확장)가 사용자 모드에서 IOCTL(I/O 제어 코드) 요청을 처리할 수 있도록 허용합니다.

구문

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는 유니코드 문자열을 검색합니다. 사용자 모드 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