Java USB API 1.0.2 · javax.usb.UsbPipe

Modifier and Type	Method and Description
public void	abortAllSubmissions() Stop all submissions in progress.
public void	addUsbPipeListener(UsbPipeListener The UsbPipeListener. listener) Adds the listener.
public UsbIrp	Returns: A UsbIrp representing the submission. asyncSubmit(byte[] The buffer to use. data) Asynchonously submit a byte[] to the UsbPipe.
public void	asyncSubmit(UsbIrp The UsbIrp to use for the submission. irp) Asynchonously submit a UsbIrp to the UsbPipe.
public void	asyncSubmit(List<E> The List of UsbIrps. list) Asynchonously submit a List of UsbIrps to the UsbPipe.
public void	close() Close this UsbPipe.
public UsbControlIrp	Returns: A UsbControlIrp ready for use. createUsbControlIrp(byte The bmRequestType. bmRequestType, byte The bRequest. bRequest, short The wValue. wValue, short The wIndex. wIndex) Create a UsbControlIrp.
public UsbIrp	Returns: A UsbIrp ready for use. createUsbIrp() Create a UsbIrp.
public UsbEndpoint	Returns: The associated endpoint. getUsbEndpoint() Get this pipe's UsbEndpoint.
public boolean	Returns: If this UsbPipe is active. isActive() If this pipe is active.
public boolean	Returns: If this UsbPipe is open. isOpen() If this pipe is open.
public void	open() Open this UsbPipe.
public void	removeUsbPipeListener(UsbPipeListener The UsbPipeListener. listener) Removes the listener.
public int	Returns: The number of bytes actually transferred. syncSubmit(byte[] The buffer to use. data) Synchonously submit a byte[] to the UsbPipe.
public void	syncSubmit(UsbIrp A UsbIrp to use for the submission. irp) Synchonously submit a UsbIrp to the UsbPipe.
public void	syncSubmit(List<E> The List of UsbIrps. list) Synchonously submit a List of UsbIrps to the UsbPipe.

Method Detail

abortAllSubmissions back to summary

abortAllSubmissions	back to summary
public void abortAllSubmissions() throws UsbNotActiveException, UsbNotOpenException, UsbDisconnectedException Stop all submissions in progress. This will abort all submission in progress on the pipe, and block until all submissions are complete. There will be no submissions pending after this returns. Exceptions UsbNotActiveException: If the pipe is not `active`. UsbNotOpenException: If the pipe is not `open`. UsbDisconnectedException: If this pipe (device) has been disconnected.

public void abortAllSubmissions() throws UsbNotActiveException, UsbNotOpenException, UsbDisconnectedException

Stop all submissions in progress.

This will abort all submission in progress on the pipe, and block until all submissions are complete. There will be no submissions pending after this returns.

Exceptions

UsbNotActiveException:: If the pipe is not active.
UsbNotOpenException:: If the pipe is not open.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

addUsbPipeListener	back to summary
public void addUsbPipeListener(UsbPipeListener listener) Adds the listener. Parameters listener:UsbPipeListener The UsbPipeListener.

addUsbPipeListener

back to summary

public void addUsbPipeListener(UsbPipeListener listener)

Adds the listener.

Parameters

listener:UsbPipeListener: The UsbPipeListener.

asyncSubmit back to summary

asyncSubmit	back to summary
public UsbIrp asyncSubmit(byte[] data) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException Asynchonously submit a byte[] to the UsbPipe. This can be used for input and output. This may only be called when the pipe is `open`. The implementation must support multiple (queued) submissions. There is no maximum size restriction; the implementation will segment the buffer into multiple transactions if required. There may be a minimum size, but it will not be more than the `maximum packet size`. The implementation should only place this on a queue, or perform whatever minimal processing is required, and then return. This method will not block until the submission is complete. The returned UsbIrp will represent the submission. Short packets are accepted. There is no way to disable short packet acceptance using this method. See the USB 1.1 specification sec 5.3.2 for details on short packets and short packet detection. Parameters data:byte[] The buffer to use. Returns:UsbIrp A UsbIrp representing the submission. Exceptions UsbException: If an error occurs. UsbNotActiveException: If the pipe is not `active`. UsbNotOpenException: If the pipe is not `open`. IllegalArgumentException: If the data is null. UsbDisconnectedException: If this pipe (device) has been disconnected.

