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] session handle to the session

Returns:: 0 on success, otherwise a negative error value.

Return values:

SMARTCARD_ERROR_NONE	Successful
SMARTCARD_ERROR_NOT_SUPPORTED	Not supported
SMARTCARD_ERROR_PERMISSION_DENIED	Permission denied
SMARTCARD_ERROR_INVALID_PARAMETER	Invalid function parameter
SMARTCARD_ERROR_GENERAL	A general error occurred
SMARTCARD_ERROR_IO_ERROR	I/O error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard 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] session Handle to the session

Returns:: 0 on success, otherwise a negative error value.

Return values:

SMARTCARD_ERROR_NONE	Successful
SMARTCARD_ERROR_NOT_SUPPORTED	Not supported
SMARTCARD_ERROR_PERMISSION_DENIED	Permission denied
SMARTCARD_ERROR_INVALID_PARAMETER	Invalid function parameter
SMARTCARD_ERROR_GENERAL	A general error occurred
SMARTCARD_ERROR_IO_ERROR	I/O error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard 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]	session	Handle to the session
[out]	atr	Byte array to retrieve the Answer to Reset(ATR)
[out]	length	The length of atr

Returns:: 0 on success, otherwise a negative error value.

Return values:

SMARTCARD_ERROR_NONE	Successful
SMARTCARD_ERROR_NOT_SUPPORTED	Not supported
SMARTCARD_ERROR_PERMISSION_DENIED	Permission denied
SMARTCARD_ERROR_INVALID_PARAMETER	Invalid function parameter
SMARTCARD_ERROR_GENERAL	A general error occurred
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard 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]	session	Handle to the session
[out]	reader	Reader handle that provides the given session

Returns:: 0 on success, otherwise a negative error value.

Return values:

SMARTCARD_ERROR_NONE	Successful
SMARTCARD_ERROR_NOT_SUPPORTED	Not supported
SMARTCARD_ERROR_INVALID_PARAMETER	Invalid function parameter
SMARTCARD_ERROR_GENERAL	A general error occurred
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard 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]	session	Handle to the session
[out]	is_closed	True or false depending on the session state

Returns:: 0 on success, otherwise a negative error value.

Return values:

SMARTCARD_ERROR_NONE	Successful
SMARTCARD_ERROR_NOT_SUPPORTED	Not supported
SMARTCARD_ERROR_INVALID_PARAMETER	Invalid function parameter
SMARTCARD_ERROR_GENERAL	A general error occurred
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard 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]	session	Handle to the session
[in]	aid	Byte array containing the Application ID (AID) to be selected on the given channel
[in]	aid_len	Size of byte array or 0 when no SELECT should be executed
[in]	P2	P2 byte of the SELECT command if executed
[out]	channel	Handle of the basic channel

Returns:: 0 on success, otherwise a negative error value.

Return values:

SMARTCARD_ERROR_NONE	Successful
SMARTCARD_ERROR_NOT_SUPPORTED	Not supported
SMARTCARD_ERROR_PERMISSION_DENIED	Permission denied
SMARTCARD_ERROR_INVALID_PARAMETER	Invalid function parameter
SMARTCARD_ERROR_CHANNEL_NOT_AVAILABLE	No channel available
SMARTCARD_ERROR_GENERAL	A general error occurred
SMARTCARD_ERROR_NO_SUCH_ELEMENT	No such element error
SMARTCARD_ERROR_IO_ERROR	I/O error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard 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]	session	Handle to the session
[in]	aid	Byte array containing the Application ID (AID) to be selected on the given channel
[in]	aid_len	Size of byte array or 0 when no SELECT should be executed
[in]	P2	P2 byte of the SELECT command if executed
[out]	channel	Handle of the new logical channel

Returns:: 0 on success, otherwise a negative error value.

Return values:

SMARTCARD_ERROR_NONE	Successful
SMARTCARD_ERROR_NOT_SUPPORTED	Not supported
SMARTCARD_ERROR_PERMISSION_DENIED	Permission denied
SMARTCARD_ERROR_INVALID_PARAMETER	Invalid function parameter
SMARTCARD_ERROR_CHANNEL_NOT_AVAILABLE	No channel available
SMARTCARD_ERROR_GENERAL	A general error occurred
SMARTCARD_ERROR_NO_SUCH_ELEMENT	No such element error
SMARTCARD_ERROR_IO_ERROR	I/O error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard service not initialized

See also:: smartcard_reader_open_session()

Required Header

Related Features

Functions

Function Documentation