Added in API level 28

Summary: Methods | Inherited Methods

Session

Kotlin |Java

public final class Session
extends Object

java.lang.Object
↳	android.se.omapi.Session

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 Applet in the Secure Element. This channel can be the basic channel or a logical channel.

See also:

SIMalliance Open Mobile API v3.0

Summary

Public methods
`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)` This method is provided to ease the development of mobile application and for compliancy with existing applications.
`Channel`	`openBasicChannel(byte[] aid, byte p2)` 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, byte p2)` Open a logical channel with the Secure Element, selecting the Applet represented by the given AID.
`Channel`	`openLogicalChannel(byte[] aid)` This method is provided to ease the development of mobile application and for compliancy with existing applications.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public methods

close

Added in API level 28

public void close ()

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

closeChannels

Added in API level 28

public void closeChannels ()

Close any channel opened on this session.

getATR

Added in API level 28

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
`byte[]`	the ATR as a byte array or null.

Throws
`IllegalStateException`	if there was an error connecting to SE or if the service was not connected.

getReader

Added in API level 28

public Reader getReader ()

Get the reader that provides this session.

Returns
`Reader`	The Reader object. This value cannot be `null`.

isClosed

Added in API level 28

public boolean isClosed ()

Tells if this session is closed.

Returns
`boolean`	`true` if the session is closed, false otherwise.

openBasicChannel

Added in API level 28

public Channel openBasicChannel (byte[] aid)

This method is provided to ease the development of mobile application and for compliancy with existing applications. This method is equivalent to openBasicChannel(aid, P2=0x00)

Parameters
`aid`	`byte`: 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
`Channel`	an instance of Channel if available or null.

Throws
`IOException`	if there is a communication problem to the reader or the Secure Element.
`IllegalStateException`	if the Secure Element session is used after being closed.
`IllegalArgumentException`	if the aid's length is not within 5 to 16 (inclusive).
`SecurityException`	if the calling application cannot be granted access to this AID or the default Applet on this session.
`NoSuchElementException`	if the AID on the Secure Element is not available or cannot be selected.
`UnsupportedOperationException`	if the given P2 parameter is not supported by the device

openBasicChannel

Added in API level 28

public Channel openBasicChannel (byte[] aid, 
                byte p2)

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, it 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. With previous release (V2.05) it was not possible to set P2 value, this value was always set to '00'.Except for specific needs it is recommended to keep P2 to '00'. It is recommended that the device allows all values for P2, however only the following values are mandatory: '00', '04', '08', '0C'(as defined in [2]) The implementation of the underlying SELECT command within this method shall be based on ISO 7816-4 with following options:

CLA = '00'
INS = 'A4'
P1 = '04' (Select by DF name/application identifier)

The select response data can be retrieved with byte[] getSelectResponse(). The API shall handle received status word as follow. If the status word indicates that the Secure Element was able to open a channel (e.g. status word '90 00' or status words referencing a warning in ISO-7816-4: '62 XX' or '63 XX') the API shall keep the channel opened and the next getSelectResponse() shall return the received status word. Other received status codes indicating that the Secure Element was able not to open a channel shall be considered as an error and the corresponding channel shall not be opened. The function without P2 as parameter is provided for backwards compatibility and will fall back to a select command with P2='00'.

Parameters
`aid`	`byte`: the AID of the Applet to be selected on this channel, as a byte array, or null if no Applet is to be selected.
`p2`	`byte`: the P2 parameter of the SELECT APDU executed on this channel. This value may be `null`.

Returns
`Channel`	an instance of Channel if available or null.

Throws
`IOException`	if there is a communication problem to the reader or the Secure Element.
`IllegalStateException`	if the Secure Element session is used after being closed.
`IllegalArgumentException`	if the aid's length is not within 5 to 16 (inclusive).
`SecurityException`	if the calling application cannot be granted access to this AID or the default Applet on this session.
`NoSuchElementException`	if the AID on the Secure Element is not available or cannot be selected.
`UnsupportedOperationException`	if the given P2 parameter is not supported by the device

openLogicalChannel

Added in API level 28

public Channel openLogicalChannel (byte[] aid, 
                byte p2)

Open a logical channel with the Secure Element, selecting the Applet represented by the given AID. If the AID is 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. With previous release (V2.05) it was not possible to set P2 value, this value was always set to '00'.Except for specific needs it is recommended to keep P2 to '00'. It is recommended that the device allows all values for P2, however only the following values are mandatory: '00', '04', '08', '0C'(as defined in [2]) The implementation of the underlying SELECT command within this method shall be based on ISO 7816-4 with following options:

CLA = '01' to '03', '40 to 4F'
INS = 'A4'
P1 = '04' (Select by DF name/application identifier)

The select response data can be retrieved with byte[] getSelectResponse(). The API shall handle received status word as follow. If the status word indicates that the Secure Element was able to open a channel (e.g. status word '90 00' or status words referencing a warning in ISO-7816-4: '62 XX' or '63 XX') the API shall keep the channel opened and the next getSelectResponse() shall return the received status word. Other received status codes indicating that the Secure Element was able not to open a channel shall be considered as an error and the corresponding channel shall not be opened. In case of UICC it is recommended for the API to reject the opening of the logical channel without a specific AID, by always answering null to such a request. The function without P2 as parameter is provided for backwards compatibility and will fall back to a select command with P2=00.

Parameters
`aid`	`byte`: the AID of the Applet to be selected on this channel, as a byte array. This value may be `null`.
`p2`	`byte`: the P2 parameter of the SELECT APDU executed on this channel. This value may be `null`.

Returns
`Channel`	an instance of Channel. Null if the Secure Element is unable to provide a new logical channel.

Throws
`IOException`	if there is a communication problem to the reader or the Secure Element.
`IllegalStateException`	if the Secure Element is used after being closed.
`IllegalArgumentException`	if the aid's length is not within 5 to 16 (inclusive).
`SecurityException`	if the calling application cannot be granted access to this AID or the default Applet on this session.
`NoSuchElementException`	if the AID on the Secure Element is not available or cannot be selected or a logical channel is already open to a non-multiselectable Applet.
`UnsupportedOperationException`	if the given P2 parameter is not supported by the device.

openLogicalChannel

Added in API level 28

public Channel openLogicalChannel (byte[] aid)

This method is provided to ease the development of mobile application and for compliancy with existing applications. This method is equivalent to openLogicalChannel(aid, P2=0x00)

Parameters
`aid`	`byte`: the AID of the Applet to be selected on this channel, as a byte array. This value may be `null`.

Returns
`Channel`	an instance of Channel. Null if the Secure Element is unable to provide a new logical channel. This value may be `null`.

Throws
`IOException`	if there is a communication problem to the reader or the Secure Element.
`IllegalStateException`	if the Secure Element is used after being closed.
`IllegalArgumentException`	if the aid's length is not within 5 to 16 (inclusive).
`SecurityException`	if the calling application cannot be granted access to this AID or the default Applet on this session.
`NoSuchElementException`	if the AID on the Secure Element is not available or cannot be selected or a logical channel is already open to a non-multiselectable Applet.
`UnsupportedOperationException`	if the given P2 parameter is not supported by the device.