Função USBD_UrbAllocate (usbdlib.h)

A rotina USBD_UrbAllocate aloca um URB (Bloco de Solicitação USB).

Sintaxe

NTSTATUS USBD_UrbAllocate(
  [in]  USBD_HANDLE USBDHandle,
  [out] PURB        *Urb
);

Parâmetros

[in] USBDHandle

Identificador USBD recuperado pelo driver cliente em uma chamada anterior para a rotina de USBD_CreateHandle .

[out] Urb

Ponteiro para a estrutura URB recém-alocada. Todos os membros da estrutura são definidos como zero. O driver do cliente deve liberar o URB quando o driver terminar de usá-lo chamando USBD_UrbFree.

Retornar valor

A rotina USBD_UrbAllocate retornará STATUS_SUCCESS se a solicitação for bem-sucedida. Caso contrário, USBD_UrbAllocate define Urb como NULL e retorna um código de falha.

Os valores possíveis incluem, mas não se limitam a, STATUS_INVALID_PARAMETER, o que indica o chamador passado em NULL para USBDHandle ou Urb.

Comentários

A rotina de USBD_UrbAllocate permite que a pilha de driver USB subjacente aloque um contexto URB opaco para o URB. Usando o contexto URB, a pilha de driver USB pode processar solicitações de forma mais eficiente e confiável. Essas otimizações são fornecidas pela pilha de driver USB 3.0 incluída no Windows 8. O driver do cliente não pode acessar o contexto URB; o contexto é usado internamente pelo motorista do ônibus.

Independentemente da versão do protocolo USB do controlador de host, da pilha de driver USB subjacente, do sistema operacional de destino, o driver cliente deve sempre chamar USBD_UrbAllocate para alocar uma estrutura URB . USBD_UrbAllocate substitui mecanismos de alocação anteriores, como ExAllocatePoolWithTag ou alocando-os na pilha.

O driver cliente não deve usar USBD_UrbAllocate,

• Para alocar um URB com comprimento variável, como um URB para uma transferência isocrona. Em vez disso, o driver do cliente deve chamar USBD_IsochUrbAllocate.
• Se o sistema operacional de destino for o Windows XP com Service Pack 2 (SP2) ou uma versão anterior do Windows.

Para obter mais informações sobre rotinas de substituição, consulte Alocando e criando URBs.

Você deve chamar USBD_UrbFree para liberar o URB alocado por USBD_UrbAllocate.

Exemplos

O exemplo de código a seguir mostra como alocar, enviar e liberar um URB. O exemplo envia a URB de forma síncrona. Para a implementação da função SubmitUrbSync, consulte a seção de exemplo em Como enviar um URB.

NTSTATUS CreateandSubmitURBSynchronously (
    _In_ USBD_HANDLE USBDHandle 
{
    PURB    Urb = NULL;

    NTSTATUS status;

    status = USBD_UrbAllocate(USBDHandle, &Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    //Format the URB for the request. Not Shown.
    status = BuildURBForBulkTransfer (Urb);

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

    status = SubmitUrbSync( TargetDeviceObject,
        Urb)  

    if (!NT_SUCCESS(status))
    {
        goto CreateandSubmitURBExit;
    }

CreateandSubmitURBExit:

    if (Urb)
    {
        USBD_UrbFree( USBDHandle, Urb); 
    }

    return status;

}

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Requer WDK para Windows 8. Tem como destino o Windows Vista e versões posteriores do sistema operacional Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	usbdlib.h
Biblioteca	Usbdex.lib
IRQL	DISPATCH_LEVEL

Confira também

Alocando e criando URBs

Enviando solicitações para um dispositivo USB

USBD_UrbFree