WdfUsbTargetDeviceCreateIsochUrb method

[Applies to KMDF only]

The WdfUsbTargetDeviceCreateIsochUrb method allocates an isochronous USB request block (URB).

Syntax

NTSTATUS WdfUsbTargetDeviceCreateIsochUrb(
  [in]             WDFUSBDEVICE UsbDevice,
  [in, optional]   PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]             ULONG NumberOfIsochPackets,
  [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.

NumberOfIsochPackets [in]

Specifies the number of isochronous packets for which the system allocates memory in the URB.

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 new isochronous URB. The framework initializes contents of the URB structure to zero. This parameter is optional and can be NULL.

Return value

WdfUsbTargetDeviceCreateIsochUrb 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 WdfUsbTargetDeviceCreateIsochUrb, a driver must call WdfUsbTargetDeviceCreateWithParameters. If successful, WdfUsbTargetDeviceCreateIsochUrb returns a handle to a framework memory object that describes the newly allocated isochronous URB.

A driver can call WdfUsbTargetDeviceCreateIsochUrb to allocate a URB structure before calling WdfUsbTargetDeviceFormatRequestForUrb.

Typically, a driver calls WdfUsbTargetDeviceCreateIsochUrb from within a request handler.

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.

For related information, see the Remarks section of WdfUsbTargetDeviceCreateUrb.

Examples

The following code example is based on the PerformIsochTransfer routine in the Isorwr sample driver. The example calls WdfUsbTargetDeviceCreateIsochUrb to allocate an isochronous USB request block. The example determines the number of bytes required to hold the isochronous transfer request, and then manually configures the URB header and the isochronous packets in the URB. At this point, the driver can call WdfUsbTargetPipeFormatRequestForUrb, as shown in the example in WdfUsbTargetDeviceCreateUrb.

USBD_PIPE_HANDLE usbdPipeHandle;
ULONG numPackets = UserBufferLength/TransferSizePerFrame;
ULONG urbSize;
PURB urb;  
WDFMEMORY memory;

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

status = WdfUsbTargetDeviceCreateIsochUrb(
                                     pDevContext->WdfUsbTargetDevice,  
                                     &objectAttribs,  
                                     0, 
                                     numPackets, 
                                     &memory,  
                                     NULL  
                                     ); 
 
urb = WdfMemoryGetBuffer(urbMemory, &urbSize); 
urbSize = GET_ISO_URB_SIZE(numPackets);  

usbdPipeHandle = WdfUsbTargetPipeWdmGetPipeHandle(pipe);
urb->UrbIsochronousTransfer.Hdr.Length = GET_ISO_URB_SIZE(numPackets);  
urb->UrbIsochronousTransfer.Hdr.Function = URB_FUNCTION_ISOCH_TRANSFER;  
urb->UrbIsochronousTransfer.PipeHandle = usbdPipeHandle; 

for (packetId = 0; packetId < numberOfPackets; packetId++) {

     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].Offset = xxx;
     Urb-> UrbIsochronousTransfer.IsoPacket[packetId].YYY = yyy;
}

Requirements

See also

WdfUsbTargetDeviceCreateUrb

WdfUsbTargetDeviceCreateWithParameters

Send comments about this topic to Microsoft