estrutura _URB_HEADER (usb.h)

Artigo
08/07/2023

A estrutura _URB_HEADER é usada por drivers de cliente USB para fornecer informações básicas sobre a solicitação que está sendo enviada ao driver do controlador de host.

Sintaxe

struct _URB_HEADER {
  USHORT      Length;
  USHORT      Function;
  USBD_STATUS Status;
  PVOID       UsbdDeviceHandle;
  ULONG       UsbdFlags;
};

Membros

Length

Especifica o comprimento, em bytes, do URB. Para solicitações URB que usam estruturas de dados diferentes de _URB_HEADER, esse membro deve ser definido com o comprimento de toda a estrutura de solicitação URB, não o tamanho da _URB_HEADER.

Function

Especifica um código numérico que indica a operação solicitada para este URB. Um dos seguintes valores deve ser definido:

URB_FUNCTION_SELECT_CONFIGURATION

Indica ao driver do controlador de host que uma configuração deve ser selecionada. Se definido, o URB será usado com URB_SELECT_CONFIGURATION como a estrutura de dados.

URB_FUNCTION_SELECT_INTERFACE

Indica ao driver do controlador de host que uma configuração de interface alternativa está sendo selecionada para uma interface. Se definido, o URB será usado com _URB_SELECT_INTERFACE como a estrutura de dados.

URB_FUNCTION_ABORT_PIPE

Indica que todas as solicitações pendentes para um pipe devem ser canceladas. Se definido, o URB será usado com _URB_PIPE_REQUEST como a estrutura de dados. Essa solicitação de uso geral permite que um cliente cancele todas as transferências pendentes para o pipe especificado. O estado do pipe e o estado do ponto de extremidade não são afetados. A solicitação de anulação pode ser concluída antes que todas as solicitações pendentes sejam concluídas. Não suponha que a conclusão da solicitação de anulação implica que todas as outras solicitações pendentes foram concluídas.

URB_FUNCTION_TAKE_FRAME_LENGTH_CONTROL

Essa função URB foi preterida no Windows 2000 e em sistemas operacionais posteriores e não tem suporte da Microsoft. Não use. Se você especificar essa função com uma solicitação URB, a solicitação falhará e o sistema relatará um erro.

URB_FUNCTION_RELEASE_FRAME_LENGTH_CONTROL

URB_FUNCTION_GET_FRAME_LENGTH

Essa função URB foi preterida no Windows 2000 e em sistemas operacionais posteriores e não tem suporte da Microsoft. Não use. Se você usar essa função com uma solicitação URB, a solicitação falhará e o sistema relatará um erro.

URB_FUNCTION_SET_FRAME_LENGTH

Essa função URB foi preterida no Windows 2000 e em sistemas operacionais posteriores e não tem suporte da Microsoft. Não use. Se você usá-lo com uma solicitação URB, a solicitação falhará e o sistema relatará um erro.

URB_FUNCTION_GET_CURRENT_FRAME_NUMBER

Solicita o número do quadro atual do driver do controlador de host. Se definido, o URB será usado com _URB_GET_CURRENT_FRAME_NUMBER como a estrutura de dados.

URB_FUNCTION_CONTROL_TRANSFER

Transfere dados de ou para um pipe de controle. Se definido, o URB será usado com _URB_CONTROL_TRANSFER como a estrutura de dados.

URB_FUNCTION_CONTROL_TRANSFER_EX

Transfere dados de ou para um pipe de controle sem um limite de tempo especificado por um valor de tempo limite. Se definido, o URB será usado com URB_CONTROL_TRANSFER_EX como a estrutura de dados.

Disponível no Windows Vista e em sistemas operacionais posteriores.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER

Transfere dados de um pipe em massa ou pipe de interrupção ou para um pipe em massa. Se definido, o URB será usado com _URB_BULK_OR_INTERRUPT_TRANSFER como a estrutura de dados.

URB_FUNCTION_BULK_OR_INTERRUPT_TRANSFER_USING_CHAINED_MDL

