Expand Minimize

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:

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



Requirements

Minimum support

Windows Vista

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

See also

WdfUsbTargetDeviceCreateWithParameters
WdfUsbTargetDeviceFormatRequestForUrb
WdfUsbTargetDeviceCreateIsochUrb
WDF_USB_DEVICE_CREATE_CONFIG_INIT

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft