Tizen Native API  5.5
Card Emulation

The Card Emulation api provide functions to exchange data with Secure Element.

Required Header

#include <nfc.h>

Overview

The Card Emulation api provide functions to exchange data with Secure Element.

  • send apdu to secure element
  • get atr from secure element

Related Features

This API is related with the following features:

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 nfc_se_enable_card_emulation (void)
 Enables card emulation mode.
int nfc_se_disable_card_emulation (void)
 Disables card emulation mode.
int nfc_se_get_card_emulation_mode (nfc_se_card_emulation_mode_type_e *type)
 Gets the current card emulation mode.
int nfc_hce_send_apdu_response (nfc_se_h handle, unsigned char *resp, unsigned int resp_len)
 Sends APDU (Application Protocol Data Unit) response to CLF (Contactless Front-end).
int nfc_se_set_default_route (nfc_se_type_e powered_on_status, nfc_se_type_e powered_off_status, nfc_se_type_e low_battery_status)
 Sets the default route for each device status.
int nfc_se_is_activated_handler_for_aid (nfc_se_type_e se_type, const char *aid, bool *is_activated_handler)
 Gets the state whether an application to call this function is currently the activated handler for specific AID.
int nfc_se_is_activated_handler_for_category (nfc_se_type_e se_type, nfc_card_emulation_category_type_e category, bool *is_activated_handler)
 Gets the state whether an application to call this function is currently the activated handler for category.
int nfc_se_register_aid (nfc_se_type_e se_type, nfc_card_emulation_category_type_e category, const char *aid)
 Registers a AID for a specific category.
int nfc_se_unregister_aid (nfc_se_type_e se_type, nfc_card_emulation_category_type_e category, const char *aid)
 Unregisters a previously registered AID for the specified category.
int nfc_se_foreach_registered_aids (nfc_se_type_e se_type, nfc_card_emulation_category_type_e category, nfc_se_registered_aid_cb callback, void *user_data)
 Retrieves all registered AID.
int nfc_se_set_preferred_handler (void)
 Sets the application as a preferred handler.
int nfc_se_unset_preferred_handler (void)
 Unsets the application as a preferred handler.

Typedefs

typedef void * nfc_se_h
 The handle to NFC secure element instance.
typedef void(* nfc_hce_event_cb )(nfc_se_h handle, nfc_hce_event_type_e event, unsigned char *apdu, unsigned int apdu_len, void *user_data)
 Called when receiving HCE (Host Card Emulation) event.
typedef void(* nfc_se_registered_aid_cb )(nfc_se_type_e se_type, const char *aid, bool read_only, void *user_data)
 Called once for each registered AID.

Typedef Documentation

typedef void(* nfc_hce_event_cb)(nfc_se_h handle, nfc_hce_event_type_e event, unsigned char *apdu, unsigned int apdu_len, void *user_data)

Called when receiving HCE (Host Card Emulation) event.

Since :
2.3.1
Remarks:
The handle can be used only in the callback. To use outside, make a copy.
The apdu should not be released.
The apdu can be used only in the callback. To use outside, make a copy.
If the event type is NFC_HCE_EVENT_DEACTIVATED or NFC_HCE_EVENT_ACTIVATED, then apdu and apdu_len is NULL and 0.
Parameters:
[in]handleThe handle of connected secure element
[in]eventThe HCE event type
[in]apduThe bytes array of apdu command data
[in]apdu_lenThe size of apdu command bytes array
[in]user_dataThe user data passed from nfc_manager_set_hce_event_cb()
See also:
nfc_manager_set_hce_event_cb()
nfc_manager_unset_hce_event_cb()
typedef void* nfc_se_h

The handle to NFC secure element instance.

Since :
2.3
typedef void(* nfc_se_registered_aid_cb)(nfc_se_type_e se_type, const char *aid, bool read_only, void *user_data)

Called once for each registered AID.

Since :
2.3.1
Remarks:
The aid can be used only in the callback. To use outside, make a copy.
Parameters:
[in]se_typeThe type of Secure Element
[in]aidApplication Id, specified in ISO/IEC 7816-4
[in]read_onlytrue an aid is on read only mode, otherwise false
[in]user_dataThe user data passed from the foreach function
See also:
nfc_se_foreach_registered_aids()

Enumeration Type Documentation

Enumerations for NFC Card Emulation Category type.

Since :
2.3.1
Enumerator:
NFC_CARD_EMULATION_CATEGORY_PAYMENT 

Category used for NFC payment services

NFC_CARD_EMULATION_CATEGORY_OTHER 

Category that can be used for all other card emulation services

Enumerations for NFC Card Emulation HCE event type.

Since :
2.3.1
Enumerator:
NFC_HCE_EVENT_DEACTIVATED 

HCE Deactivated

NFC_HCE_EVENT_ACTIVATED 

HCE Activated

NFC_HCE_EVENT_APDU_RECEIVED 

HCE APDU Received


Function Documentation

int nfc_hce_send_apdu_response ( nfc_se_h  handle,
unsigned char *  resp,
unsigned int  resp_len 
)

Sends APDU (Application Protocol Data Unit) response to CLF (Contactless Front-end).

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[in]handleThe handle of connected secure element
[in]respThe bytes array of response data
[in]resp_lenThe size of response bytes array
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_ILLEGAL_STATEIllegal state
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_manager_set_hce_event_cb()
nfc_manager_unset_hce_event_cb()
nfc_manager_initialize()

