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)
	Enable card emulation mode.
int	nfc_se_disable_card_emulation (void)
	Disable card emulation mode.
int	nfc_se_get_card_emulation_mode (nfc_se_card_emulation_mode_type_e *type)
	Get the current card emulation mode.
int	nfc_hce_send_apdu_response (nfc_se_h handle, unsigned char *resp, unsigned int resp_len)
	Send 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)
	Set 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 api 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 api 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:: 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()

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

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, otherwise `false`
[in]	user_data	The user data passed from the foreach function

See also:: nfc_se_foreach_registered_aids()

Enumeration Type Documentation

enum nfc_card_emulation_category_type_e

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

enum nfc_hce_event_type_e

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
	)

Send 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

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_set_hce_event_cb(); nfc_manager_unset_hce_event_cb(); nfc_manager_initialize()

int nfc_se_disable_card_emulation ( void )

Disable 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_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_INVALID_PARAMETER	Invalid parameter
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

See also:: nfc_se_enable_card_emulation(); nfc_manager_initialize()

int nfc_se_enable_card_emulation ( void )

Enable 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_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_INVALID_PARAMETER	Invalid parameter
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

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

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

See also:: nfc_manager_initialize()

int nfc_se_get_card_emulation_mode ( nfc_se_card_emulation_mode_type_e * type )

Get 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_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

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 api 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, otherwise `false`

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 api 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, otherwise `false`

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

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

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
	)

Set 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

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.

Since :: 3.0

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

Privilege Level:: public

Privilege:: http://tizen.org/privilege/nfc.cardemulation

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

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

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_se_register_aid(); nfc_manager_initialize()

int nfc_se_unset_preferred_handler ( void )

Unsets the application as a preferred handler.

Since :: 3.0

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.

Privilege Level:: public

Privilege:: http://tizen.org/privilege/nfc.cardemulation

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

See also:: nfc_manager_initialize(); nfc_se_set_preferred_handler()

Required Header

Overview

Related Features

Functions

Typedefs

Typedef Documentation

Enumeration Type Documentation

Function Documentation