public UsbIrp asyncSubmit(byte[] data) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException

Asynchonously submit a byte[] to the UsbPipe.

This can be used for input and output. This may only be called when the pipe is open. The implementation must support multiple (queued) submissions. There is no maximum size restriction; the implementation will segment the buffer into multiple transactions if required. There may be a minimum size, but it will not be more than the maximum packet size.

The implementation should only place this on a queue, or perform whatever minimal processing is required, and then return. This method will not block until the submission is complete.

The returned UsbIrp will represent the submission.

Short packets are accepted. There is no way to disable short packet acceptance using this method. See the USB 1.1 specification sec 5.3.2 for details on short packets and short packet detection.

Parameters

data:byte[]: The buffer to use.

Returns:UsbIrp

A UsbIrp representing the submission.

Exceptions

UsbException:: If an error occurs.
UsbNotActiveException:: If the pipe is not active.
UsbNotOpenException:: If the pipe is not open.
IllegalArgumentException:: If the data is null.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

asyncSubmit back to summary

asyncSubmit	back to summary
public void asyncSubmit(UsbIrp irp) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException Asynchonously submit a UsbIrp to the UsbPipe. This can be used for input and output. This may only be called when the pipe is `open`. The implementation must support multiple (queued) submissions. There is no maximum size restriction; the implementation will segment the buffer into multiple transactions if required. There may be a minimum size, but it will not be more than the `maximum packet size`. The implementation should only place this on a queue, or perform whatever minimal processing is required, and then return. This method will not block until the submission is complete. If this is a Control `type` pipe, the UsbIrp must be a `UsbControlIrp`. Parameters irp:UsbIrp The UsbIrp to use for the submission. Exceptions UsbException: If an error occurs. UsbNotActiveException: If the pipe is not `active`. UsbNotOpenException: If the pipe is not `open`. IllegalArgumentException: If the UsbIrp is not valid. UsbDisconnectedException: If this pipe (device) has been disconnected.

public void asyncSubmit(UsbIrp irp) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException

Asynchonously submit a UsbIrp to the UsbPipe.

The implementation should only place this on a queue, or perform whatever minimal processing is required, and then return. This method will not block until the submission is complete.

If this is a Control type pipe, the UsbIrp must be a UsbControlIrp.

Parameters

irp:UsbIrp: The UsbIrp to use for the submission.

Exceptions

UsbException:: If an error occurs.
UsbNotActiveException:: If the pipe is not active.
UsbNotOpenException:: If the pipe is not open.
IllegalArgumentException:: If the UsbIrp is not valid.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

asyncSubmit back to summary

asyncSubmit	back to summary
public void asyncSubmit(List<E> list) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException Asynchonously submit a List of UsbIrps to the UsbPipe. This is exactly the same as calling `asyncSubmit` multiple times, except: The UsbIrps will be submitted synchronously on the Java level; and if the implementation permits, synchronously on the native level. The implementation may optimize the submissions, especially in the case of Isochronous transfers. If any of the UsbIrps fails (initial submissions only), the implementation may either continue with the remaining UsbIrps, or fail all remaining UsbIrps. If this is a Control `type` pipe, the UsbIrps must be `UsbControlIrps`. Parameters list:List<E> The List of UsbIrps. Exceptions UsbException: If an error occurs. UsbNotActiveException: If the pipe is not `active`. UsbNotOpenException: If the pipe is not `open`. IllegalArgumentException: If the list is empty or contains any non-UsbIrp objects, or those UsbIrp(s) are invalid. UsbDisconnectedException: If this pipe (device) has been disconnected.

public void asyncSubmit(List<E> list) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException

Asynchonously submit a List of UsbIrps to the UsbPipe.

This is exactly the same as calling asyncSubmit multiple times, except:

The UsbIrps will be submitted synchronously on the Java level; and if the implementation permits, synchronously on the native level.
The implementation may optimize the submissions, especially in the case of Isochronous transfers.
If any of the UsbIrps fails (initial submissions only), the implementation may either continue with the remaining UsbIrps, or fail all remaining UsbIrps.

