Tizen Native API  5.5

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
    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.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/secureelement
Parameters:
[in]channelHandle to the 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_GENERALA general error occurred
SMARTCARD_ERROR_IO_ERRORI/O error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard 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.

Since :
2.3.1
Remarks:
select_resp must be released using free().
Parameters:
[in]channelHandle to the channel
[out]select_respByte array to retrieve the SELECT response
[out]lengthThe length of select_resp
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_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.

Since :
2.3.1
Parameters:
[in]channelHandle to the channel
[out]sessionSession handle of the given channel
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_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.

Since :
2.3.1
Parameters:
[in]channelHandle to the channel
[out]is_basic_channelTrue or false depending on the channel type
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_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.

Since :
2.3.1
Parameters:
[in]channelHandle to the channel
[out]is_closedTrue or false depending on the channel 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_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).

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/secureelement
Parameters:
[in]channelHandle to the channel
[out]is_successTrue 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_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_ILLEGAL_STATEIllegal state of execution error
SMARTCARD_ERROR_OPERATION_NOT_SUPPORTEDOperation not supported from SE
SMARTCARD_ERROR_IO_ERRORI/O error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard 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.

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]channelHandle to the channel
[in]cmdCommand APDU to be send to the secure element
[in]cmd_lenSize of command APDU
[out]respByte array for the response APDU plus status words
[out]lengthThe length of resp
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_ILLEGAL_STATEIllegal state of execution error
SMARTCARD_ERROR_IO_ERRORI/O error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard 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).

Since :
2.3.1
Remarks:
resp must be released using free().
Parameters:
[in]channelHandle to the channel
[out]respByte array for the response APDU plus status words
[out]lengthThe length of resp
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_ILLEGAL_STATEIllegal state of execution error
SMARTCARD_ERROR_NOT_INITIALIZEDSmartcard service not initialized
See also:
smartcard_session_open_basic_channel()
smartcard_session_open_logical_channel()