WdfUsbTargetDeviceCreateUrb method

[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

UsbDevice [in]

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

Attributes [in, optional]

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.

UrbMemory [out]

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

Urb [out, optional]

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:

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
                   ) == FALSE) {
    status = WdfRequestGetStatus(request);
}

Requirements

See also

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceFormatRequestForUrb

WdfUsbTargetDeviceCreateIsochUrb

WDF_USB_DEVICE_CREATE_CONFIG_INIT

Send comments about this topic to Microsoft