Tizen Native API  5.0

TAG API provide functions for read/write operation on NDEF and also provide low level API of Mifare.

Required Header

#include <nfc.h>

Overview

The TAG api provides functions to read or write NDEF and low level transaction APIs with Non NDEF tag.

  • read NDEF from NDEF compatible TAG
  • write NDEF to NDEF compatible TAG
  • check whether tag has NDEF or not
  • format NFC forum tag to be compatible with NDEF
  • read specific attributes from tag by ISO14443
  • low level api of MIFARE classic and MIFARE ultra light

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_tag_get_type (nfc_tag_h tag, nfc_tag_type_e *type)
 Gets the type of NFC tag.
int nfc_tag_is_support_ndef (nfc_tag_h tag, bool *is_supported)
 Checks whether the given NFC tag supports NDEF messages.
int nfc_tag_get_maximum_ndef_size (nfc_tag_h tag, unsigned int *maximum_ndef_bytes_size)
 Gets the maximum NDEF message size that can be stored in NFC tag.
int nfc_tag_get_ndef_size (nfc_tag_h tag, unsigned int *ndef_bytes_size)
 Gets size of NDEF message that stored in the tag.
int nfc_tag_foreach_information (nfc_tag_h tag, nfc_tag_information_cb callback, void *user_data)
 Retrieves all tag information.
int nfc_tag_transceive (nfc_tag_h tag, unsigned char *buffer, int buffer_size, nfc_tag_transceive_completed_cb callback, void *user_data)
 Transceives the data of the raw format card.
int nfc_tag_read_ndef (nfc_tag_h tag, nfc_tag_read_completed_cb callback, void *user_data)
 Reads NDEF formatted data from NFC tag.
int nfc_tag_write_ndef (nfc_tag_h tag, nfc_ndef_message_h msg, nfc_tag_write_completed_cb callback, void *user_data)
 Writes NDEF formatted data.
int nfc_tag_format_ndef (nfc_tag_h tag, unsigned char *key, int key_size, nfc_tag_format_completed_cb callback, void *user_data)
 Formats the detected tag that can store NDEF message.

Typedefs

typedef struct
_net_nfc_target_info_s * 
nfc_tag_h
 The handle to the NFC tag.
typedef bool(* nfc_tag_information_cb )(const char *key, const unsigned char *value, int value_size, void *user_data)
 Called once for each tag information.
typedef void(* nfc_tag_transceive_completed_cb )(nfc_error_e result, unsigned char *buffer, int buffer_size, void *user_data)
 Called after nfc_tag_transceive() has completed.
typedef void(* nfc_tag_write_completed_cb )(nfc_error_e result, void *user_data)
 Called after the nfc_tag_write_ndef() has completed.
typedef void(* nfc_tag_read_completed_cb )(nfc_error_e result, nfc_ndef_message_h message, void *user_data)
 Called after the nfc_tag_read_ndef() has completed.
typedef void(* nfc_tag_format_completed_cb )(nfc_error_e result, void *user_data)
 Called after the nfc_tag_format_ndef() has completed.

Typedef Documentation

typedef void(* nfc_tag_format_completed_cb)(nfc_error_e result, void *user_data)

Called after the nfc_tag_format_ndef() has completed.

Since :
2.3.1
Parameters:
[in]resultThe result of function call
[in]user_dataThe user data passed from nfc_tag_format_ndef()
See also:
nfc_tag_format_ndef()
typedef struct _net_nfc_target_info_s* nfc_tag_h

The handle to the NFC tag.

Since :
2.3.1
typedef bool(* nfc_tag_information_cb)(const char *key, const unsigned char *value, int value_size, void *user_data)

Called once for each tag information.

Since :
2.3.1
Remarks:
key and value will be automatically destroyed when the callback function returns. (Do not release key and value.)
Parameters:
[in]keyThe key of information
[in]valueThe value of information
[in]value_sizeThe data size in bytes
[in]user_dataThe user data passed from the foreach function
Returns:
true to continue with the next iteration of the loop,
false to break out of the loop.
Precondition:
nfc_tag_foreach_information() invokes this callback.
See also:
nfc_tag_foreach_information()
typedef void(* nfc_tag_read_completed_cb)(nfc_error_e result, nfc_ndef_message_h message, void *user_data)

Called after the nfc_tag_read_ndef() has completed.

