estrutura _URB_CONTROL_TRANSFER_EX (usb.h)

Artigo
08/07/2023

A estrutura _URB_CONTROL_TRANSFER_EX é usada por drivers de cliente USB para transferir dados de ou para um pipe de controle, com um tempo limite que limita o tempo de transferência aceitável.

Sintaxe

struct _URB_CONTROL_TRANSFER_EX {
  struct _URB_HEADER   Hdr;
  USBD_PIPE_HANDLE     PipeHandle;
  ULONG                TransferFlags;
  ULONG                TransferBufferLength;
  PVOID                TransferBuffer;
  PMDL                 TransferBufferMDL;
  ULONG                Timeout;
  ULONG                Pad;
  struct _URB_HCD_AREA hca;
  UCHAR                SetupPacket[8];
};

Membros

Hdr

Ponteiro para uma estrutura _URB_HEADER que especifica as informações do cabeçalho URB. Hdr.Function deve ser URB_FUNCTION_CONTROL_TRANSFER_EX e Hdr.Length deve ser sizeof(_URB_CONTROL_TRANSFER_EX).

PipeHandle

Identificador do pipe.

Se target for o ponto de extremidade de controle padrão, PipeHandle deverá ser NULL. Nesse caso, o TransferFlags deve conter o sinalizador USBD_DEFAULT_PIPE_TRANSFER.

Se target for um ponto de extremidade de controle não padrão, PipeHandle especificará uma alça opaca para o pipe de controle. O driver do controlador de host retorna esse identificador quando o driver do cliente seleciona a configuração do dispositivo com um URB do tipo URB_FUNCTION_SELECT_CONFIGURATION ou quando o driver cliente altera as configurações de uma interface com um URB do tipo URB_FUNCTION_SELECT_INTERFACE.

TransferFlags

Especifica zero, um ou uma combinação dos seguintes sinalizadores:

Valor	Significado
USBD_TRANSFER_DIRECTION_IN	Está definido para solicitar dados de um dispositivo. Para transferir dados para um dispositivo, esse sinalizador deve estar claro.
USBD_TRANSFER_DIRECTION_OUT	Está definido para transferir dados para um dispositivo. Definir esse sinalizador é equivalente a limpar o sinalizador USBD_TRANSFER_DIRECTION_IN.
USBD_SHORT_TRANSFER_OK	É definido para direcionar o controlador de host a não retornar um erro quando ele recebe um pacote do dispositivo que é menor que o tamanho máximo do pacote para o ponto de extremidade. O tamanho máximo do pacote para o ponto de extremidade é relatado no membro bMaxPacketSize0 da estrutura USB_DEVICE_DESCRIPTOR (descritor de dispositivo) para o ponto de extremidade de controle padrão. Para um ponto de extremidade de controle não padrão, o tamanho máximo do pacote é definido no membro wMaxPacketSize da estrutura USB_ENDPOINT_DESCRIPTOR (descritor de ponto de extremidade). Quando o controlador de host recebe um pacote cujo comprimento é menor que o valor wMaxPacketSize em um ponto de extremidade de controle, o comportamento é o seguinte, dependendo do tipo de controlador de host: Em controladores de host EHCI, o controlador host prossegue imediatamente para a fase status da transferência de controle. A transferência é concluída com êxito, independentemente de USBD_SHORT_TRANSFER_OK ser definida. Em controladores de host UHCI e OHCI, se USBD_SHORT_TRANSFER_OK estiver definido, o controlador host prosseguirá para a fase de status. Se USBD_SHORT_TRANSFER_OK não estiver definido, o controlador host abandonará os dados e status fases da transferência de controle e a transferência será concluída com um erro.
USBD_DEFAULT_PIPE_TRANSFER	É definido para direcionar o controlador de host para fazer uma transferência de controle no pipe de controle padrão. Isso permite que o chamador envie comandos para o pipe de controle padrão sem especificar explicitamente o identificador de pipe.

TransferBufferLength

Especifica o comprimento, em bytes, do buffer especificado em TransferBuffer ou descrito em TransferBufferMDL. O driver do controlador de host retorna o número de bytes enviados ou lidos do pipe neste membro.

TransferBuffer

Ponteiro para um buffer residente para a transferência ou será NULL se um MDL for fornecido em TransferBufferMDL. O conteúdo desse buffer depende do valor de TransferFlags. Se USBD_TRANSFER_DIRECTION_IN for especificado, esse buffer conterá dados lidos do dispositivo no retorno do driver do controlador host. Caso contrário, esse buffer contém dados fornecidos pelo driver para transferência para o dispositivo.

TransferBufferMDL

Ponteiro para um MDL que descreve um buffer residente ou é NULL se um buffer for fornecido no TransferBuffer. O conteúdo do buffer depende do valor de TransferFlags. Se USBD_TRANSFER_DIRECTION_IN for especificado, o buffer descrito conterá dados lidos do dispositivo no retorno do driver do controlador de host. Caso contrário, o buffer contém dados fornecidos pelo driver para transferência para o dispositivo. Esse MDL deve ser alocado do pool nãopagado.

Timeout

Indica a hora, em milissegundos, antes do tempo limite da URB. Um valor 0 indica que não há tempo limite para essa URB.

Pad

Reservado. Não use.

hca

Reservado. Não use.

SetupPacket[8]

Especifica um pacote de configuração de solicitação definido por USB. O formato de um pacote de configuração de solicitação USB é encontrado na especificação do núcleo USB.