Disables card emulation mode.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Remarks:
Security level can be determined by the manufacturer usage.
If a security issue is occurred, contact with the manufacturer of the product.
If you want to know about security level in detail, See the GSMA specification.
(http://www.gsma.com/digitalcommerce/wp-content/uploads/2013/12/GSMA-NFC05-NFC-Handset-APIs-Requirement-Specification-version-4-1.pdf)
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_OPERATION_FAILEDOperation failed
NFC_ERROR_PERMISSION_DENIEDSecurity Restricted by SMACK
NFC_ERROR_SECURITY_RESTRICTEDSecurity Restricted
NFC_ERROR_DEVICE_BUSYDevice is too busy to handle your request
NFC_ERROR_OUT_OF_MEMORYOut of memory
See also:
nfc_se_enable_card_emulation()
nfc_manager_initialize()

Enables card emulation mode.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Remarks:
Security level can be determined by the manufacturer usage.
If a security issue is occurred, contact with the manufacturer of the product.
If you want to know about security level in detail, See the GSMA specification.
(http://www.gsma.com/digitalcommerce/wp-content/uploads/2013/12/GSMA-NFC05-NFC-Handset-APIs-Requirement-Specification-version-4-1.pdf)
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_OPERATION_FAILEDOperation failed
NFC_ERROR_PERMISSION_DENIEDSecurity Restricted by SMACK
NFC_ERROR_SECURITY_RESTRICTEDSecurity Restricted
NFC_ERROR_DEVICE_BUSYDevice is too busy to handle your request
NFC_ERROR_OUT_OF_MEMORYOut of memory
See also:
nfc_se_disable_card_emulation()
nfc_manager_initialize()
int nfc_se_foreach_registered_aids ( nfc_se_type_e  se_type,
nfc_card_emulation_category_type_e  category,
nfc_se_registered_aid_cb  callback,
void *  user_data 
)

Retrieves all registered AID.

You can retrieve aid only you registered. If you try to retrieves the aid what you are not registered, then the function return error.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[in]se_typeThe type of Secure Element
[in]categoryThe category
[in]callbackThe callback function to invoke
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_ILLEGAL_STATEIllegal state
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_manager_initialize()

Gets the current card emulation mode.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[out]typeThe current card emulation mode type
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_OPERATION_FAILEDOperation failed
NFC_ERROR_PERMISSION_DENIEDSecurity Restricted by SMACK
NFC_ERROR_DEVICE_BUSYDevice is too busy to handle your request
NFC_ERROR_OUT_OF_MEMORYOut of memory
See also:
nfc_se_enable_card_emulation()
nfc_se_disable_card_emulation()
nfc_manager_initialize()
int nfc_se_is_activated_handler_for_aid ( nfc_se_type_e  se_type,
const char *  aid,
bool *  is_activated_handler 
)

Gets the state whether an application to call this function is currently the activated handler for specific AID.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[in]se_typeThe type of Secure Element
[in]aidApplication Id, specified in ISO/IEC 7816-4
[out]is_activated_handlertrue when application is currently the activated handler, otherwise false
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_ILLEGAL_STATEIllegal state
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_manager_initialize()
int nfc_se_is_activated_handler_for_category ( nfc_se_type_e  se_type,
nfc_card_emulation_category_type_e  category,
bool *  is_activated_handler 
)

Gets the state whether an application to call this function is currently the activated handler for category.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[in]se_typeThe type of Secure Element
[in]categoryThe category
[out]is_activated_handlertrue when application is currently the activated handler, otherwise false
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_ILLEGAL_STATEIllegal state
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_manager_initialize()
int nfc_se_register_aid ( nfc_se_type_e  se_type,
nfc_card_emulation_category_type_e  category,
const char *  aid 
)

Registers a AID for a specific category.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[in]se_typeThe type of Secure Element
[in]categoryThe category
[in]aidApplication Id, specified in ISO/IEC 7816-4
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_ILLEGAL_STATEIllegal state
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_AID_ALREADY_REGISTEREDAID is already registered
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_se_unregister_aid()
nfc_manager_initialize()
int nfc_se_set_default_route ( nfc_se_type_e  powered_on_status,
nfc_se_type_e  powered_off_status,
nfc_se_type_e  low_battery_status 
)

Sets the default route for each device status.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[in]powered_on_statusThe type of default Secure Element when device is powered on
[in]powered_off_statusThe type of default Secure Element when device is powered off
[in]low_battery_statusThe type of default Secure Element when battery is low
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_ILLEGAL_STATEIllegal state
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_manager_initialize()

Sets the application as a preferred handler.

This function is possible to call when your application is in the foreground.
We recommend that you call function when the app state is resume.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_OPERATION_FAILEDOperation failed
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_manager_initialize()
nfc_se_unset_preferred_handler()
int nfc_se_unregister_aid ( nfc_se_type_e  se_type,
nfc_card_emulation_category_type_e  category,
const char *  aid 
)

Unregisters a previously registered AID for the specified category.

You can unregister aid only you registered. If you try to release the aid what you are not registered, then the function return error.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Parameters:
[in]se_typeThe type of Secure Element
[in]categoryThe category
[in]aidApplication Id, specified in ISO/IEC 7816-4
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_ILLEGAL_STATEIllegal state
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_se_register_aid()
nfc_manager_initialize()

Unsets the application as a preferred handler.

We recommend that you call API when the app state is pause.
If you do not call the API, Tizen will initialize the preferred app properly.
But there may be a problem with the performance, we recommend your explicit call.

Since :
3.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc.cardemulation
Returns:
0 on success, otherwise a negative error value.
Return values:
NFC_ERROR_NONESuccessful
NFC_ERROR_NOT_SUPPORTEDNot supported NFC
NFC_ERROR_NOT_INITIALIZEDNot initialized NFC
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_OPERATION_FAILEDOperation failed
NFC_ERROR_PERMISSION_DENIEDPermission denied
See also:
nfc_manager_initialize()
nfc_se_set_preferred_handler()