UcxIoDeviceControl, fonction (ucxcontroller.h)

Article
02/26/2024

Permet à l’extension du contrôleur hôte USB (UCX) de gérer une demande de code de contrôle d’E/S (IOCTL) à partir du mode utilisateur.

Syntaxe

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

Paramètres

[in] Device

Handle de l’objet de périphérique d’infrastructure que le pilote client a récupéré lors de l’appel précédent à WdfDeviceCreate.

[in] Request

Handle vers un objet de demande d’infrastructure qui représente la demande IOCTL en mode utilisateur.

[in] OutputBufferLength

Longueur, en octets, de la mémoire tampon de sortie de la requête, si une mémoire tampon de sortie est disponible.

[in] InputBufferLength

Longueur, en octets, de la mémoire tampon d’entrée de la requête, si une mémoire tampon d’entrée est disponible.

[in] IoControlCode

IOCTL défini par le pilote ou défini par le système qui est associé à la requête.

Valeur retournée

Si l’opération réussit, la méthode retourne TRUE. Sinon, elle retourne FALSE.

Remarques

Le pilote client peut appeler cette méthode pour permettre à UCX de gérer les IOCTL répertoriés dans le tableau suivant : IOCTL en mode utilisateur pour USB. Si le code IOCTL est IOCTL_USB_DIAGNOSTIC_MODE_OFF ou IOCTL_USB_DIAGNOSTIC_MODE_ON, UCX termine la demande avec succès. Pour les IOCTLS utilisés pour récupérer le nom de clé du pilote des contrôleurs hôtes USB, par exemple IOCTL_USB_GET_ROOT_HUB_NAME ou IOCTL_GET_HCD_DRIVERKEY_NAME, UCX récupère la chaîne Unicode. Si le mode utilisateur IOCTL est IOCTL_USB_USER_REQUEST, les longueurs de mémoire tampon d’entrée et de sortie doivent être égales et la mémoire tampon de sortie doit contenir la structure USBUSER_REQUEST_HEADER . Pour les autres IOCTL, UCX retourne FALSE et le pilote client peut fournir sa propre logique de gestion.

Exemples

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10
Plateforme cible	Windows
En-tête	ucxcontroller.h (inclure Ucxclass.h)
IRQL	<=DISPATCH_LEVEL

Voir aussi

IOCTL en mode utilisateur pour USB

Share via