Funzione UcxIoDeviceControl (ucxcontroller.h)

Articolo
02/26/2024

Consente all'estensione del controller host USB (UCX) di gestire una richiesta di codice di controllo I/O (IOCTL) dalla modalità utente.

Sintassi

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

Parametri

[in] Device

Handle per l'oggetto dispositivo framework recuperato dal driver client nella chiamata precedente a WdfDeviceCreate.

[in] Request

Handle a un oggetto richiesta framework che rappresenta la richiesta IOCTL in modalità utente.

[in] OutputBufferLength

Lunghezza, in byte, del buffer di output della richiesta, se è disponibile un buffer di output.

[in] InputBufferLength

Lunghezza, in byte, del buffer di input della richiesta, se è disponibile un buffer di input.

[in] IoControlCode

Il driver definito o definito dal sistema IOCTL associato alla richiesta.

Valore restituito

Se l'operazione ha esito positivo, il metodo restituisce TRUE. In caso contrario, restituisce FALSE.

Commenti

Il driver client può chiamare questo metodo per consentire a UCX di gestire IOCTLs elencati in questa tabella: IOCTLs in modalità utente per USB. Se il codice IOCTL è IOCTL_USB_DIAGNOSTIC_MODE_OFF o IOCTL_USB_DIAGNOSTIC_MODE_ON, UCX completa correttamente la richiesta. Per IOCTLS che vengono usati per recuperare il nome della chiave chiave del driver dei controller host USB, ad esempio IOCTL_USB_GET_ROOT_HUB_NAME o IOCTL_GET_HCD_DRIVERKEY_NAME, UCX recupera la stringa Unicode. Se la modalità utente IOCTL è IOCTL_USB_USER_REQUEST, le lunghezze del buffer di input e di output devono essere uguali e il buffer di output deve contenere la struttura USBUSER_REQUEST_HEADER . Per gli IOCTLs rimanenti, UCX restituisce FALSE e il driver client può fornire la propria logica di gestione.

Esempio

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows 10
Piattaforma di destinazione	Windows
Intestazione	ucxcontroller.h (includere Ucxclass.h)
IRQL	<=DISPATCH_LEVEL

Vedi anche

IOCTLs in modalità utente per USB

Condividi tramite