IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX IOCTL (usbioctl.h)

Artigo
02/07/2025

A solicitação IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX recupera informações sobre uma porta USB e o dispositivo anexado à porta, se houver uma.

Os drivers cliente devem enviar esse IOCTL em um IRQL de PASSIVE_LEVEL.

IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX é uma solicitação de controle de E/S no modo de usuário. Essa solicitação tem como destino o dispositivo de hub USB (GUID_DEVINTERFACE_USB_HUB).

Código principal

IRP_MJ_DEVICE_CONTROL

Buffer de entrada/saída

Os buffers de entrada e de saída apontam para uma estrutura de USB_NODE_CONNECTION_INFORMATION_EX alocada pelo chamador. Na entrada, o ConnectionIndex membro dessa estrutura deve conter um número maior ou igual a 1 que indique o número da porta cujas informações de conexão devem ser relatadas. O driver do hub retorna informações de conexão nos membros restantes do USB_NODE_CONNECTION_INFORMATION_EX. O IRP, o membro AssociatedIrp.SystemBuffer aponta para a estrutura de USB_NODE_CONNECTION_INFORMATION_EX.

Na saída, a estrutura USB_NODE_CONNECTION_INFORMATION_EX recebe informações sobre a conexão indicada do driver do hub USB.

Comprimento do buffer de entrada/saída

O tamanho de uma estrutura USB_NODE_CONNECTION_INFORMATION_EX.

Bloco de status

A pilha USB define Irp->IoStatus.Status para STATUS_SUCCESS se a solicitação for bem-sucedida. Caso contrário, a pilha USB define Status à condição de erro apropriada, como STATUS_INVALID_PARAMETER ou STATUS_INSUFFICIENT_RESOURCES.

Observações

Aqui está um exemplo que mostra como obter a velocidade da porta do hub enviando essa solicitação.

A função especifica o link simbólico para o dispositivo de hub e o índice de porta para consulta. No retorno, pPortSpeed indica:

Velocidade da porta
SPEED_PATHERROR: se não for possível abrir o caminho.
SPEED_IOCTLERROR: Falha no IOCTL do Hub.

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

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP, Windows Server 2003 e posterior.
cabeçalho	usbioctl.h (include Usbioctl.h)

Consulte também

USB_NODE_CONNECTION_INFORMATION

USB_NODE_CONNECTION_INFORMATION_EX

Compartilhar via