Tizen Native API
7.0
|
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:
- http://tizen.org/feature/network.nfc
- http://tizen.org/feature/network.nfc.card_emulation
- http://tizen.org/feature/network.nfc.card_emulation.hce
- http://tizen.org/feature/network.secure_element.uicc
- http://tizen.org/feature/network.secure_element.ese
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] handle The handle of connected secure element [in] event The HCE event type [in] apdu The bytes array of apdu command data [in] apdu_len The size of apdu command bytes array [in] user_data The user data passed from nfc_manager_set_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_type The type of Secure Element [in] aid Application Id, specified in ISO/IEC 7816-4 [in] read_only true
an aid is on read only mode, otherwisefalse
[in] user_data The user data passed from the foreach function
- See also:
- nfc_se_foreach_registered_aids()
Enumeration Type Documentation
enum nfc_hce_event_type_e |
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] handle The handle of connected secure element [in] resp The bytes array of response data [in] resp_len The size of response bytes array
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_ILLEGAL_STATE Illegal state NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_OUT_OF_MEMORY Out of memory NFC_ERROR_PERMISSION_DENIED Permission denied
int nfc_se_disable_card_emulation | ( | void | ) |
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.
(https://www.gsma.com/newsroom/wp-content/uploads/TS.26-v15.0.pdf)
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_OPERATION_FAILED Operation failed NFC_ERROR_PERMISSION_DENIED Security Restricted by SMACK NFC_ERROR_SECURITY_RESTRICTED Security Restricted NFC_ERROR_DEVICE_BUSY Device is too busy to handle your request NFC_ERROR_OUT_OF_MEMORY Out of memory
int nfc_se_enable_card_emulation | ( | void | ) |
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.
(https://www.gsma.com/newsroom/wp-content/uploads/TS.26-v15.0.pdf)
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_OPERATION_FAILED Operation failed NFC_ERROR_PERMISSION_DENIED Security Restricted by SMACK NFC_ERROR_SECURITY_RESTRICTED Security Restricted NFC_ERROR_DEVICE_BUSY Device is too busy to handle your request NFC_ERROR_OUT_OF_MEMORY Out of memory
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_type The type of Secure Element [in] category The category [in] callback The callback function to invoke [in] user_data The user data to be passed to the callback function
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_ILLEGAL_STATE Illegal state NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_OUT_OF_MEMORY Out of memory NFC_ERROR_PERMISSION_DENIED Permission 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] type The current card emulation mode type
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_OPERATION_FAILED Operation failed NFC_ERROR_PERMISSION_DENIED Security Restricted by SMACK NFC_ERROR_DEVICE_BUSY Device is too busy to handle your request NFC_ERROR_OUT_OF_MEMORY Out of memory
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_type The type of Secure Element [in] aid Application Id, specified in ISO/IEC 7816-4 [out] is_activated_handler true
when application is currently the activated handler, otherwisefalse
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_ILLEGAL_STATE Illegal state NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_OUT_OF_MEMORY Out of memory NFC_ERROR_PERMISSION_DENIED Permission 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_type The type of Secure Element [in] category The category [out] is_activated_handler true
when application is currently the activated handler, otherwisefalse
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_ILLEGAL_STATE Illegal state NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_OUT_OF_MEMORY Out of memory NFC_ERROR_PERMISSION_DENIED Permission 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_type The type of Secure Element [in] category The category [in] aid Application Id, specified in ISO/IEC 7816-4
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_ILLEGAL_STATE Illegal state NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_OUT_OF_MEMORY Out of memory NFC_ERROR_AID_ALREADY_REGISTERED AID is already registered NFC_ERROR_PERMISSION_DENIED Permission denied
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_status The type of default Secure Element when device is powered on [in] powered_off_status The type of default Secure Element when device is powered off [in] low_battery_status The type of default Secure Element when battery is low
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_ILLEGAL_STATE Illegal state NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_OUT_OF_MEMORY Out of memory NFC_ERROR_PERMISSION_DENIED Permission denied
- See also:
- nfc_manager_initialize()
int nfc_se_set_preferred_handler | ( | void | ) |
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_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_OPERATION_FAILED Operation failed NFC_ERROR_PERMISSION_DENIED Permission denied
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_type The type of Secure Element [in] category The category [in] aid Application Id, specified in ISO/IEC 7816-4
- Returns:
- 0 on success, otherwise a negative error value.
- Return values:
-
NFC_ERROR_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_ILLEGAL_STATE Illegal state NFC_ERROR_INVALID_PARAMETER Invalid parameter NFC_ERROR_OUT_OF_MEMORY Out of memory NFC_ERROR_PERMISSION_DENIED Permission denied
int nfc_se_unset_preferred_handler | ( | void | ) |
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_NONE Successful NFC_ERROR_NOT_SUPPORTED Not supported NFC NFC_ERROR_NOT_INITIALIZED Not initialized NFC NFC_ERROR_NOT_ACTIVATED NFC is not activated NFC_ERROR_OPERATION_FAILED Operation failed NFC_ERROR_PERMISSION_DENIED Permission denied