通过

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。

返回值

如果请求成功，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（SP2）或早期版本的 Windows 的 Windows XP。
有关替换例程的详细信息，请参阅 分配和生成 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
库 Usbdex.lib
IRQL DISPATCH_LEVEL

另请参阅

分配和生成 URL

向 USB 设备发送请求

USBD_UrbFree