The Channel API provides functions to channel.

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
http://tizen.org/feature/network.secure_element.usb
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_channel_close (int channel)
	Closes the given channel to the Secure Element.
int	smartcard_channel_is_basic_channel (int channel, bool *is_basic_channel)
	Checks if the given channel is the basic channel.
int	smartcard_channel_is_closed (int channel, bool *is_closed)
	Checks if the given channel is closed.
int	smartcard_channel_get_select_response (int channel, unsigned char *select_resp, int length)
	Gets the response to the select command.
int	smartcard_channel_get_session (int channel, int *session)
	Gets the session that has opened the given channel.
int	smartcard_channel_transmit (int channel, unsigned char cmd, int cmd_len, unsigned char resp, int length)
	Transmits an APDU command (as per ISO/IEC 7816-4) to the Secure Element.
int	smartcard_channel_transmit_retrieve_response (int channel, unsigned char *resp, int length)
	Retrieves the response APDU of the previous transmit() call (helper function).
int	smartcard_channel_select_next (int channel, bool *is_success)
	Performs a selection of the next Applet on the given channel that matches to the partial Application ID (AID).

Function Documentation

int smartcard_channel_close ( int channel )

Closes the given channel to the Secure Element.

Closes the given channel to the Secure Element. This function releases any resources associated with the channel.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/secureelement

Parameters:

[in] channel Handle to the 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_GENERAL	A general error occurred
SMARTCARD_ERROR_IO_ERROR	I/O error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard service not initialized

See also:: smartcard_session_open_basic_channel(); smartcard_session_open_logical_channel()

int smartcard_channel_get_select_response	(	int	channel,
		unsigned char **	select_resp,
		int *	length
	)

Gets the response to the select command.

Retrieves the response to the SELECT command for the given channel. The response is stored in the byte array pointed to by the select_resp parameter, and its length is stored in the location pointed to by the length parameter. Note that the select_resp buffer must be released using free() after use.

Since :: 2.3.1

Remarks:: select_resp must be released using free().

Parameters:

[in]	channel	Handle to the channel
[out]	select_resp	Byte array to retrieve the SELECT response
[out]	length	The length of select_resp

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_session_open_basic_channel(); smartcard_session_open_logical_channel()

int smartcard_channel_get_session	(	int	channel,
		int *	session
	)

Gets the session that has opened the given channel.

Retrieves the session handle that has opened the given channel. The session handle is stored in the location pointed to by the session parameter.

Since :: 2.3.1

Parameters:

[in]	channel	Handle to the channel
[out]	session	Session handle of the given channel

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_session_open_basic_channel(); smartcard_session_open_logical_channel()

int smartcard_channel_is_basic_channel	(	int	channel,
		bool *	is_basic_channel
	)

Checks if the given channel is the basic channel.

Determines whether the given channel is a basic channel. The result is stored in the location pointed to by the is_basic_channel parameter.

Since :: 2.3.1

Parameters:

[in]	channel	Handle to the channel
[out]	is_basic_channel	True or false depending on the channel type

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_session_open_basic_channel(); smartcard_session_open_logical_channel()

int smartcard_channel_is_closed	(	int	channel,
		bool *	is_closed
	)

Checks if the given channel is closed.

Checks whether the given channel is closed. The result is stored in the location pointed to by the is_closed parameter.

Since :: 2.3.1

Parameters:

[in]	channel	Handle to the channel
[out]	is_closed	True or false depending on the channel 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_session_open_basic_channel(); smartcard_session_open_logical_channel()

int smartcard_channel_select_next	(	int	channel,
		bool *	is_success
	)

Performs a selection of the next Applet on the given channel that matches to the partial Application ID (AID).

Selects the next Applet on the given channel that matches the partial Application ID (AID). The result is stored in the location pointed to by the is_success parameter.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/secureelement

Parameters:

[in]	channel	Handle to the channel
[out]	is_success	True or false depending whether another applet with the partial Application ID (AID) could be selected on the given 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_GENERAL	A general error occurred
SMARTCARD_ERROR_ILLEGAL_STATE	Illegal state of execution error
SMARTCARD_ERROR_OPERATION_NOT_SUPPORTED	Operation not supported from SE
SMARTCARD_ERROR_IO_ERROR	I/O error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard service not initialized

See also:: smartcard_session_open_basic_channel(); smartcard_session_open_logical_channel()

int smartcard_channel_transmit	(	int	channel,
		unsigned char *	cmd,
		int	cmd_len,
		unsigned char **	resp,
		int *	length
	)

Transmits an APDU command (as per ISO/IEC 7816-4) to the Secure Element.

Transmits an APDU command to the Secure Element associated with the given channel. The response to the command is stored in the byte array pointed to by the resp parameter, and its length is stored in the location pointed to by the length parameter. Note that the resp buffer must be released using free() after use.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/secureelement

Remarks:: resp must be released using free().; MANAGE_CHANNEL commands are not allowed.; SELECT by DF Name (P1=04) are not allowed.; bytes with channel numbers are de-masked.

Parameters:

[in]	channel	Handle to the channel
[in]	cmd	Command APDU to be send to the secure element
[in]	cmd_len	Size of command APDU
[out]	resp	Byte array for the response APDU plus status words
[out]	length	The length of resp

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_ILLEGAL_STATE	Illegal state of execution error
SMARTCARD_ERROR_IO_ERROR	I/O error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard service not initialized

See also:: smartcard_session_open_basic_channel(); smartcard_session_open_logical_channel()

int smartcard_channel_transmit_retrieve_response	(	int	channel,
		unsigned char **	resp,
		int *	length
	)

Retrieves the response APDU of the previous transmit() call (helper function).

Retrieves the response APDU from the previous transmit() call for the given channel. The response is stored in the byte array pointed to by the resp parameter, and its length is stored in the location pointed to by the length parameter. Note that the resp buffer must be released using free() after use.

Since :: 2.3.1

Remarks:: resp must be released using free().

Parameters:

[in]	channel	Handle to the channel
[out]	resp	Byte array for the response APDU plus status words
[out]	length	The length of resp

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_ILLEGAL_STATE	Illegal state of execution error
SMARTCARD_ERROR_NOT_INITIALIZED	Smartcard service not initialized

See also:: smartcard_session_open_basic_channel(); smartcard_session_open_logical_channel()

Required Header

Related Features

Functions

Function Documentation