Transfere dados de e para um pipe em massa ou pipe de interrupção usando MDLs encadeados. Se definido, o URB será usado com _URB_BULK_OR_INTERRUPT_TRANSFER como a estrutura de dados. O driver cliente deve definir o membro TransferBufferMDL como a primeira estrutura MDL na cadeia que contém o buffer de transferência. A pilha de driver USB ignora o membro TransferBuffer ao processar esse URB.

Disponível em Windows 8. Para obter informações sobre como usar MDLs encadeados, consulte Como enviar MDLs encadeados">Como enviar MDLs encadeados.

URB_FUNCTION_ISOCH_TRANSFER

Transfere dados de ou para um pipe isócrono. Se definido, o URB será usado com _URB_ISOCH_TRANSFER como a estrutura de dados.

URB_FUNCTION_ISOCH_TRANSFER_USING_CHAINED_MDL

Transfere dados de ou para um pipe isócrono usando MDLs encadeados. Se definido, o URB será usado com _URB_ISOCH_TRANSFER como a estrutura de dados. O driver cliente deve definir o membro TransferBufferMDL como o primeiro MDL na cadeia que contém o buffer de transferência. A pilha de driver USB ignora o membro TransferBuffer ao processar esse URB.

Disponível em Windows 8. Para obter informações sobre como usar MDLs encadeados, consulte Como enviar MDLs encadeados">Como enviar MDLs encadeados.

URB_FUNCTION_RESET_PIPE

Consulte URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL

Redefine o pipe indicado. Se definido, esse URB será usado com _URB_PIPE_REQUEST.

Observação

Esse URB substitui URB_FUNCTION_RESET_PIPE.

O motorista do ônibus realiza três tarefas em resposta a esta URB:

Primeiro, para todos os pipes, exceto pipes isócronos, esse URB envia uma solicitação CLEAR_FEATURE para limpar o recurso de ENDPOINT_HALT do dispositivo.

Em segundo lugar, o driver de barramento USB redefine a alternância de dados no lado do host, conforme exigido pela especificação USB. O dispositivo USB deve redefinir a alternância de dados no lado do dispositivo quando o driver de barramento limpar seu recurso de ENDPOINT_HALT. Como alguns dispositivos não compatíveis não dão suporte a esse recurso, a Microsoft fornece os dois URBs adicionais: URB_FUNCTION_SYNC_CLEAR_STALL e URB_FUNCTION_SYNC_RESET_PIPE. Isso permite que os drivers cliente limpem o recurso ENDPOINT_HALT no dispositivo ou redefinam o pipe no lado do host, respectivamente, sem afetar a alternância de dados no lado do host. Se o dispositivo não redefinir a alternância de dados quando deveria, o driver cliente poderá compensar esse defeito não redefinindo a alternância de dados do lado do host. Se a alternância de dados for redefinida no lado do host, mas não no lado do dispositivo, os pacotes sairão da sequência e o dispositivo poderá descartar pacotes.

Em terceiro lugar, depois que o motorista do ônibus redefinir o pipe com êxito, ele retomará as transferências com o próximo URB enfileirado.

Após uma redefinição de pipe, as transferências são retomadas com o próximo URB enfileirado.

Não é necessário limpar uma condição de parada em um pipe de controle padrão. O pipe de controle padrão sempre deve aceitar pacotes de instalação e, portanto, se ele parar, a pilha USB limpará a condição de parada automaticamente. O driver cliente não precisa executar nenhuma ação especial para limpar a condição de parada em um pipe padrão.

Todas as transferências devem ser anuladas ou canceladas antes de tentar redefinir o pipe.

Esse URB deve ser enviado em PASSIVE_LEVEL.

URB_FUNCTION_SYNC_RESET_PIPE

Limpa a condição de parada no lado do host de um pipe. Se definido, esse URB será usado com _URB_PIPE_REQUEST como a estrutura de dados.

