USBD_UrbAllocate function (usbdlib.h)

Article
10/21/2021

The USBD_UrbAllocate routine allocates a USB Request Block (URB).

Syntax

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

Parameters

[in] USBDHandle

USBD handle that is retrieved by the client driver in a previous call to the USBD_CreateHandle routine.

[out] Urb

Pointer to the newly allocated URB structure. All members of the structure are set to zero. The client driver must free the URB when the driver has finished using it by calling USBD_UrbFree.

Return value

The USBD_UrbAllocate routine returns STATUS_SUCCESS if the request is successful. Otherwise, USBD_UrbAllocate sets Urb to NULL and returns a failure code.

Possible values include, but are not limited to, STATUS_INVALID_PARAMETER, which indicates the caller passed in NULL to USBDHandle or Urb.

Remarks

The USBD_UrbAllocate routine enables the underlying USB driver stack to allocate an opaque URB context for the URB. By using the URB context, the USB driver stack can process requests more efficiently and reliably. Those optimizations are provided by the USB 3.0 driver stack that is included in Windows 8. The client driver cannot access the URB context; the context is used internally by the bus driver.

Regardless of the USB protocol version of the host controller, the underlying USB driver stack, the target operating system, the client driver must always call USBD_UrbAllocate to allocate an URB structure. USBD_UrbAllocate replaces earlier allocation mechanisms, such as ExAllocatePoolWithTag, or allocating them on the stack.

The client driver must not use USBD_UrbAllocate,

To allocate an URB that has variable length, such as an URB for an isochronous transfer. Instead the client driver must call USBD_IsochUrbAllocate.
If the target operating system is Windows XP with Service Pack 2 (SP2) or an earlier version of Windows.

For more information about replacement routines, see Allocating and Building URBs.

You must call USBD_UrbFree to release the URB allocated by USBD_UrbAllocate.

Examples

The following code example shows how to allocate, submit, and release a URB. The example submits the URB synchronously. For the implementation of the SubmitUrbSync function, see the example section in 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;

}

Requirements

Requirement	Value
Minimum supported client	Requires WDK for Windows 8. Targets Windows Vista and later versions of the Windows operating system.
Target Platform	Desktop
Header	usbdlib.h
Library	Usbdex.lib
IRQL	DISPATCH_LEVEL

Share via