UcxIoDeviceControl-Funktion (ucxcontroller.h)

Ermöglicht die USB-Hostcontrollererweiterung (UCX), eine I/O-Steuerungscodeanforderung (IOCTL) aus dem Benutzermodus zu verarbeiten.

Syntax

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

Parameter

[in] Device

Ein Handle für das Framework-Geräteobjekt, das der Clienttreiber im vorherigen Aufruf von WdfDeviceCreate abgerufen hat.

[in] Request

Ein Handle für ein Frameworkanforderungsobjekt, das die IOCTL-Anforderung im Benutzermodus darstellt.

[in] OutputBufferLength

Die Länge des Ausgabepuffers der Anforderung in Bytes, wenn ein Ausgabepuffer verfügbar ist.

[in] InputBufferLength

Die Länge des Eingabepuffers der Anforderung in Bytes, wenn ein Eingabepuffer verfügbar ist.

[in] IoControlCode

Die treiberdefinierte oder systemdefinierte IOCTL, die der Anforderung zugeordnet ist.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt die Methode TRUE zurück. Andernfalls wird FALSE zurückgegeben.

Hinweise

Der Clienttreiber kann diese Methode aufrufen, damit UCX IOCTLs verarbeiten kann, die in dieser Tabelle aufgeführt sind: Benutzermodus-IOCTLs für USB. Wenn der IOCTL-Code IOCTL_USB_DIAGNOSTIC_MODE_OFF oder IOCTL_USB_DIAGNOSTIC_MODE_ON ist, schließt UCX die Anforderung erfolgreich ab. Für IOCTLS, die zum Abrufen des Treibernamens des USB-Hostcontrollers verwendet werden, z. B. IOCTL_USB_GET_ROOT_HUB_NAME oder IOCTL_GET_HCD_DRIVERKEY_NAME, ruft UCX die Unicode-Zeichenfolge ab. Wenn die IOCTL im Benutzermodus IOCTL_USB_USER_REQUEST ist, müssen die Längen des Eingabe- und Ausgabepuffers gleich sein, und der Ausgabepuffer muss die USBUSER_REQUEST_HEADER-Struktur enthalten. Für die verbleibenden IOCTLs gibt UCX FALSE zurück, und der Clienttreiber kann eine eigene Verarbeitungslogik bereitstellen.

Beispiele

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

Anforderungen

Weitere Informationen

Benutzermodus-IOCTLs für USB