IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX IOCTL (usbioctl.h)

Article
02/07/2025

La demande IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX récupère des informations sur un port USB et l’appareil attaché au port, s’il en existe un.

Les pilotes clients doivent envoyer cette IOCTL à un irQL de PASSIVE_LEVEL.

IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX est une demande de contrôle d’E/S en mode utilisateur. Cette requête cible l’appareil du hub USB (GUID_DEVINTERFACE_USB_HUB).

Code principal

IRP_MJ_DEVICE_CONTROL

Mémoire tampon d’entrée/sortie

Les mémoires tampons d’entrée et de sortie pointent vers une structure USB_NODE_CONNECTION_INFORMATION_EX allouée par l’appelant. Lors de l’entrée, le ConnectionIndex membre de cette structure doit contenir un nombre supérieur ou égal à 1 qui indique le nombre du port dont les informations de connexion doivent être signalées. Le pilote hub retourne les informations de connexion dans les membres restants de USB_NODE_CONNECTION_INFORMATION_EX. L’IRP, le membre AssociatedIrp.SystemBuffer pointe vers la structure USB_NODE_CONNECTION_INFORMATION_EX.

En sortie, la structure USB_NODE_CONNECTION_INFORMATION_EX reçoit des informations sur la connexion indiquée à partir du pilote du hub USB.

Longueur de la mémoire tampon d’entrée/sortie

Taille d’une structure USB_NODE_CONNECTION_INFORMATION_EX.

Bloc d’état

La pile USB définit Irp->IoStatus.Status sur STATUS_SUCCESS si la requête réussit. Sinon, la pile USB définit 'état à la condition d’erreur appropriée, telle que STATUS_INVALID_PARAMETER ou STATUS_INSUFFICIENT_RESOURCES.

Remarques

Voici un exemple qui montre comment obtenir la vitesse du port hub en envoyant cette requête.

La fonction spécifie le lien symbolique vers l’appareil hub et l’index de port à interroger. Lors du retour, pPortSpeed indique :

Vitesse du port
SPEED_PATHERROR : s’il n’est pas en mesure d’ouvrir le chemin d’accès.
SPEED_IOCTLERROR : Échec de la durée de vie du hub IOCTL.

void GetPortSpeed(const WCHAR *Path, ULONG PortIndex, UCHAR *pPortSpeed)

{
    if (Path == NULL) { return; }

    HANDLE handle = CreateFile(
                            Path,
                            GENERIC_WRITE | GENERIC_READ,
                            FILE_SHARE_WRITE | FILE_SHARE_READ,
                            NULL,
                            OPEN_EXISTING,
                            NULL,
                            NULL
                        );

    if (handle == INVALID_HANDLE_VALUE)
    {
      *pPortSpeed = SPEED_PATHERROR;
      return;
    }

    PUSB_NODE_CONNECTION_INFORMATION_EX ConnectionInfo =
                    (PUSB_NODE_CONNECTION_INFORMATION_EX)
                    malloc(sizeof(USB_NODE_CONNECTION_INFORMATION_EX));

    ConnectionInfo->ConnectionIndex = PortIndex;

    ULONG bytes = 0;
    BOOL success = DeviceIoControl(handle,
                              IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX,
                              ConnectionInfo,
                              sizeof(USB_NODE_CONNECTION_INFORMATION_EX),
                              ConnectionInfo,
                              sizeof(USB_NODE_CONNECTION_INFORMATION_EX),
                              &bytes,
                              NULL);

    CloseHandle(handle);

    if (success == FALSE)
    {
      *pPortSpeed = SPEED_IOCTLERROR;
    }
    else
    {
      *pPortSpeed = (UCHAR)ConnectionInfo->Speed;
    }

    free(ConnectionInfo);
}

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP, Windows Server 2003 et versions ultérieures.
d’en-tête	usbioctl.h (include Usbioctl.h)

Voir aussi

USB_NODE_CONNECTION_INFORMATION

USB_NODE_CONNECTION_INFORMATION_EX

Partager via