Tizen Native API  5.5

The Session API provides functions to session.

Required Header

#include <smartcard.h>

Related Features

This API is related with the following features:

  • http://tizen.org/feature/network.secure_element
  • http://tizen.org/feature/network.secure_element.ese
  • http://tizen.org/feature/network.secure_element.uicc
    It is recommended to design feature related codes in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions

int smartcard_session_get_reader (int session, int *reader)
 Gets the reader that provides the given session.
int smartcard_session_get_atr (int session, unsigned char **atr, int *length)
 Gets the Answer to Reset(ATR) of this Secure Element.
int smartcard_session_close (int session)
 Closes the connection with the Secure Element.
int smartcard_session_is_closed (int session, bool *is_closed)
 Checks if the given session is closed.
int smartcard_session_close_channels (int session)
 Closes any channel opened on the given session.
int smartcard_session_open_basic_channel (int session, unsigned char *aid, int aid_len, unsigned char P2, int *channel)
 Gets an access to the basic channel, as defined in the ISO/IEC 7816-4 specification (the one that has number 0).
int smartcard_session_open_logical_channel (int session, unsigned char *aid, int aid_len, unsigned char P2, int *channel)
 Opens a logical channel with the Secure Element, selecting the Applet represented by the given Application ID (AID).

Function Documentation

int smartcard_session_close ( int  session)

Closes the connection with the Secure Element.

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

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/secureelement
Parameters:
[in]sessionhandle to the session
Returns:
0 on success, otherwise a negative error value.
Return values:
SMARTCARD_ERROR_NONESuccessful
SMARTCARD_ERROR_NOT_SUPPORTEDNot supported
SMARTCARD_ERROR_PERMISSION_DENIEDPermission denied
SMARTCARD_ERROR_INVALID_PARAMETERInvalid function parameter
SMARTCARD_ERROR_GENERALA general error occurred
SMARTCARD_ERROR_IO_ERRORI/O error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_reader_open_session()
int smartcard_session_close_channels ( int  session)

Closes any channel opened on the given session.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/secureelement
Parameters:
[in]sessionHandle to the session
Returns:
0 on success, otherwise a negative error value.
Return values:
SMARTCARD_ERROR_NONESuccessful
SMARTCARD_ERROR_NOT_SUPPORTEDNot supported
SMARTCARD_ERROR_PERMISSION_DENIEDPermission denied
SMARTCARD_ERROR_INVALID_PARAMETERInvalid function parameter
SMARTCARD_ERROR_GENERALA general error occurred
SMARTCARD_ERROR_IO_ERRORI/O error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_reader_open_session()
int smartcard_session_get_atr ( int  session,
unsigned char **  atr,
int *  length 
)

Gets the Answer to Reset(ATR) of this Secure Element.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/secureelement
Remarks:
atr must be released using free().
If the Answer to Reset(ATR) for this Secure Element is not available the returned length is set to zero and return value is Success.
Parameters:
[in]sessionHandle to the session
[out]atrByte array to retrieve the Answer to Reset(ATR)
[out]lengthThe length of atr
Returns:
0 on success, otherwise a negative error value.
Return values:
SMARTCARD_ERROR_NONESuccessful
SMARTCARD_ERROR_NOT_SUPPORTEDNot supported
SMARTCARD_ERROR_PERMISSION_DENIEDPermission denied
SMARTCARD_ERROR_INVALID_PARAMETERInvalid function parameter
SMARTCARD_ERROR_GENERALA general error occurred
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_reader_open_session()
int smartcard_session_get_reader ( int  session,
int *  reader 
)

Gets the reader that provides the given session.

Since :
2.3.1
Parameters:
[in]sessionHandle to the session
[out]readerReader handle that provides the given session
Returns:
0 on success, otherwise a negative error value.
Return values:
SMARTCARD_ERROR_NONESuccessful
SMARTCARD_ERROR_NOT_SUPPORTEDNot supported
SMARTCARD_ERROR_INVALID_PARAMETERInvalid function parameter
SMARTCARD_ERROR_GENERALA general error occurred
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_reader_open_session()
int smartcard_session_is_closed ( int  session,
bool *  is_closed 
)

