org.simalliance.openmobileapi
Class Session

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

public class Session
extends java.lang.Object

Instances of this class represent a connection session to one of the secure elements available on the device. These objects can be used to get a communication channel with an application in the secure element. This channel can be the basic channel or a logical channel.

See Also:
SIMalliance Open Mobile API v2.02

Method Summary
 void close()
          Close the connection with the Secure Element.
 void closeChannels()
          Close any channel opened on this session.
 byte[] getATR()
          Get the Answer to Reset of this Secure Element.
 Reader getReader()
          Get the reader that provides this session.
 boolean isClosed()
          Tells if this session is closed.
 Channel openBasicChannel(byte[] aid)
          Get an access to the basic channel, as defined in the ISO/IEC 7816-4 specification (the one that has number 0).
 Channel openLogicalChannel(byte[] aid)
          Open a logical channel with the Secure Element, selecting the Applet represented by the given AID.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getReader

public Reader getReader()
Get the reader that provides this session.

Returns:
The Reader object.

getATR

public byte[] getATR()
Get the Answer to Reset of this Secure Element.
The returned byte array can be null if the ATR for this Secure Element is not available.

Returns:
the ATR as a byte array or null.

close

public void close()
Close the connection with the Secure Element. This will close any channels opened by this application with this Secure Element.


isClosed

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

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

closeChannels

public void closeChannels()
Close any channel opened on this session.

Throws:
java.io.IOException

openBasicChannel

public Channel openBasicChannel(byte[] aid)
                         throws java.io.IOException
Get an access to the basic channel, as defined in the ISO/IEC 7816-4 specification (the one that has number 0). The obtained object is an instance of the Channel class. If the AID is null, which means no Applet is to be selected on this channel and the default Applet is used. If the AID is defined then the corresponding Applet is selected. Once this channel has been opened by a device application, it is considered as "locked" by this device application, and other calls to this method will return null, until the channel is closed. Some Secure Elements (like the UICC) might always keep the basic channel locked (i.e. return null to applications), to prevent access to the basic channel, while some other might return a channel object implementing some kind of filtering on the commands, restricting the set of accepted command to a smaller set. It is recommended for the UICC to reject the opening of the basic channel to a specific Applet, by always answering null to such a request. For other Secure Elements, the recommendation is to accept opening the basic channel on the default Applet until another Applet is selected on the basic channel. As there is no other way than a reset to select again the default Applet, the implementation of the transport API should guarantee that the openBasicChannel(null) command will return null until a reset occurs. If such a restriction is not possible, then openBasicChannel(null) should always return null and therefore prevent access to the default Applet on the basic channel.

The optional select response data of an applet can be retrieved with byte[] getSelectResponse().

Parameters:
aid - the AID of the Applet to be selected on this channel, as a byte array, or null if no Applet is to be selected.
Returns:
an instance of Channel if available or null.
Throws:
java.io.IOException - if there is a communication problem to the reader or the Secure Element (e.g. if the SE is not responding).
java.lang.IllegalStateException - if the Secure Element session is used after being closed.
java.lang.IllegalArgumentException - if the aid's length is not within 5 to 16 (inclusive).
java.lang.SecurityException - if the calling application cannot be granted access to this AID or the default application on this session.
java.util.NoSuchElementException - if an Applet with the defined AID does not exist in the SE

openLogicalChannel

public Channel openLogicalChannel(byte[] aid)
                           throws java.io.IOException
Open a logical channel with the Secure Element, selecting the Applet represented by the given AID. The AID can be null, which means no Applet is to be selected on this channel, the default Applet is used. It's up to the Secure Element to choose which logical channel will be used.

The optional select response data of an applet can be retrieved with byte[] getSelectResponse().

A logical channel to an applet can be opened multiple times if the applet implements MultiSelectable.

Parameters:
aid - the AID of the Applet to be selected on this channel, as a byte array.
Returns:
an instance of Channel. Null if the Secure Element is unable to provide a new logical channel.
Throws:
java.io.IOException - if there is a communication problem to the reader or the Secure Element. (e.g. if the SE is not responding)
java.lang.IllegalStateException - if the Secure Element is used after being closed.
java.lang.IllegalArgumentException - if the aid's length is not within 5 to 16 (inclusive).
java.lang.SecurityException - if the calling application cannot be granted access to this AID or the default application on this session.
java.util.NoSuchElementException - if an Applet with the defined AID does not exist in the SE or a logical channel is already open to a non-multiselectable applet