javax.usb.util
Class UsbUtil.SynchronizedUsbPipe

java.lang.Object
  extended by javax.usb.util.UsbUtil.SynchronizedUsbPipe
All Implemented Interfaces:
UsbPipe
Enclosing class:
UsbUtil

public static class UsbUtil.SynchronizedUsbPipe
extends java.lang.Object
implements UsbPipe

A synchronized UsbPipe wrapper implementation.

Not all methods are synchronized; the open/close methods are synchronized to each other, and the submission and abort methods are synchronized to each other.


Field Summary
 UsbPipe usbPipe
           
 
Constructor Summary
UsbUtil.SynchronizedUsbPipe(UsbPipe usbPipe)
           
 
Method Summary
 void abortAllSubmissions()
          Stop all submissions in progress.
 void addUsbPipeListener(UsbPipeListener listener)
          Adds the listener.
 UsbIrp asyncSubmit(byte[] data)
          Asynchonously submit a byte[] to the UsbPipe.
 void asyncSubmit(java.util.List list)
          Asynchonously submit a List of UsbIrps to the UsbPipe.
 void asyncSubmit(UsbIrp irp)
          Asynchonously submit a UsbIrp to the UsbPipe.
 void close()
          Close this UsbPipe.
 UsbControlIrp createUsbControlIrp(byte bmRequestType, byte bRequest, short wValue, short wIndex)
          Create a UsbControlIrp.
 UsbIrp createUsbIrp()
          Create a UsbIrp.
 UsbEndpoint getUsbEndpoint()
          Get this pipe's UsbEndpoint.
 boolean isActive()
          If this pipe is active.
 boolean isOpen()
          If this pipe is open.
 void open()
          Open this UsbPipe.
 void removeUsbPipeListener(UsbPipeListener listener)
          Removes the listener.
 int syncSubmit(byte[] data)
          Synchonously submit a byte[] to the UsbPipe.
 void syncSubmit(java.util.List list)
          Synchonously submit a List of UsbIrps to the UsbPipe.
 void syncSubmit(UsbIrp irp)
          Synchonously submit a UsbIrp to the UsbPipe.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

usbPipe

public UsbPipe usbPipe
Constructor Detail

UsbUtil.SynchronizedUsbPipe

public UsbUtil.SynchronizedUsbPipe(UsbPipe usbPipe)
Method Detail

open

public void open()
          throws UsbException,
                 UsbNotActiveException,
                 UsbNotClaimedException
Description copied from interface: UsbPipe
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.

Specified by:
open in interface UsbPipe
Throws:
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.

close

public void close()
           throws UsbException,
                  UsbNotOpenException
Description copied from interface: UsbPipe
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.

Specified by:
close in interface UsbPipe
Throws:
UsbException - If the UsbPipe could not be closed.
UsbNotOpenException - If the UsbPipe is not open.

isActive

public boolean isActive()
Description copied from interface: UsbPipe
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.

Specified by:
isActive in interface UsbPipe
Returns:
If this UsbPipe is active.

isOpen

public boolean isOpen()
Description copied from interface: UsbPipe
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.

Specified by:
isOpen in interface UsbPipe
Returns:
If this UsbPipe is open.

getUsbEndpoint

public UsbEndpoint getUsbEndpoint()
Description copied from interface: UsbPipe
Get this pipe's UsbEndpoint.

Specified by:
getUsbEndpoint in interface UsbPipe
Returns:
The associated endpoint.

syncSubmit

public int syncSubmit(byte[] data)
               throws UsbException,
                      UsbNotOpenException
Description copied from interface: UsbPipe
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.

Specified by:
syncSubmit in interface UsbPipe
Parameters:
data - The buffer to use.
Returns:
The number of bytes actually transferred.
Throws:
UsbException - If an error occurs.
UsbNotOpenException - If the pipe is not open.

asyncSubmit

public UsbIrp asyncSubmit(byte[] data)
                   throws UsbException,
                          UsbNotOpenException
Description copied from interface: UsbPipe
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.

Specified by:
asyncSubmit in interface UsbPipe
Parameters:
data - The buffer to use.
Returns:
A UsbIrp representing the submission.
Throws:
UsbException - If an error occurs.
UsbNotOpenException - If the pipe is not open.

syncSubmit

public void syncSubmit(UsbIrp irp)
                throws UsbException,
                       UsbNotOpenException
Description copied from interface: UsbPipe
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.

Specified by:
syncSubmit in interface UsbPipe
Parameters:
irp - A UsbIrp to use for the submission.
Throws:
UsbException - If an error occurs.
UsbNotOpenException - If the pipe is not open.

asyncSubmit

public void asyncSubmit(UsbIrp irp)
                 throws UsbException,
                        UsbNotOpenException
Description copied from interface: UsbPipe
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.

Specified by:
asyncSubmit in interface UsbPipe
Parameters:
irp - The UsbIrp to use for the submission.
Throws:
UsbException - If an error occurs.
UsbNotOpenException - If the pipe is not open.

syncSubmit

public void syncSubmit(java.util.List list)
                throws UsbException,
                       UsbNotOpenException
Description copied from interface: UsbPipe
Synchonously submit a List of UsbIrps to the UsbPipe.

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

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

Specified by:
syncSubmit in interface UsbPipe
Parameters:
list - The List of UsbIrps.
Throws:
UsbException - If an error occurs.
UsbNotOpenException - If the pipe is not open.

asyncSubmit

public void asyncSubmit(java.util.List list)
                 throws UsbException,
                        UsbNotOpenException
Description copied from interface: UsbPipe
Asynchonously submit a List of UsbIrps to the UsbPipe.

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

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

Specified by:
asyncSubmit in interface UsbPipe
Parameters:
list - The List of UsbIrps.
Throws:
UsbException - If an error occurs.
UsbNotOpenException - If the pipe is not open.

abortAllSubmissions

public void abortAllSubmissions()
                         throws UsbNotOpenException
Description copied from interface: UsbPipe
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.

Specified by:
abortAllSubmissions in interface UsbPipe
Throws:
UsbNotOpenException - If the pipe is not open.

createUsbIrp

public UsbIrp createUsbIrp()
Description copied from interface: UsbPipe
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).

Specified by:
createUsbIrp in interface UsbPipe
Returns:
A UsbIrp ready for use.

createUsbControlIrp

public UsbControlIrp createUsbControlIrp(byte bmRequestType,
                                         byte bRequest,
                                         short wValue,
                                         short wIndex)
Description copied from interface: UsbPipe
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.

Specified by:
createUsbControlIrp in interface UsbPipe
Parameters:
bmRequestType - The bmRequestType.
bRequest - The bRequest.
wValue - The wValue.
wIndex - The wIndex.
Returns:
A UsbControlIrp ready for use.

addUsbPipeListener

public void addUsbPipeListener(UsbPipeListener listener)
Description copied from interface: UsbPipe
Adds the listener.

Specified by:
addUsbPipeListener in interface UsbPipe
Parameters:
listener - The UsbPipeListener.

removeUsbPipeListener

public void removeUsbPipeListener(UsbPipeListener listener)
Description copied from interface: UsbPipe
Removes the listener.

Specified by:
removeUsbPipeListener in interface UsbPipe
Parameters:
listener - The UsbPipeListener.