Since :
2.3.1
Remarks:
message will be automatically destroyed when the callback function returns. (Do not release message.)
Parameters:
[in]resultThe result of function call
[in]messageThe NDEF message
[in]user_dataThe user data passed from nfc_tag_read_ndef()
See also:
nfc_tag_read_ndef()
typedef void(* nfc_tag_transceive_completed_cb)(nfc_error_e result, unsigned char *buffer, int buffer_size, void *user_data)

Called after nfc_tag_transceive() has completed.

Since :
2.3.1
Remarks:
buffer will be automatically destroyed when the callback function returns. (Do not release buffer.)
Parameters:
[in]resultThe result of function call
[in]bufferThe result data
[in]buffer_sizeThe size of buffer in bytes
[in]user_dataThe user data passed from nfc_tag_transceive()
See also:
nfc_tag_transceive()
typedef void(* nfc_tag_write_completed_cb)(nfc_error_e result, void *user_data)

Called after the nfc_tag_write_ndef() has completed.

Since :
2.3.1
Parameters:
[in]resultThe result of function call
[in]user_dataThe user data passed from nfc_manager_initialize()
See also:
nfc_tag_write_ndef()

Enumeration Type Documentation

Enumerations for NFC tag types.

Since :
2.3.1
Enumerator:
NFC_UNKNOWN_TARGET 

Unknown target

NFC_GENERIC_PICC 

GENERIC PICC

NFC_ISO14443_A_PICC 

ISO14443_A PICC

NFC_ISO14443_4A_PICC 

ISO14443_4A PICC

NFC_ISO14443_3A_PICC 

ISO14443_3A PICC

NFC_MIFARE_MINI_PICC 

MIFARE_MINI_PICC

NFC_MIFARE_1K_PICC 

MIFARE_1K_PICC

NFC_MIFARE_4K_PICC 

MIFARE_4K_PICC

NFC_MIFARE_ULTRA_PICC 

MIFARE_ULTRA_PICC

NFC_MIFARE_DESFIRE_PICC 

MIFARE_DESFIRE_PICC

NFC_ISO14443_B_PICC 

ISO14443_B PICC

NFC_ISO14443_4B_PICC 

ISO14443_4B PICC

NFC_ISO14443_BPRIME_PICC 

ISO14443_BPRIME PICC

NFC_FELICA_PICC 

FELICA PICC

NFC_JEWEL_PICC 

JEWEL PICC

NFC_ISO15693_PICC 

ISO15693 PICC

NFC_BARCODE_128_PICC 

BARCODE_128 PICC

NFC_BARCODE_256_PICC 

BARCODE_256 PICC

NFC_NFCIP1_TARGET 

NFCIP1_TARGET

NFC_NFCIP1_INITIATOR 

NFCIP1_INITIATOR


Function Documentation

int nfc_tag_foreach_information ( nfc_tag_h  tag,
nfc_tag_information_cb  callback,
void *  user_data 
)

Retrieves all tag information.

