javax.usb
Interface UsbIrp

All Known Subinterfaces:

UsbControlIrp

All Known Implementing Classes:

DefaultUsbControlIrp, DefaultUsbIrp, UsbControlIrpImp, UsbIrpImp

public interface UsbIrp

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:

• The data must be set.
• The data offset, may be set.
• The data length may be set.
• The Short Packet policy may be set.
• The UsbException must be null (and isUsbException must be false).
• The complete state must be false.

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

void	complete() Set this as complete.
boolean	getAcceptShortPacket() If short packets should be accepted.
int	getActualLength() The amount of data that was transferred.
byte[]	getData() Get the data.
int	getLength() The amount of data to transfer.
int	getOffset() Get the starting offset of the data.
UsbException	getUsbException() Get the UsbException.
boolean	isComplete() If this has completed.
boolean	isUsbException() If a UsbException occured.
void	setAcceptShortPacket(boolean accept) Set if short packets should be accepted.
void	setActualLength(int length) Set the amount of data that was transferred.
void	setComplete(boolean complete) Set this as complete or not.
void	setData(byte[] data) Set the data.
void	setData(byte[] data, int offset, int length) Set the data.
void	setLength(int length) Set the amount of data to transfer.
void	setOffset(int offset) Set the offset.
void	setUsbException(UsbException usbException) Set the UsbException.
void	waitUntilComplete() Wait until complete.
void	waitUntilComplete(long timeout) Wait until complete, or the timeout has expired.

Method Detail

getData

byte[] getData()

Get the data.

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

Returns:

The data.

getOffset

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:

The offset.

getLength

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:

The amount of data to transfer.

getActualLength

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:

The amount of data that was transferred.

setData

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 - The data.

Throws:

java.lang.IllegalArgumentException - If the data is null.

setData

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

Set the data.

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

Parameters:

data - The data.

offset - The offset.

length - The length.

Throws:

java.lang.IllegalArgumentException - If the data is null, or offset and/or length is negative.

setOffset

void setOffset(int offset)

Set the offset.

Parameters:

offset - The offset.

Throws:

java.lang.IllegalArgumentException - If the offset is negative.

setLength

void setLength(int length)

Set the amount of data to transfer.

Parameters:

length - The amount of data to transfer.

Throws:

java.lang.IllegalArgumentException - If the length is negative.

setActualLength

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 - The amount of data that was transferred.

Throws:

java.lang.IllegalArgumentException - If the length is negative.

isUsbException

boolean isUsbException()

If a UsbException occured.

If this is true, the actual length is undefined.

Returns:

If a UsbException occurred.

getUsbException

UsbException getUsbException()

Get the UsbException.

If no UsbException occurred, this returns null.

Returns:

The UsbException, or null.

setUsbException

void setUsbException(UsbException usbException)

Set the UsbException.

Parameters:

usbException - The UsbException.

getAcceptShortPacket

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:

If short packects should be accepted.

setAcceptShortPacket

void setAcceptShortPacket(boolean accept)

Set if short packets should be accepted.

This should be set by the application.

Parameters:

accept - If short packets should be accepted.

isComplete

boolean isComplete()

If this has completed.

This must be false before use.

Returns:

If this UsbIrp has completed.

setComplete

void setComplete(boolean complete)

Set this as complete or not.

This is what isComplete returns.

Parameters:

complete - If this is complete or not.

complete

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.

waitUntilComplete

void waitUntilComplete()

Wait until complete.

This will block until this is complete.

waitUntilComplete

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 - The maximum number of milliseconds to wait.