If this is a Control type pipe, the UsbIrps must be UsbControlIrps.

Parameters

list:List<E>: The List of UsbIrps.

Exceptions

UsbException:: If an error occurs.
UsbNotActiveException:: If the pipe is not active.
UsbNotOpenException:: If the pipe is not open.
IllegalArgumentException:: If the list is empty or contains any non-UsbIrp objects, or those UsbIrp(s) are invalid.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

close back to summary

close	back to summary
public void close() throws UsbException, UsbNotActiveException, UsbNotOpenException, UsbDisconnectedException Close this UsbPipe. The pipe can only be closed while no submissions are pending. All submissions can be aborted by `abortAllSubmissions`. If the pipe is already closed, this fails. Exceptions UsbException: If the UsbPipe could not be closed. UsbNotActiveException: If the UsbPipe is not active. UsbNotOpenException: If the UsbPipe is not open. UsbDisconnectedException: If this pipe (device) has been disconnected.

public void close() throws UsbException, UsbNotActiveException, UsbNotOpenException, UsbDisconnectedException

Close this UsbPipe.

The pipe can only be closed while no submissions are pending. All submissions can be aborted by abortAllSubmissions.

If the pipe is already closed, this fails.

Exceptions

UsbException:: If the UsbPipe could not be closed.
UsbNotActiveException:: If the UsbPipe is not active.
UsbNotOpenException:: If the UsbPipe is not open.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

createUsbControlIrp back to summary

createUsbControlIrp	back to summary
public UsbControlIrp createUsbControlIrp(byte bmRequestType, byte bRequest, short wValue, short wIndex) Create a UsbControlIrp. This creates a UsbControlIrp that may be optimized for use on this UsbPipe. Using this UsbControlIrp instead of a `DefaultUsbControlIrp` may increase performance or decrease memory requirements. The UsbPipe cannot require this UsbControlIrp to be used, all submit methods must accept any UsbControlIrp implementation. Note that if this is not a Control-type UsbPipe, none of the setup packet fields will be used. Parameters bmRequestType:byte The bmRequestType. bRequest:byte The bRequest. wValue:short The wValue. wIndex:short The wIndex. Returns:UsbControlIrp A UsbControlIrp ready for use.

public UsbControlIrp createUsbControlIrp(byte bmRequestType, byte bRequest, short wValue, short wIndex)

Create a UsbControlIrp.

This creates a UsbControlIrp that may be optimized for use on this UsbPipe. Using this UsbControlIrp instead of a DefaultUsbControlIrp may increase performance or decrease memory requirements.

The UsbPipe cannot require this UsbControlIrp to be used, all submit methods must accept any UsbControlIrp implementation.

Note that if this is not a Control-type UsbPipe, none of the setup packet fields will be used.

Parameters

bmRequestType:byte: The bmRequestType.
bRequest:byte: The bRequest.
wValue:short: The wValue.
wIndex:short: The wIndex.

Returns:UsbControlIrp

A UsbControlIrp ready for use.

createUsbIrp back to summary

createUsbIrp	back to summary
public UsbIrp createUsbIrp() Create a UsbIrp. This creates a UsbIrp that may be optimized for use on this UsbPipe. Using this UsbIrp instead of a `DefaultUsbIrp` may increase performance or decrease memory requirements. The UsbPipe cannot require this UsbIrp to be used, all submit methods must accept any UsbIrp implementation (or UsbControlIrp implementation if this is a Control-type UsbPipe). Returns:UsbIrp A UsbIrp ready for use.

public UsbIrp createUsbIrp()

Create a UsbIrp.

This creates a UsbIrp that may be optimized for use on this UsbPipe. Using this UsbIrp instead of a DefaultUsbIrp may increase performance or decrease memory requirements.

The UsbPipe cannot require this UsbIrp to be used, all submit methods must accept any UsbIrp implementation (or UsbControlIrp implementation if this is a Control-type UsbPipe).

Returns:UsbIrp: A UsbIrp ready for use.

getUsbEndpoint	back to summary
public UsbEndpoint getUsbEndpoint() Get this pipe's UsbEndpoint. Returns:UsbEndpoint The associated endpoint.

