WdfUsbTargetDeviceCreateUrb function (wdfusb.h)
[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 |
---|---|
|
An invalid parameter was detected. |
|
The driver did not specify a client contract version when it called WDF_USB_DEVICE_CREATE_CONFIG_INIT. |
|
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) |
See also
WDF_USB_DEVICE_CREATE_CONFIG_INIT
WdfUsbTargetDeviceCreateIsochUrb