Since :
2.3.1
Parameters:
[in]tagThe handle to NFC tag
[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_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
See also:
nfc_manager_initialize()
int nfc_tag_format_ndef ( nfc_tag_h  tag,
unsigned char *  key,
int  key_size,
nfc_tag_format_completed_cb  callback,
void *  user_data 
)

Formats the detected tag that can store NDEF message.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc

Some tags are required authentication. If the detected target doesn't need authentication, key can be NULL.

Parameters:
[in]tagThe handle to NFC tag
[in]keyThe key value that may need to format the tag
[in]key_sizeThe size of key in byte
[in]callbackThe callback function to invoke after this function has completed
It can be null if notification is not required
[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_OUT_OF_MEMORYOut of memory
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_DEVICE_BUSYDevice is too busy to handle your request
NFC_ERROR_TIMED_OUTTimeout is reached while communicating with tag
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_NOT_NDEF_FORMATNot ndef format tag
NFC_ERROR_OPERATION_FAILEDOperation failed
Postcondition:
It invokes nfc_tag_format_completed_cb() when it has completed to format the NFC tag.
The Callback can receive error code when process is done.
See also:
nfc_tag_is_support_ndef()
nfc_manager_initialize()
int nfc_tag_get_maximum_ndef_size ( nfc_tag_h  tag,
unsigned int *  maximum_ndef_bytes_size 
)

Gets the maximum NDEF message size that can be stored in NFC tag.

Since :
2.3.1
Remarks:
This max size indicates the maximum size of NDEF message that can be stored in this detected tag.
Parameters:
[in]tagThe handle to NFC tag
[out]maximum_ndef_bytes_sizeThe maximum bytes size of NDEF message that can be stored in this detected tag.
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_INVALID_PARAMETERInvalid parameter
See also:
nfc_manager_initialize()
int nfc_tag_get_ndef_size ( nfc_tag_h  tag,
unsigned int *  ndef_bytes_size 
)

Gets size of NDEF message that stored in the tag.

Since :
2.3.1
Parameters:
[in]tagThe handle to NFC tag
[out]ndef_bytes_sizeThe NDEF message bytes size that stored in the tag
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_INVALID_PARAMETERInvalid parameter
See also:
nfc_manager_initialize()
int nfc_tag_get_type ( nfc_tag_h  tag,
nfc_tag_type_e type 
)

Gets the type of NFC tag.

Since :
2.3.1
Parameters:
[in]tagThe handle to NFC tag
[out]typeThe type of NFC tag
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_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OPERATION_FAILEDOperation failed
See also:
nfc_manager_initialize()
int nfc_tag_is_support_ndef ( nfc_tag_h  tag,
bool *  is_supported 
)

Checks whether the given NFC tag supports NDEF messages.

Since :
2.3.1
Parameters:
[in]tagThe handle to NFC tag
[out]is_supportedtrue when NFC tag supports NDEF messages, 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_INVALID_PARAMETERInvalid parameter
See also:
nfc_tag_read_ndef()
nfc_manager_initialize()
int nfc_tag_read_ndef ( nfc_tag_h  tag,
nfc_tag_read_completed_cb  callback,
void *  user_data 
)

Reads NDEF formatted data from NFC tag.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc
Parameters:
[in]tagThe handle to NFC tag
[in]callbackThe callback function to invoke after this function has completed
It can be null if notification is not required
[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_OUT_OF_MEMORYOut of memory
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_DEVICE_BUSYDevice is too busy to handle your request
NFC_ERROR_TIMED_OUTTimeout is reached while communicating with tag
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_NOT_NDEF_FORMATNot ndef format tag
NFC_ERROR_OPERATION_FAILEDOperation failed
Postcondition:
It invokes nfc_tag_read_completed_cb() when it has completed to read NDEF formatted data.
The Callback can receive error code when process is done.
See also:
nfc_tag_transceive()
nfc_tag_is_support_ndef()
nfc_tag_write_ndef()
nfc_manager_initialize()
int nfc_tag_transceive ( nfc_tag_h  tag,
unsigned char *  buffer,
int  buffer_size,
nfc_tag_transceive_completed_cb  callback,
void *  user_data 
)

Transceives the data of the raw format card.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc

This function is the only way to access the raw format card (not formated), each tag type requires own command to access tags.
This function provides the low level access of tag operation and you require the knowledge of each tag technology.

Parameters:
[in]tagThe handle to NFC tag
[in]bufferThe binary data for parameter or additional commands
[in]buffer_sizeThe size of buffer in bytes
[in]callbackThe callback function to invoke after this function has completed
It can be null if a notification is not required
[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_OUT_OF_MEMORYOut of memory
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_DEVICE_BUSYDevice is too busy to handle your request
NFC_ERROR_TIMED_OUTTimeout is reached while communicating with tag
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_OPERATION_FAILEDOperation failed
Postcondition:
It invokes nfc_tag_transceive_completed_cb() when it has completed to transceive data.
The Callback can receive error code when process is done.
See also:
nfc_tag_read_ndef()
nfc_tag_is_support_ndef()
nfc_manager_initialize()
int nfc_tag_write_ndef ( nfc_tag_h  tag,
nfc_ndef_message_h  msg,
nfc_tag_write_completed_cb  callback,
void *  user_data 
)

Writes NDEF formatted data.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/nfc
Parameters:
[in]tagThe handle to NFC tag
[in]msgThe message will be write to the tag
[in]callbackThe callback function to invoke after this function has completed
It can be null if notification is not required
[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_OUT_OF_MEMORYOut of memory
NFC_ERROR_INVALID_PARAMETERInvalid parameter
NFC_ERROR_DEVICE_BUSYDevice is too busy to handle your request
NFC_ERROR_TIMED_OUTTimeout is reached while communicating with tag
NFC_ERROR_NOT_ACTIVATEDNFC is not activated
NFC_ERROR_NOT_NDEF_FORMATNot ndef format tag
NFC_ERROR_OPERATION_FAILEDOperation failed
Postcondition:
It invokes nfc_tag_write_completed_cb() when it has completed to write NDEF data.
The Callback can receive error code when process is done.
See also:
nfc_tag_is_support_ndef()
nfc_tag_read_ndef()
nfc_manager_initialize()