通过

USBD_UrbAllocate 函数 (usbdlib.h)

  • 项目

USBD_UrbAllocate例程分配 USB 请求块 (URB) 。

语法

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

参数

[in] USBDHandle

客户端驱动程序在对 USBD_CreateHandle 例程的先前调用中检索的 USBD 句柄。

[out] Urb

指向新分配的 URB 结构的指针。 结构的所有成员都设置为零。 当驱动程序通过调用 USBD_UrbFree 完成使用 URB 时，客户端驱动程序必须释放 URB。

返回值

如果请求成功 ，USBD_UrbAllocate 例程将返回STATUS_SUCCESS。 否则， USBD_UrbAllocate 将 Urb 设置为 NULL 并返回失败代码。

可能的值包括但不限于 STATUS_INVALID_PARAMETER，它指示调用方以 NULL 传递给 USBDHandle 或 Urb。

注解

USBD_UrbAllocate例程允许基础 USB 驱动程序堆栈为 URB 分配不透明的 URB 上下文。 通过使用 URB 上下文，USB 驱动程序堆栈可以更高效、更可靠地处理请求。 这些优化由Windows 8中包含的 USB 3.0 驱动程序堆栈提供。 客户端驱动程序无法访问 URB 上下文;上下文由总线驱动程序在内部使用。

无论主机控制器、基础 USB 驱动程序堆栈（目标操作系统）的 USB 协议版本如何，客户端驱动程序都必须始终调用 USBD_UrbAllocate 来分配 URB 结构。 USBD_UrbAllocate 替换以前的分配机制，例如 ExAllocatePoolWithTag，或在堆栈上分配它们。

客户端驱动程序 不得 使用 USBD_UrbAllocate，

  • 分配长度可变的 URB，例如常时常量传输的 URB。 客户端驱动程序必须调用 USBD_IsochUrbAllocate。
  • 如果目标操作系统是具有 Service Pack 2 的 Windows XP (SP2) 或早期版本的 Windows。
有关替换例程的详细信息，请参阅 分配和生成 URL。

必须调用 USBD_UrbFree 才能释放 USBD_UrbAllocate分配的 URB。

示例

下面的代码示例演示如何分配、提交和释放 URB。 该示例以同步方式提交 URB。 有关 SubmitUrbSync 函数的实现，请参阅 如何提交 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;

}

要求

要求 值
最低受支持的客户端 Windows 8需要 WDK。 面向 Windows Vista 和更高版本的 Windows 操作系统。
目标平台 桌面
标头 usbdlib.h
Library Usbdex.lib
IRQL DISPATCH_LEVEL

另请参阅

分配和构建 URB

将请求发送到 USB 设备

USBD_UrbFree