IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX IOCTL (usbioctl.h)

Artikel
02/22/2024

The IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX request retrieves information about a USB port and the device that is attached to the port, if there is one.

Client drivers must send this IOCTL at an IRQL of PASSIVE_LEVEL.

IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX is a user-mode I/O control request. This request targets the USB hub device (GUID_DEVINTERFACE_USB_HUB).

Major code

IRP_MJ_DEVICE_CONTROL

Input / Output buffer

Both input and output buffers point to a caller-allocated USB_NODE_CONNECTION_INFORMATION_EX structure. On input, the ConnectionIndex member of this structure must contain a number greater than or equal to 1 that indicates the number of the port whose connection information is to be reported. The hub driver returns connection information in the remaining members of USB_NODE_CONNECTION_INFORMATION_EX. The IRP, the AssociatedIrp.SystemBuffer member points to the USB_NODE_CONNECTION_INFORMATION_EX structure.

On output, the USB_NODE_CONNECTION_INFORMATION_EX structure receives information about the indicated connection from the USB hub driver.

Input / Output buffer length

The size of a USB_NODE_CONNECTION_INFORMATION_EX structure.

Status block

The USB stack sets Irp->IoStatus.Status to STATUS_SUCCESS if the request is successful. Otherwise, the USB stack sets Status to the appropriate error condition, such as STATUS_INVALID_PARAMETER or STATUS_INSUFFICIENT_RESOURCES.

Remarks

Here is an example that shows how to get the speed of the hub port by sending this request.

The function specifies the symbolic link to hub device and port index to query. On return, pPortSpeed indicates:

Port speed
SPEED_PATHERROR: if unable to open path.
SPEED_IOCTLERROR: Hub IOCTL failed.

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

Requirements

Requirement	Value
Minimum supported client	Windows XP, Windows Server 2003, and later.
Header	usbioctl.h (include Usbioctl.h)

Delen via