getUsbEndpoint

back to summary

public UsbEndpoint getUsbEndpoint()

Get this pipe's UsbEndpoint.

Returns:UsbEndpoint: The associated endpoint.

isActive back to summary

isActive	back to summary
public boolean isActive() If this pipe is active. This pipe is active only if it belongs to an `active configuration` and `interface setting`, otherwise it is inactive. This UsbPipe cannot be used if inactive. Returns:boolean If this UsbPipe is active.

public boolean isActive()

If this pipe is active.

This pipe is active only if it belongs to an active configuration and interface setting, otherwise it is inactive. This UsbPipe cannot be used if inactive.

Returns:boolean: If this UsbPipe is active.

isOpen back to summary

isOpen	back to summary
public boolean isOpen() If this pipe is open. This is true after a sucessful `open` until a successful `close`. If this pipe is not `active`, this returns false. Returns:boolean If this UsbPipe is open.

public boolean isOpen()

If this pipe is open.

This is true after a sucessful open until a successful close.

If this pipe is not active, this returns false.

Returns:boolean: If this UsbPipe is open.

open	back to summary
public void open() throws UsbException, UsbNotActiveException, UsbNotClaimedException, UsbDisconnectedException Open this UsbPipe. The pipe cannot be used for communication until it is open. The implementation should, to whatever extent the platform allows, try to ensure the pipe is usable (not in error) before returning successfully. If the pipe has already been opened, this will not succeed. Exceptions UsbException: If the UsbPipe could not be opened. UsbNotActiveException: If the config or interface setting is not active. UsbNotClaimedException: If the interface is not claimed. UsbDisconnectedException: If this pipe (device) has been disconnected.

open

back to summary

public void open() throws UsbException, UsbNotActiveException, UsbNotClaimedException, UsbDisconnectedException

Open this UsbPipe.

The pipe cannot be used for communication until it is open.

The implementation should, to whatever extent the platform allows, try to ensure the pipe is usable (not in error) before returning successfully.

If the pipe has already been opened, this will not succeed.

Exceptions

UsbException:: If the UsbPipe could not be opened.
UsbNotActiveException:: If the config or interface setting is not active.
UsbNotClaimedException:: If the interface is not claimed.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

removeUsbPipeListener	back to summary
public void removeUsbPipeListener(UsbPipeListener listener) Removes the listener. Parameters listener:UsbPipeListener The UsbPipeListener.

removeUsbPipeListener

back to summary

public void removeUsbPipeListener(UsbPipeListener listener)

Removes the listener.

Parameters

listener:UsbPipeListener: The UsbPipeListener.

syncSubmit back to summary

syncSubmit	back to summary
public int syncSubmit(byte[] data) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException Synchonously submit a byte[] to the UsbPipe. This can be used for input and output. This may only be called when the pipe is `open`. The implementation must support multiple (queued) submissions. There is no maximum size restriction; the implementation will segment the buffer into multiple transactions if required. There may be a minimum size, but it will not be more than the `maximum packet size`. This will block until either all data is transferred or an error occurrs. Short packets indicate either the end of data or an error. The return value will indicate the number of bytes sucessfully transferred to or from the target endpoint (depending on direction). The return value will never exceed the total size of the provided buffer. If the operation was not sucessful the UsbException will accurately reflect the cause of the error. Short packets are accepted. There is no way to disable short packet acceptance using this method. See the USB 1.1 specification sec 5.3.2 for details on short packets and short packet detection. Parameters data:byte[] The buffer to use. Returns:int The number of bytes actually transferred. Exceptions UsbException: If an error occurs. UsbNotActiveException: If the pipe is not `active`. UsbNotOpenException: If the pipe is not `open`. IllegalArgumentException: If the data is null. UsbDisconnectedException: If this pipe (device) has been disconnected.

public int syncSubmit(byte[] data) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException

Synchonously submit a byte[] to the UsbPipe.

This will block until either all data is transferred or an error occurrs. Short packets indicate either the end of data or an error.

The return value will indicate the number of bytes sucessfully transferred to or from the target endpoint (depending on direction). The return value will never exceed the total size of the provided buffer. If the operation was not sucessful the UsbException will accurately reflect the cause of the error.

