estrutura _URB_BULK_OR_INTERRUPT_TRANSFER (usb.h)

Artigo
08/07/2023

A estrutura _URB_BULK_OR_INTERRUPT_TRANSFER é usada por drivers de cliente USB para enviar ou receber dados em um pipe em massa ou em um pipe de interrupção.

Sintaxe

struct _URB_BULK_OR_INTERRUPT_TRANSFER {
  struct _URB_HEADER   Hdr;
  USBD_PIPE_HANDLE     PipeHandle;
  ULONG                TransferFlags;
  ULONG                TransferBufferLength;
  PVOID                TransferBuffer;
  PMDL                 TransferBufferMDL;
  struct _URB          *UrbLink;
  struct _URB_HCD_AREA hca;
};

Membros

Hdr

Ponteiro para uma estrutura de _URB_HEADER que especifica as informações do cabeçalho URB. Hdr.Function deve ser URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER e Hdr.Length deve ser definido como sizeof(_URB_BULK_OR_INTERRUPT_TRANSFER).

PipeHandle

Especifica um identificador opaco para o pipe de interrupção ou em massa. 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	É definido para solicitar dados de um dispositivo. Para transferir dados para um dispositivo, esse sinalizador deve estar claro.
USBD_TRANSFER_DIRECTION_OUT	É 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 para 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 wMaxPacketSize da estrutura USB_ENDPOINT_DESCRIPTOR (descritor de ponto de extremidade). Quando o controlador host recebe um pacote menor que wMaxPacketSize em um ponto de extremidade em massa ou de interrupção, o controlador host para imediatamente a solicitação de dados do ponto de extremidade e conclui a transferência. Se o sinalizador USBD_SHORT_TRANSFER_OK não estiver definido, o controlador host concluirá a transferência com um erro. Esse sinalizador não deve ser definido, a menos que USBD_TRANSFER_DIRECTION_IN também esteja definido. Nota Em controladores de host EHCI, USBD_SHORT_TRANSFER_OK é ignorado para pontos de extremidade em massa e interrupção. A transferência de pacotes curtos em controladores EHCI não resulta em uma condição de erro. Em controladores de host UHCI e OHCI, se USBD_SHORT_TRANSFER_OK não estiver definido para uma transferência em massa ou interrupção, uma transferência de pacote curta interromperá o ponto de extremidade e um código de erro será retornado para a transferência. O driver do cliente deve retomar o ponto de extremidade enviando uma solicitação URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL antes de enviar uma solicitação de transferência para o ponto de extremidade.

Valor

Significado

USBD_TRANSFER_DIRECTION_IN

É definido para solicitar dados de um dispositivo. Para transferir dados para um dispositivo, esse sinalizador deve estar claro.

USBD_TRANSFER_DIRECTION_OUT

É 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 para 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 wMaxPacketSize da estrutura USB_ENDPOINT_DESCRIPTOR (descritor de ponto de extremidade). Quando o controlador host recebe um pacote menor que wMaxPacketSize em um ponto de extremidade em massa ou de interrupção, o controlador host para imediatamente a solicitação de dados do ponto de extremidade e conclui a transferência. Se o sinalizador USBD_SHORT_TRANSFER_OK não estiver definido, o controlador host concluirá a transferência com um erro.

Esse sinalizador não deve ser definido, a menos que USBD_TRANSFER_DIRECTION_IN também esteja definido. Nota Em controladores de host EHCI, USBD_SHORT_TRANSFER_OK é ignorado para pontos de extremidade em massa e interrupção. A transferência de pacotes curtos em controladores EHCI não resulta em uma condição de erro.

Em controladores de host UHCI e OHCI, se USBD_SHORT_TRANSFER_OK não estiver definido para uma transferência em massa ou interrupção, uma transferência de pacote curta interromperá o ponto de extremidade e um código de erro será retornado para a transferência. O driver do cliente deve retomar o ponto de extremidade enviando uma solicitação URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL antes de enviar uma solicitação de transferência para o ponto de extremidade.

TransferBufferLength

Especifica o comprimento, em bytes, do buffer especificado em TransferBuffer ou descrito em TransferBufferMDL. O driver do controlador 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 é 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 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.

UrbLink

Reservado. Não use.

hca

Reservado. Não use.

Comentários

Os drivers podem usar a rotina de serviço UsbBuildInterruptOrBulkTransferRequest para formatar esse URB. Os buffers especificados em TransferBuffer ou descritos em TransferBufferMDL devem não ser gináveis.

Em um URB, os parâmetros TransferBuffer e TransferBufferMDL podem ser valores não NULL, ao mesmo tempo. Nesse caso, o buffer de transferência e o MDL apontado para TransferBuffer e TransferBufferMDL devem apontar para o mesmo buffer.

O driver do barramento USB processa esse URB em DISPATCH_LEVEL.

Os membros reservados dessa estrutura devem ser tratados como opacos e são reservados para uso do sistema.