Top Description Methods
javax.usb

public Interface UsbIrp

Known Direct Subinterfaces
javax.usb.UsbControlIrp
Known Direct Implementers
javax.usb.util.DefaultUsbIrp
Interface for a USB IRP (I/O Request Packet).

Some USB communication requires addiitonal metadata that describes how the actual data should be handled when being transferred. This UsbIrp encapsulates the actual data buffer, as well as other metadata that gives the user more control and knowledge over how the data is handled.

Before submitting this, at least some of these (depending on UsbIrp implementation) must be performed:

Any UsbIrp implementation must behave as specified in this interface's documentation, including the specified defaults. Note that setData also sets the offset to 0 and the length to data.length; if other values should be used, use the 3-parameter setData or set the offset and length with their setters after setting the data.

The javax.usb implementation will set the data length or, if unsuccessful, the UsbException, after processing. Finally, it will call complete.

See the USB 1.1 specification section 5.3.2 for details on USB IRPs. The IRP defined in this API has more than is mentioned in the USB 1.1 specification.

Author
Dan Streetman

Method Summary

Modifier and TypeMethod and Description
public void
complete()

Set this as complete.

public boolean

Returns:

If short packects should be accepted.
getAcceptShortPacket()

If short packets should be accepted.

public int

Returns:

The amount of data that was transferred.
getActualLength()

The amount of data that was transferred.

public byte[]

Returns:

The data.
getData()

Get the data.

public int

Returns:

The amount of data to transfer.
getLength()

The amount of data to transfer.

public int

Returns:

The offset.
getOffset()

Get the starting offset of the data.

public UsbException

Returns:

The UsbException, or null.
getUsbException()

Get the UsbException.

public boolean

Returns:

If this UsbIrp has completed.
isComplete()

If this has completed.

public boolean

Returns:

If a UsbException occurred.
isUsbException()

If a UsbException occured.

public void
setAcceptShortPacket(boolean
If short packets should be accepted.
accept)

Set if short packets should be accepted.

public void
setActualLength(int
The amount of data that was transferred.
length)

Set the amount of data that was transferred.

public void
setComplete(boolean
If this is complete or not.
complete)

Set this as complete or not.

public void
setData(byte[]
The data.
data)

Set the data.

public void
setData(byte[]
The data.
data, int
The offset.
offset, int
The length.
length)

Set the data.

public void
setLength(int
The amount of data to transfer.
length)

Set the amount of data to transfer.

public void
setOffset(int
The offset.
offset)

Set the offset.

public void
setUsbException(UsbException
The UsbException.
usbException)

Set the UsbException.

public void
waitUntilComplete()

Wait until complete.

public void
waitUntilComplete(long
The maximum number of milliseconds to wait.
timeout)

Wait until complete, or the timeout has expired.

Method Detail

completeback to summary
public void complete()

Set this as complete.

This is the last method the implementation calls; it indicates the UsbIrp has completed. The implementation will set the actual length, even if the submission was unsuccessful, before calling this. The implementation will set the UsbException, if appropriate, before calling this.

After calling this isComplete will return true.

getAcceptShortPacketback to summary
public boolean getAcceptShortPacket()

If short packets should be accepted.

See the USB 1.1 specification sec 5.3.2 for details on short packets and short packet detection. If short packets are accepted (true), a short packet indicates the end of data. If short packets are not accepted (false), a short packet will generate an UsbException. The default is true.

Returns:boolean

If short packects should be accepted.

getActualLengthback to summary
public int getActualLength()

The amount of data that was transferred.

This defaults to 0, and is set by the implementation during/after submission (if successful). This will never be negative. If isUsbException is true, this value is undefined.

Returns:int

The amount of data that was transferred.

getDataback to summary
public byte[] getData()

Get the data.

This defaults to an empty byte[]. This will never be null.

Returns:byte[]

The data.

getLengthback to summary
public int getLength()

The amount of data to transfer.

This indicates the amount of data to transfer.

This defaults to 0, and this is set to data.length by the 1-parameter setData. This will never be negative.

Returns:int

The amount of data to transfer.

getOffsetback to summary
public int getOffset()

Get the starting offset of the data.

This indicates the starting byte in the data.

This defaults to 0, and this is set to 0 by the 1-parameter setData. This will never be negative.

Returns:int

The offset.

getUsbExceptionback to summary
public UsbException getUsbException()

Get the UsbException.

If no UsbException occurred, this returns null.

Returns:UsbException

The UsbException, or null.

isCompleteback to summary
public boolean isComplete()

If this has completed.

This must be false before use.

Returns:boolean

If this UsbIrp has completed.

isUsbExceptionback to summary
public boolean isUsbException()

If a UsbException occured.

If this is true, the actual length is undefined.

Returns:boolean

If a UsbException occurred.

setAcceptShortPacketback to summary
public void setAcceptShortPacket(boolean accept)

Set if short packets should be accepted.

This should be set by the application.

Parameters
accept:boolean

If short packets should be accepted.

setActualLengthback to summary
public void setActualLength(int length)

Set the amount of data that was transferred.

The implementation will set this to the amount of data actually transferred. The implementation will set this before calling complete, regardless of whether the submission was successful or not.

Parameters
length:int

The amount of data that was transferred.

Exceptions
IllegalArgumentException:
If the length is negative.
setCompleteback to summary
public void setComplete(boolean complete)

Set this as complete or not.

This is what isComplete returns.

Parameters
complete:boolean

If this is complete or not.

setDataback to summary
public void setData(byte[] data)

Set the data.

This sets the offset to 0, and sets the length to data.length; if those values are inappropriate, use the other setData.

Parameters
data:byte[]

The data.

Exceptions
IllegalArgumentException:
If the data is null.
setDataback to summary
public void setData(byte[] data, int offset, int length)

Set the data.

This sets the data, offset, and length to the specified values.

Parameters
data:byte[]

The data.

offset:int

The offset.

length:int

The length.

Exceptions
IllegalArgumentException:
If the data is null, or offset and/or length is negative.
setLengthback to summary
public void setLength(int length)

Set the amount of data to transfer.

Parameters
length:int

The amount of data to transfer.

Exceptions
IllegalArgumentException:
If the length is negative.
setOffsetback to summary
public void setOffset(int offset)

Set the offset.

Parameters
offset:int

The offset.

Exceptions
IllegalArgumentException:
If the offset is negative.
setUsbExceptionback to summary
public void setUsbException(UsbException usbException)

Set the UsbException.

Parameters
usbException:UsbException

The UsbException.

waitUntilCompleteback to summary
public void waitUntilComplete()

Wait until complete.

This will block until this is complete.

waitUntilCompleteback to summary
public void waitUntilComplete(long timeout)

Wait until complete, or the timeout has expired.

This will block until this is complete, or the timeout has expired. The timeout is ignored if it is 0 or less, i.e. this will behave as the no-timeout method.

Parameters
timeout:long

The maximum number of milliseconds to wait.