Short packets are accepted. There is no way to disable short packet acceptance using this method. See the USB 1.1 specification sec 5.3.2 for details on short packets and short packet detection.

Parameters

data:byte[]: The buffer to use.

Returns:int

The number of bytes actually transferred.

Exceptions

UsbException:: If an error occurs.
UsbNotActiveException:: If the pipe is not active.
UsbNotOpenException:: If the pipe is not open.
IllegalArgumentException:: If the data is null.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

syncSubmit back to summary

syncSubmit	back to summary
public void syncSubmit(UsbIrp irp) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException Synchonously submit a UsbIrp to the UsbPipe. This can be used for input and output. This may only be called when the pipe is `open`. The implementation must support multiple (queued) submissions. There is no maximum size restriction; the implementation will segment the buffer into multiple transactions if required. There may be a minimum size, but it will not be more than the `maximum packet size`. This will block until either all data is transferred or an error occurrs. Short packets indicate either the end of data or an error. If this is a Control `type` pipe, the UsbIrp must be a `UsbControlIrp`. Parameters irp:UsbIrp A UsbIrp to use for the submission. Exceptions UsbException: If an error occurs. UsbNotActiveException: If the pipe is not `active`. UsbNotOpenException: If the pipe is not `open`. IllegalArgumentException: If the UsbIrp is not valid. UsbDisconnectedException: If this pipe (device) has been disconnected.

public void syncSubmit(UsbIrp irp) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException

Synchonously submit a UsbIrp to the UsbPipe.

This will block until either all data is transferred or an error occurrs. Short packets indicate either the end of data or an error.

If this is a Control type pipe, the UsbIrp must be a UsbControlIrp.

Parameters

irp:UsbIrp: A UsbIrp to use for the submission.

Exceptions

UsbException:: If an error occurs.
UsbNotActiveException:: If the pipe is not active.
UsbNotOpenException:: If the pipe is not open.
IllegalArgumentException:: If the UsbIrp is not valid.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

syncSubmit back to summary

syncSubmit	back to summary
public void syncSubmit(List<E> list) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException Synchonously submit a List of UsbIrps to the UsbPipe. This is exactly the same as calling `syncSubmit` multiple times, except: The UsbIrps will be submitted synchronously on the Java level; and if the implementation permits, synchronously on the native level. The implementation may optimize the submissions, especially in the case of Isochronous transfers. If any of the UsbIrps fails (initial submisson or UsbIrp status), the implementation may either continue with the remaining UsbIrps, or fail all remaining UsbIrps. If this is a Control `type` pipe, the UsbIrps must be `UsbControlIrps`. Parameters list:List<E> The List of UsbIrps. Exceptions UsbException: If an error occurs. UsbNotActiveException: If the pipe is not `active`. UsbNotOpenException: If the pipe is not `open`. IllegalArgumentException: If the list is empty or contains any non-UsbIrp objects, or those UsbIrp(s) are invalid. UsbDisconnectedException: If this pipe (device) has been disconnected.

public void syncSubmit(List<E> list) throws UsbException, UsbNotActiveException, UsbNotOpenException, IllegalArgumentException, UsbDisconnectedException

Synchonously submit a List of UsbIrps to the UsbPipe.

This is exactly the same as calling syncSubmit multiple times, except:

The UsbIrps will be submitted synchronously on the Java level; and if the implementation permits, synchronously on the native level.
The implementation may optimize the submissions, especially in the case of Isochronous transfers.
If any of the UsbIrps fails (initial submisson or UsbIrp status), the implementation may either continue with the remaining UsbIrps, or fail all remaining UsbIrps.

If this is a Control type pipe, the UsbIrps must be UsbControlIrps.

Parameters

list:List<E>: The List of UsbIrps.

Exceptions

UsbException:: If an error occurs.
UsbNotActiveException:: If the pipe is not active.
UsbNotOpenException:: If the pipe is not open.
IllegalArgumentException:: If the list is empty or contains any non-UsbIrp objects, or those UsbIrp(s) are invalid.
UsbDisconnectedException:: If this pipe (device) has been disconnected.

public Interface UsbPipe

Method Summary

Method Detail