função USBD_UrbAllocate (usbdlib.h)

A rotina de 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 de URB recém-alocada. Todos os membros da estrutura são definidos como zero. O driver cliente deve liberar o URB quando o driver terminar de usá-lo chamando USBD_UrbFree.

Valor de retorno

A rotina de 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, que indica o chamador passado em NULL para USBDHandle ou Urb.

Observações

A rotina de USBD_UrbAllocate permite que a pilha de driver USB subjacente aloque um contexto URB opaco para a 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 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 sempre deve chamar USBD_UrbAllocate para alocar uma estrutura de URB. USBD_UrbAllocate substitui mecanismos de alocação anteriores, como ExAllocatePoolWithTag ou aloque-os na pilha.

O driver cliente deve não usar USBD_UrbAllocate,

• Para alocar um URB que tenha comprimento variável, como um URB para uma transferência isocrona. Em vez disso, o driver 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.

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 obter a implementação da função SubmitUrbSync, consulte a seção de exemplo em How to Submit an 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

Consulte também

alocação e criação de URBs

enviar solicitações para um dispositivo USB

USBD_UrbFree