función USBD_UrbAllocate (usbdlib.h)

La rutina USBD_UrbAllocate asigna un bloque de solicitud USB (URB).

Sintaxis

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

Parámetros

[in] USBDHandle

Identificador USBD recuperado por el controlador cliente en una llamada anterior a la rutina USBD_CreateHandle .

[out] Urb

Puntero a la estructura URB recién asignada. Todos los miembros de la estructura se establecen en cero. El controlador cliente debe liberar el URB cuando el controlador haya terminado de usarlo llamando a USBD_UrbFree.

Valor devuelto

La rutina USBD_UrbAllocate devuelve STATUS_SUCCESS si la solicitud se realiza correctamente. De lo contrario, USBD_UrbAllocate establece Urb en NULL y devuelve un código de error.

Entre los valores posibles se incluyen, entre otros, STATUS_INVALID_PARAMETER, que indica el autor de la llamada pasado a NULL a USBDHandle o Urb.

Comentarios

La rutina de USBD_UrbAllocate permite que la pila de controladores USB subyacente asigne un contexto URB opaco para el URB. Mediante el uso del contexto URB, la pila de controladores USB puede procesar solicitudes de forma más eficaz y confiable. Esas optimizaciones las proporciona la pila de controladores USB 3.0 que se incluye en Windows 8. El controlador cliente no puede acceder al contexto URB; el controlador de autobús usa internamente el contexto.

Independientemente de la versión del protocolo USB del controlador host, la pila de controladores USB subyacente, el sistema operativo de destino, el controlador cliente siempre debe llamar a USBD_UrbAllocate para asignar una estructura URB . USBD_UrbAllocate reemplaza los mecanismos de asignación anteriores, como ExAllocatePoolWithTag, o asignándolos en la pila.

El controlador cliente no debe usar USBD_UrbAllocate,

• Para asignar un URB con longitud variable, como un URB para una transferencia isócrónica. En su lugar, el controlador cliente debe llamar a USBD_IsochUrbAllocate.
• Si el sistema operativo de destino es Windows XP con Service Pack 2 (SP2) o una versión anterior de Windows.

Para obtener más información sobre las rutinas de reemplazo, vea Asignar y compilar direcciones URL.

Debe llamar a USBD_UrbFree para liberar el URB asignado por USBD_UrbAllocate.

Ejemplos

En el ejemplo de código siguiente se muestra cómo asignar, enviar y liberar un URB. En el ejemplo se envía el URB de forma sincrónica. Para la implementación de la función SubmitUrbSync, consulte la sección de ejemplo de Cómo enviar un 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	Value
Cliente mínimo compatible	Requiere WDK para Windows 8. Tiene como destino Windows Vista y versiones posteriores del sistema operativo Windows.
Plataforma de destino	Escritorio
Encabezado	usbdlib.h
Library	Usbdex.lib
IRQL	DISPATCH_LEVEL

Consulte también

Asignar y compilar direcciones URL

Envío de solicitudes a un dispositivo USB

USBD_UrbFree