Expand Minimize

USBD_UrbAllocate routine

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

Syntax


NTSTATUS USBD_UrbAllocate(
  _In_   USBD_HANDLE USBDHandle,
  _Out_  PURB *Urb
);

Parameters

USBDHandle [in]

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

Urb [out]

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.


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

Version

Requires WDK for Windows 8. Targets Windows Vista and later versions of the Windows operating system.

Header

Usbdlib.h

Library

Usbdex.lib

IRQL

DISPATCH_LEVEL

See also

USBD_UrbFree
Allocating and Building URBs
Sending Requests to a USB Device

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft