Fungsi UcxIoDeviceControl (ucxcontroller.h)

Memungkinkan ekstensi pengontrol host USB (UCX) untuk menangani permintaan kode kontrol I/O (IOCTL) dari mode pengguna.

Sintaks

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

Parameter

[in] Device

Handel ke objek perangkat kerangka kerja yang diambil driver klien dalam panggilan sebelumnya ke WdfDeviceCreate.

[in] Request

Handel ke objek permintaan kerangka kerja yang mewakili permintaan IOCTL mode pengguna.

[in] OutputBufferLength

Panjang, dalam byte, dari buffer output permintaan, jika buffer output tersedia.

[in] InputBufferLength

Panjang, dalam byte, dari buffer input permintaan, jika buffer input tersedia.

[in] IoControlCode

IOCTL yang ditentukan driver atau yang ditentukan sistem yang terkait dengan permintaan.

Mengembalikan nilai

Jika operasi berhasil, metode mengembalikan TRUE. Jika tidak, ia mengembalikan FALSE.

Keterangan

Driver klien dapat memanggil metode ini untuk memungkinkan UCX menangani IOCTL yang tercantum dalam tabel ini: IOCTL Mode Pengguna untuk USB. Jika kode IOCTL IOCTL_USB_DIAGNOSTIC_MODE_OFF atau IOCTL_USB_DIAGNOSTIC_MODE_ON, UCX berhasil menyelesaikan permintaan. Untuk IOCTLS yang digunakan untuk mengambil nama kunci driver pengontrol host USB, seperti IOCTL_USB_GET_ROOT_HUB_NAME atau IOCTL_GET_HCD_DRIVERKEY_NAME, UCX mengambil string Unicode. Jika mode pengguna IOCTL IOCTL_USB_USER_REQUEST, panjang buffer input dan output harus sama dan buffer output harus berisi struktur USBUSER_REQUEST_HEADER . Untuk IOCTL yang tersisa, UCX mengembalikan FALSE dan driver klien dapat memberikan logika penanganannya sendiri.

Contoh

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;
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10
Target Platform	Windows
Header	ucxcontroller.h (termasuk Ucxclass.h)
IRQL	<=DISPATCH_LEVEL

Lihat juga

IOCTL Mode Pengguna untuk USB