WdfUsbTargetDeviceCreateUrb function (wdfusb.h)

Article
04/18/2022

[Applies to KMDF only]

The WdfUsbTargetDeviceCreateUrb method allocates a USB request block (URB).

Syntax

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

Parameters

[in] UsbDevice

A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreateWithParameters.

[in, optional] Attributes

A pointer to a caller-supplied WDF_OBJECT_ATTRIBUTES structure that contains attributes for the new memory object. If the driver provides this parameter, the structure's ParentObject member must be a USB device object (WDFUSBDEVICE) or a request object (WDFREQUEST) created by the framework, or any object whose chain of parents leads to one of these types. This parameter is optional and can be WDF_NO_OBJECT_ATTRIBUTES.

[out] UrbMemory

A pointer to a WDFMEMORY-typed location that receives a handle to a framework memory object.

[out, optional] Urb

A pointer to an URB structure that receives the address of the newly allocated URB. This parameter is optional and can be NULL.

Return value

WdfUsbTargetDeviceCreateUrb returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:

Return code	Description
STATUS_INVALID_PARAMETER	An invalid parameter was detected.
STATUS_INVALID_DEVICE_STATE	The driver did not specify a client contract version when it called WDF_USB_DEVICE_CREATE_CONFIG_INIT.
STATUS_INSUFFICIENT_RESOURCES	There was insufficient memory to create a new URB.

This method also might return other NTSTATUS values.

Remarks

Before calling WdfUsbTargetDeviceCreateUrb, a driver must call WdfUsbTargetDeviceCreateWithParameters. If successful, WdfUsbTargetDeviceCreateUrb returns a handle to a framework memory object that describes the newly allocated URB. Typically, a driver calls WdfUsbTargetDeviceCreateUrb from within a request handler.

A driver can call WdfUsbTargetDeviceCreateUrb to allocate an URB structure before calling WdfUsbTargetDeviceFormatRequestForUrb.

WdfUsbTargetDeviceCreateUrb is similar in operation to WdfMemoryCreate. Both methods allocate a framework memory object, and both methods also provide the option of receiving the buffer (in this case, the URB) associated with the memory object. In both cases, the caller can also retrieve the buffer later by calling WdfMemoryGetBuffer.

If the driver provides an Urb parameter when it calls WdfUsbTargetDeviceCreateUrb, you can format the URB manually or by calling the UsbBuildXxx routines.

The memory object and its buffer are deleted when the parent object is deleted. A driver can also delete a memory object and its buffer by calling WdfObjectDelete.

Examples

The following code example declares a framework memory object. The example calls WdfUsbTargetDeviceCreateUrb to allocate a USB request block, and then calls WdfUsbTargetDeviceFormatRequestForUrb to format a request that uses the URB structure's contents. Finally, the example registers a CompletionRoutine callback function and sends the request to an I/O target.

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);
}

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Target Platform	Universal
Minimum KMDF version	1.11
Header	wdfusb.h (include Wdfusb.h)
Library	Wdf01000.sys (see Framework Library Versioning.)
IRQL	<=DISPATCH_LEVEL
DDI compliance rules	DriverCreate(kmdf)

Share via