org.simalliance.openmobileapi
Class Channel

java.lang.Object
  extended by org.simalliance.openmobileapi.Channel

public class Channel
extends java.lang.Object

Instances of this class represent an ISO7816-4 channel opened to a secure element. It can be either a logical channel or the default channel. They can be used to send APDUs to the secure element. Channels are opened by calling the Session.openBasicChannel(byte[]) or Session.openLogicalChannel(byte[]) methods.

See Also:
SIMalliance Open Mobile API v2.02

Method Summary
 void close()
          Closes this channel to the Secure Element.
 byte[] getSelectResponse()
          Returns the data as received from the application select command inclusively the status word.
 Session getSession()
          Get the session that has opened this channel.
 boolean isBasicChannel()
          Returns a boolean telling if this channel is the basic channel.
 boolean isClosed()
          Tells if this channel is closed.
 boolean selectNext()
          Performs a selection of the next Applet on this channel that matches to the partial AID specified in the openBasicChannel(byte[] aid) or openLogicalChannel(byte[] aid) method.
 byte[] transmit(byte[] command)
          Transmit an APDU command (as per ISO7816-4) to the secure element and wait for the response.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

close

public void close()
Closes this channel to the Secure Element. If the method is called when the channel is already closed, this method will be ignored. The close() method shall wait for completion of any pending transmit(byte[] command) before closing the channel.


isClosed

public boolean isClosed()
Tells if this channel is closed.

Returns:
true if the channel is closed, false otherwise.

isBasicChannel

public boolean isBasicChannel()
Returns a boolean telling if this channel is the basic channel.

Returns:
true if this channel is a basic channel. false if this channel is a logical channel.

transmit

public byte[] transmit(byte[] command)
                throws java.io.IOException
Transmit an APDU command (as per ISO7816-4) to the secure element and wait for the response. The underlying layers might generate as much TPDUs as necessary to transport this APDU. The transport part is invisible from the application.
The system ensures the synchronization between all the concurrent calls to this method, and that only one APDU will be sent at a time, irrespective of the number of TPDUs that might be required to transport it to the SE.
The channel information in the class byte in the APDU will be completely ignored. The underlying system will add any required information to ensure the APDU is transported on this channel. There are restrictions on the set of commands that can be sent:

Parameters:
command - the APDU command to be transmitted, as a byte array.
Returns:
the response received, as a byte array.
Throws:
java.io.IOException - if there is a communication problem to the reader or the Secure Element.
java.lang.IllegalStateException - if the channel is used after being closed.
java.lang.IllegalArgumentException - if the command byte array is less than 4 bytes long.
java.lang.IllegalArgumentException - if the length of the APDU is not coherent with the length of the command byte array.
java.lang.SecurityException - if the command is filtered by the security policy

getSession

public Session getSession()
Get the session that has opened this channel.

Returns:
the session object this channel is bound to.

getSelectResponse

public byte[] getSelectResponse()
Returns the data as received from the application select command inclusively the status word. The returned byte array contains the data bytes in the following order: [<first data byte>, ..., <last data byte>, <sw1>, <sw2>]

Returns:
The data as returned by the application select command inclusively the status word. Only the status word if the application select command has no returned data. Returns null if an application select command has not been performed or the selection response can not be retrieved by the reader implementation.

selectNext

public boolean selectNext()
                   throws java.io.IOException
Performs a selection of the next Applet on this channel that matches to the partial AID specified in the openBasicChannel(byte[] aid) or openLogicalChannel(byte[] aid) method. This mechanism can be used by a device application to iterate through all Applets matching to the same partial AID. If selectNext() returns true a new Applet was successfully selected on this channel. If no further Applet exists with matches to the partial AID this method returns false and the already selected Applet stays selected.

Returns:
true if new Applet was successfully selected. false if no further Applet exists which matches the partial AID.
Throws:
java.io.IOException - if there is a communication problem to the reader or the Secure Element.
java.lang.IllegalStateException - if the channel is used after being closed or it is not connected.
java.lang.SecurityException - if the command is filtered by the security policy