WdfUsbTargetDeviceCreateUrb 函数 (wdfusb.h)

  • 项目

[仅适用于 KMDF]

WdfUsbTargetDeviceCreateUrb 方法 (URB) 分配 USB 请求块。

语法

NTSTATUS WdfUsbTargetDeviceCreateUrb(
  [in]            WDFUSBDEVICE           UsbDevice,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]           WDFMEMORY              *UrbMemory,
  [out, optional] PURB                   *Urb
);

参数

[in] UsbDevice

USB 设备对象的句柄，该对象是从之前调用 WdfUsbTargetDeviceCreateWithParameters 获取的。

[in, optional] Attributes

指向调用方提供的 WDF_OBJECT_ATTRIBUTES 结构的指针，该结构包含新内存对象的属性。 如果驱动程序提供此参数，则结构的 ParentObject 成员必须是 WDFUSBDEVICE) (USB 设备对象，或者是框架创建的 WDFREQUEST) (请求对象，或者其父链导致其中一种类型的任何对象。 此参数是可选的，可以WDF_NO_OBJECT_ATTRIBUTES。

[out] UrbMemory

指向 WDFMEMORY 类型位置的指针，该位置接收框架内存对象的句柄。

[out, optional] Urb

指向 URB 结构的指针，该结构接收新分配的 URB 的地址。 此参数是可选的，可以为 NULL。

返回值

如果操作成功，WdfUsbTargetDeviceCreateUrb 将返回STATUS_SUCCESS。 否则，此方法可返回以下值之一：

返回代码 说明
STATUS_INVALID_PARAMETER
 检测到无效的参数。
STATUS_INVALID_DEVICE_STATE
 驱动程序在调用 WDF_USB_DEVICE_CREATE_CONFIG_INIT 时未指定客户端协定版本。
STATUS_INSUFFICIENT_RESOURCES
 内存不足，无法创建新的 URB。
 

此方法还可能返回其他 NTSTATUS 值。

注解

在调用 WdfUsbTargetDeviceCreateUrb 之前，驱动程序必须调用 WdfUsbTargetDeviceCreateWithParameters。 如果成功， WdfUsbTargetDeviceCreateUrb 将返回描述新分配的 URB 的框架内存对象的句柄。 通常，驱动程序从请求处理程序中调用 WdfUsbTargetDeviceCreateUrb。

驱动程序可以在调用 WdfUsbTargetDeviceFormatRequestForUrb 之前调用 WdfUsbTargetDeviceCreateUrb 来分配 URB 结构。

WdfUsbTargetDeviceCreateUrb 在操作上与 WdfMemoryCreate 类似。 这两种方法都分配一个框架内存对象，并且这两种方法还提供接收缓冲区 (在本例中，URB) 与内存对象关联的选项。 在这两种情况下，调用方以后还可以通过调用 WdfMemoryGetBuffer 来检索缓冲区。

如果驱动程序在调用 WdfUsbTargetDeviceCreateUrb 时提供了 Urb 参数，则可以手动或通过调用 UsbBuildXxx 例程来设置 URB 的格式。

删除父对象时，将删除内存对象及其缓冲区。 驱动程序还可以通过调用 WdfObjectDelete 来删除内存对象及其缓冲区。

示例

下面的代码示例声明框架内存对象。 该示例调用 WdfUsbTargetDeviceCreateUrb 来分配 USB 请求块，然后调用 WdfUsbTargetDeviceFormatRequestForUrb 来格式化使用 URB 结构的内容的请求。 最后，该示例注册 一个 CompletionRoutine 回调函数，并将请求发送到 I/O 目标。

WDFMEMORY memory;
PURB urb = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = UsbDevice;

status = WdfUsbTargetDeviceCreateUrb(
    pDevContext->WdfUsbTargetDevice,
    &objectAttribs,
    &memory,
    &urb);

status = WdfUsbTargetDeviceFormatRequestForUrb(
    deviceContext->WdfUsbTargetDevice,
    request,
    memory,
    NULL);

WdfRequestSetCompletionRoutine(
    request,
    MyCompletionRoutine,
    NULL);

if (!WdfRequestSend(
        request,
        WdfUsbTargetDeviceGetIoTarget(UsbDevice),
        NULL)) {
    status = WdfRequestGetStatus(request);
}

要求

要求 值
最低受支持的客户端 Windows Vista
目标平台 通用
最低 KMDF 版本 1.11
标头 wdfusb.h (包括 Wdfusb.h)
Library Wdf01000.sys (请参阅框架库版本控制.)
IRQL <=DISPATCH_LEVEL
DDI 符合性规则 DriverCreate (kmdf)

另请参阅

WDF_USB_DEVICE_CREATE_CONFIG_INIT

WdfUsbTargetDeviceCreateIsochUrb

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb