IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX IOCTL (usbioctl.h)
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
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) |