com.ibm.jusb.os

Interface UsbPipeOsImp

All Known Subinterfaces:

UsbControlPipeOsImp

All Known Implementing Classes:

DefaultUsbControlPipeOsImp, DefaultUsbPipeOsImp, LinuxPipeOsImp, WindowsPipeOsImp

public interface UsbPipeOsImp

Interface for Platform-specific implementation of UsbPipe.

All methods are synchronized in the Platform-Independent layer; the implementation does not need to make them Thread-safe.

Author:

Dan Streetman

Method Summary

Methods

Modifier and Type	Method and Description
void	abortAllSubmissions() Stop all submissions in progress.
void	asyncSubmit(List list) Asynchronously submits a List of UsbIrpImps to the platform implementation.
void	asyncSubmit(UsbIrpImp irp) Asynchronously submits this UsbIrpImp to the platform implementation.
void	close() Close the pipe.
void	open() Open this pipe.
void	syncSubmit(List list) Synchronously submits a List of UsbIrpImps to the platform implementation.
void	syncSubmit(UsbIrpImp irp) Synchronously submits this UsbIrpImp to the platform implementation.

Method Detail

open

void open()
          throws UsbException

Open this pipe.

The platform can perform whatever operations it likes. This method does not currently require the platform to guarantee anything after returning.

Throws:

UsbException - If this pipe could not be opened.

syncSubmit

void syncSubmit(UsbIrpImp irp)
                throws UsbException

Synchronously submits this UsbIrpImp to the platform implementation.

The implementation must perform all actions specified in the UsbIrpImp's documentation. In addition, if a UsbException occurs, the implementation should throw it.

Parameters:

irp - the UsbIrpImp to use for this submission.

Throws:

UsbException - If the data transfer was unsuccessful.

syncSubmit

void syncSubmit(List list)
                throws UsbException

Synchronously submits a List of UsbIrpImps to the platform implementation.

All items in the List will be UsbIrpImps. Each UsbIrpImp should be handled in the same manner as syncSubmit, with the only difference being an error for one of the UsbIrpImps does not require the implementation to throw a UsbException for the entire List. The implementation may, at its option, continue processing UsbIrpImps. In either case (return from the method or throw an UsbException), all UsbIrpImps must be handled as specified in the UsbIrpImp documentation, even if they are not processed.

The implementation may call each UsbIrpImp's complete method as each UsbIrpImp completes, or defer calling until all UsbIrpImps in the list have been processed.

Parameters:

list - the UsbIrpImps to use for this submission.

Throws:

UsbException - If any of the UsbIrpImps were unsuccessful (optional).

asyncSubmit

void asyncSubmit(UsbIrpImp irp)
                 throws UsbException

Asynchronously submits this UsbIrpImp to the platform implementation.

This should return as soon as possible. The implementation must perform all actions specified in the UsbIrpImp's documentation. In addition, if the UsbIrpImp is not accepted for processing (i.e. before returning from this method), a UsbException should be thrown. Otherwise (i.e. after returning from this method) no UsbException can be thrown (but should be set on the UsbIrpImp).

Parameters:

irp - the UsbIrpImp to use for this submission

Throws:

UsbException - If the UsbIrpImp was not accepted by the implementation.

asyncSubmit

void asyncSubmit(List list)
                 throws UsbException

Asynchronously submits a List of UsbIrpImps to the platform implementation.

This should return as soon as possible. If any of the UsbIrpImps were not accepted by the implementation, no further UsbIrpImps should be attempted, and the UsbException should be thrown. UsbIrpImps already accepted should continue their normal execution. The implementation must perform all actions specified in the UsbIrpImp's documentation for all UsbIrpImps in the list.

Note that the UsbIrpImp that fails (if any) and all those after it may be completed immediately, which will result in UsbIrpImps in the beginning of the List being in-progress, while the UsbIrpImps in the end of the List will be complete.

Parameters:

list - the UsbIrpImps to use for this submission.

Throws:

UsbException - If one of the UsbIrpImps was not accepted by the implementation.

abortAllSubmissions

void abortAllSubmissions()

Stop all submissions in progress.

This should not return until all submissions have been aborted and are no longer in progress (i.e., the pipe is in a non-busy state). Note that aborted UsbIrps still must be completed; they should have their UsbException set to UsbAbortException.

Obviously, this method must not hang while waiting for submissions to complete, so if submission(s) cannot be aborted natively, the native component must be abandoned and the UsbIrp must be completed (with UsbAbortException).

The implementation may assume no more submissions will occur while this is executing.

close

void close()

Close the pipe.