Checks if the given session is closed.

Since :
2.3.1
Parameters:
[in]sessionHandle to the session
[out]is_closedTrue or false depending on the session state
Returns:
0 on success, otherwise a negative error value.
Return values:
SMARTCARD_ERROR_NONESuccessful
SMARTCARD_ERROR_NOT_SUPPORTEDNot supported
SMARTCARD_ERROR_INVALID_PARAMETERInvalid function parameter
SMARTCARD_ERROR_GENERALA general error occurred
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_reader_open_session()
int smartcard_session_open_basic_channel ( int  session,
unsigned char *  aid,
int  aid_len,
unsigned char  P2,
int *  channel 
)

Gets an access to the basic channel, as defined in the ISO/IEC 7816-4 specification (the one that has number 0).

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/secureelement
Remarks:
ex) unsigned char aid[] = {0xA0, 0x00, 0x00, 0x00, 0x63, 0x50, 0x4B, 0x43, 0x53, 0x2D, 0x31, 0x35};
If the Application ID (AID) is null, it means no Applet is to be selected on this channel and the default Applet is used.
Opening of the basic channel to a specific applet is NOT allowed for UICC.
Parameters:
[in]sessionHandle to the session
[in]aidByte array containing the Application ID (AID) to be selected on the given channel
[in]aid_lenSize of byte array or 0 when no SELECT should be executed
[in]P2P2 byte of the SELECT command if executed
[out]channelHandle of the basic channel
Returns:
0 on success, otherwise a negative error value.
Return values:
SMARTCARD_ERROR_NONESuccessful
SMARTCARD_ERROR_NOT_SUPPORTEDNot supported
SMARTCARD_ERROR_PERMISSION_DENIEDPermission denied
SMARTCARD_ERROR_INVALID_PARAMETERInvalid function parameter
SMARTCARD_ERROR_CHANNEL_NOT_AVAILABLENo channel available
SMARTCARD_ERROR_GENERALA general error occurred
SMARTCARD_ERROR_NO_SUCH_ELEMENTNo such element error
SMARTCARD_ERROR_IO_ERRORI/O error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_reader_open_session()
int smartcard_session_open_logical_channel ( int  session,
unsigned char *  aid,
int  aid_len,
unsigned char  P2,
int *  channel 
)

Opens a logical channel with the Secure Element, selecting the Applet represented by the given Application ID (AID).

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/secureelement
Remarks:
ex) unsigned char aid[] = {0xA0, 0x00, 0x00, 0x00, 0x63, 0x50, 0x4B, 0x43, 0x53, 0x2D, 0x31, 0x35};
If the Application ID (AID) is null, it means no Applet is to be selected on this channel and the default Applet is used.
Parameters:
[in]sessionHandle to the session
[in]aidByte array containing the Application ID (AID) to be selected on the given channel
[in]aid_lenSize of byte array or 0 when no SELECT should be executed
[in]P2P2 byte of the SELECT command if executed
[out]channelHandle of the new logical channel
Returns:
0 on success, otherwise a negative error value.
Return values:
SMARTCARD_ERROR_NONESuccessful
SMARTCARD_ERROR_NOT_SUPPORTEDNot supported
SMARTCARD_ERROR_PERMISSION_DENIEDPermission denied
SMARTCARD_ERROR_INVALID_PARAMETERInvalid function parameter
SMARTCARD_ERROR_CHANNEL_NOT_AVAILABLENo channel available
SMARTCARD_ERROR_GENERALA general error occurred
SMARTCARD_ERROR_NO_SUCH_ELEMENTNo such element error
SMARTCARD_ERROR_IO_ERRORI/O error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_reader_open_session()