Esse URB permite que um cliente limpe o estado interrompido de um pipe sem redefinir a alternância de dados e sem limpar a condição de parada do ponto de extremidade (recurso ENDPOINT_HALT). Para limpar uma condição de parada no pipe, redefina a alternância de dados do lado do host e limpe uma parada no dispositivo com uma única operação, use URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL.

Os seguintes códigos de status são importantes e têm o significado indicado:

USBD_STATUS_INVALID_PIPE_HANDLE

O PipeHandle não é válido

USBD_STATUS_ERROR_BUSY

O ponto de extremidade tem transferências ativas pendentes.

Não é necessário limpar uma condição de parada em um pipe de controle padrão. O pipe de controle padrão sempre deve aceitar pacotes de instalação e, portanto, se ele for interrompido, a pilha USB limpará a condição de parada automaticamente. O driver do cliente não precisa executar nenhuma ação especial para limpar a condição de parada em um pipe padrão.

Todas as transferências devem ser anuladas ou canceladas antes de tentar redefinir o pipe.

Esse URB deve ser enviado em PASSIVE_LEVEL.

Disponível no Windows XP e em sistemas operacionais posteriores.

URB_FUNCTION_SYNC_CLEAR_STALL

Limpa a condição de parada no ponto de extremidade. Para todos os pipes, exceto pipes isócronos, esse URB envia uma solicitação CLEAR_FEATURE para limpar o recurso de ENDPOINT_HALT do dispositivo. No entanto, ao contrário da função RB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL, essa função URB não redefine a alternância de dados no lado do host do pipe. A especificação USB exige que os dispositivos redefinam a alternância de dados do lado do dispositivo depois que o cliente limpa o recurso de ENDPOINT_HALT do dispositivo, mas alguns dispositivos não compatíveis não redefinem os dados corretamente. Os drivers de cliente que gerenciam esses dispositivos podem compensar esse defeito limpando a condição de parada diretamente com URB_FUNCTION_SYNC_CLEAR_STALL em vez de redefinir o pipe com URB_FUNCTION_SYNC_RESET_PIPE_AND_CLEAR_STALL. URB_FUNCTION_SYNC_CLEAR_STALL limpa uma condição de parada no dispositivo sem redefinir a alternância de dados do lado do host. Isso impede que um dispositivo não compatível interprete o próximo pacote como uma retransmissão e descarte o pacote.

Se definido, o URB será usado com _URB_PIPE_REQUEST como a estrutura de dados.

Essa função URB deve ser enviada em PASSIVE_LEVEL

Disponível no Windows XP e em sistemas operacionais posteriores.

URB_FUNCTION_GET_DESCRIPTOR_FROM_DEVICE

Recupera o descritor do dispositivo de um dispositivo USB específico. Se definido, o URB será usado com _URB_CONTROL_DESCRIPTOR_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_DESCRIPTOR_FROM_ENDPOINT

Recupera o descritor de um ponto de extremidade em uma interface para um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_DESCRIPTOR_REQUEST como a estrutura de dados.

URB_FUNCTION_SET_DESCRIPTOR_TO_DEVICE

Define um descritor de dispositivo em um dispositivo. Se definido, o URB será usado com _URB_CONTROL_DESCRIPTOR_REQUEST como a estrutura de dados.

URB_FUNCTION_SET_DESCRIPTOR_TO_ENDPOINT

Define um descritor de ponto de extremidade em um ponto de extremidade para uma interface. Se definido, o URB será usado com _URB_CONTROL_DESCRIPTOR_REQUEST como a estrutura de dados.

URB_FUNCTION_SET_FEATURE_TO_DEVICE

Define um recurso definido por USB em um dispositivo. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_SET_FEATURE_TO_INTERFACE

Define um recurso definido por USB em uma interface para um dispositivo. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_SET_FEATURE_TO_ENDPOINT

Define um recurso definido por USB em um ponto de extremidade para uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_SET_FEATURE_TO_OTHER

