IOCTL_USB_GET_NODE_CONNECTION_INFORMATION_EX IOCTL (usbioctl.h)

  • Artigo

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 de 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 saída apontam para uma estrutura de USB_NODE_CONNECTION_INFORMATION_EX alocada pelo chamador. Na entrada, o membro ConnectionIndex 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, membro AssociatedIrp.SystemBuffer , aponta para a estrutura 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> como STATUS_SUCCESS se a solicitação for bem-sucedida. Caso contrário, a pilha USB define Status como a condição de erro apropriada, como STATUS_INVALID_PARAMETER ou STATUS_INSUFFICIENT_RESOURCES.

Comentários

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 a serem consultados. No retorno, pPortSpeed indica:

  • Velocidade da porta
  • SPEED_PATHERROR: se não for possível abrir o caminho.
  • SPEED_IOCTLERROR: o IOCTL do Hub falhou.
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
Cliente mínimo com suporte Windows XP, Windows Server 2003 e posterior.
Cabeçalho usbioctl.h (inclua Usbioctl.h)

Confira também

USB_NODE_CONNECTION_INFORMATION

USB_NODE_CONNECTION_INFORMATION_EX