Define um recurso definido por USB em um destino definido pelo dispositivo em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_CLEAR_FEATURE_TO_DEVICE

Limpa um recurso definido por USB em um dispositivo. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_CLEAR_FEATURE_TO_INTERFACE

Limpa um recurso definido por USB em uma interface para um dispositivo. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_CLEAR_FEATURE_TO_ENDPOINT

Limpa um recurso definido por USB em um ponto de extremidade, para uma interface, em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_CLEAR_FEATURE_TO_OTHER

Limpa um recurso definido por USB em um destino definido pelo dispositivo em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_FEATURE_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_STATUS_FROM_DEVICE

Recupera status de um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_GET_STATUS_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_STATUS_FROM_INTERFACE

Recupera status de uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_GET_STATUS_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_STATUS_FROM_ENDPOINT

Recupera status de um ponto de extremidade para uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_GET_STATUS_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_STATUS_FROM_OTHER

Recupera status de um destino definido pelo dispositivo em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_GET_STATUS_REQUEST como a estrutura de dados.

URB_FUNCTION_VENDOR_DEVICE

Envia um comando específico do fornecedor para um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_VENDOR_INTERFACE

Envia um comando específico do fornecedor para uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_VENDOR_ENDPOINT

Envia um comando específico do fornecedor para um ponto de extremidade em uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_VENDOR_OTHER

Envia um comando específico do fornecedor para um destino definido pelo dispositivo em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_CLASS_DEVICE

Envia um comando específico de classe definido por USB para um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_CLASS_INTERFACE

Envia um comando específico de classe definido por USB para uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_CLASS_ENDPOINT

Envia um comando específico de classe definido por USB para um ponto de extremidade, em uma interface, em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_CLASS_OTHER

Envia um comando específico de classe definido por USB para um destino definido pelo dispositivo em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_VENDOR_OR_CLASS_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_CONFIGURATION

Recupera a configuração atual em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_GET_CONFIGURATION_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_INTERFACE

Recupera as configurações atuais de uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_GET_INTERFACE_REQUEST como a estrutura de dados.

Disponível no Windows 2000, no Windows Vista e em sistemas operacionais posteriores. Não disponível no Windows XP.

URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE

Recupera o descritor de uma interface para um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_DESCRIPTOR_REQUEST como a estrutura de dados.

URB_FUNCTION_SET_DESCRIPTOR_TO_INTERFACE

Define um descritor para uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_CONTROL_DESCRIPTOR_REQUEST como a estrutura de dados.

URB_FUNCTION_GET_MS_FEATURE_DESCRIPTOR

Recupera um descritor de recursos do sistema operacional da Microsoft de um dispositivo USB ou de uma interface em um dispositivo USB. Se definido, o URB será usado com _URB_OS_FEATURE_DESCRIPTOR_REQUEST como a estrutura de dados.

Disponível no Windows XP e em sistemas de operação posteriores.

URB_FUNCTION_OPEN_STATIC_STREAMS

Abre fluxos no ponto de extremidade em massa especificado. Se definido, o URB será usado com _URB_OPEN_STATIC_STREAMS como a estrutura de dados.

Disponível em Windows 8. Para obter informações sobre como formatar um URB para uma solicitação de fluxo aberto, consulte Como abrir e fechar fluxos estáticos em um ponto de extremidade em massa USB.

URB_FUNCTION_CLOSE_STATIC_STREAMS

Fecha todos os fluxos abertos no ponto de extremidade em massa especificado. Se definido, o URB será usado com _URB_PIPE_REQUEST como a estrutura de dados.

Status

Contém um código USBD_STATUS_XXX no retorno do driver do controlador de host.

UsbdDeviceHandle

Reservado. Não use.

UsbdFlags

Reservado. Não use.

Comentários

A estrutura _URB_HEADER é membro de todas as solicitações USB que fazem parte da estrutura URB. A estrutura _URB_HEADER é usada para fornecer informações comuns sobre cada solicitação para o driver do controlador de host.

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