Tizen Native API  5.5

Record API provides an NDEF record.

Required Header

#include <nfc.h>

Overview

The NDEF record api provides functions to make NDEF record

  • create / destroy NDEF record
  • set / get elements from NDEF record

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_ndef_record_create (nfc_ndef_record_h *record, nfc_record_tnf_e tnf, const unsigned char *type, int type_size, const unsigned char *id, int id_size, const unsigned char *payload, unsigned int payload_size)
 Creates a record with given parameter value.
int nfc_ndef_record_create_text (nfc_ndef_record_h *record, const char *text, const char *lang_code, nfc_encode_type_e encode)
 Creates a record with text type payload.
int nfc_ndef_record_create_uri (nfc_ndef_record_h *record, const char *uri)
 Creates a record with URI type payload.
int nfc_ndef_record_create_mime (nfc_ndef_record_h *record, const char *mime_type, const unsigned char *data, unsigned int data_size)
 Creates a record with MIME type payload.
int nfc_ndef_record_destroy (nfc_ndef_record_h record)
 Destroys the record handle.
int nfc_ndef_record_set_id (nfc_ndef_record_h record, unsigned char *id, int id_size)
 Sets record ID.
int nfc_ndef_record_get_id (nfc_ndef_record_h record, unsigned char **id, int *size)
 Gets record ID.
int nfc_ndef_record_get_payload (nfc_ndef_record_h record, unsigned char **payload, unsigned int *size)
 Gets record payload.
int nfc_ndef_record_get_type (nfc_ndef_record_h record, unsigned char **type, int *size)
 Gets record type.
int nfc_ndef_record_get_tnf (nfc_ndef_record_h record, nfc_record_tnf_e *tnf)
 Gets record TNF (Type Name Format) value.
int nfc_ndef_record_get_text (nfc_ndef_record_h record, char **text)
 Gets text from text record.
int nfc_ndef_record_get_langcode (nfc_ndef_record_h record, char **lang_code)
 Gets language code from text record.
int nfc_ndef_record_get_encode_type (nfc_ndef_record_h record, nfc_encode_type_e *encode)
 Gets encoding type from text record.
int nfc_ndef_record_get_uri (nfc_ndef_record_h record, char **uri)
 Gets URI from URI record.
int nfc_ndef_record_get_mime_type (nfc_ndef_record_h record, char **mime_type)
 Gets MIME type from MIME type record.

Typedefs

typedef struct _ndef_record_s * nfc_ndef_record_h
 The handle to the NDEF record.

Typedef Documentation

typedef struct _ndef_record_s* nfc_ndef_record_h

The handle to the NDEF record.

Since :
2.3.1

Enumeration Type Documentation

Enumerations for NFC encode types.

Since :
2.3.1
Enumerator:
NFC_ENCODE_UTF_8 

UTF-8

NFC_ENCODE_UTF_16 

UTF-16

Enumerations for record TNF (Type Name Format).

It is indicate format of type field

Since :
2.3.1
Enumerator:
NFC_RECORD_TNF_EMPTY 

Empty

NFC_RECORD_TNF_WELL_KNOWN 

RTD(Record Type Definition) type format [NFC RTD]

NFC_RECORD_TNF_MIME_MEDIA 

MIME Media types in RFC 2046 [RFC 2046]

NFC_RECORD_TNF_URI 

Absolute URI as defined in RFC 3986 [RFC 3986]

NFC_RECORD_TNF_EXTERNAL_RTD 

NFC Forum external type [NFC RTD]

NFC_RECORD_TNF_UNKNOWN 

Unknown
The payload type is unknown

NFC_RECORD_TNF_UNCHANGED 

It means the payload is an intermediate or final chunk of a chunked NDEF Record


Function Documentation

int nfc_ndef_record_create ( nfc_ndef_record_h record,
nfc_record_tnf_e  tnf,
const unsigned char *  type,
int  type_size,
const unsigned char *  id,
int  id_size,
const unsigned char *  payload,
unsigned int  payload_size 
)

Creates a record with given parameter value.

Since :
2.3.1
Remarks:
The record should be released using nfc_ndef_record_destroy().
The record should be released using nfc_ndef_record_destroy().
Every data buffer is deeply copied.
Every data is a byte array(binary data).
Parameters:
[out]recordA handle to record
[in]tnfThe type name format
[in]typeThe specified type name
[in]type_sizeThe byte size of type
[in]idThe record ID
[in]id_sizeThe byte size of ID
[in]payloadThe payload of this record
[in]payload_sizeThe byte size of payload
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_ndef_record_create_text()
nfc_ndef_record_create_uri()
nfc_ndef_record_create_mime()
nfc_ndef_record_destroy()
nfc_manager_initialize()
int nfc_ndef_record_create_mime ( nfc_ndef_record_h record,
const char *  mime_type,
const unsigned char *  data,
unsigned int  data_size 
)

Creates a record with MIME type payload.

Since :
2.3.1
Remarks:
The record should be released using nfc_ndef_record_destroy().
The data buffer will be deep copied.
The data are bytes array(binary data).
The mime_type string will deep copied.
The record is created in this format
  • TNF : NFC_RECORD_TNF_MIME_MEDIA
  • type : MIME type
  • payload : data
    Defined in Record Type Definition Technical Specifications.
Parameters:
[out]recordA handle to record
[in]mime_typeThe MIME type [RFC 2046] (ex. text/plain, image/jpeg ) This value is stored in type field
[in]dataThe pointer of data
[in]data_sizeThe size of data
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_ndef_record_create()
nfc_ndef_record_create_uri()
nfc_ndef_record_create_text()
nfc_ndef_record_destroy()
nfc_ndef_record_get_mime_type()
nfc_manager_initialize()
int nfc_ndef_record_create_text ( nfc_ndef_record_h record,
const char *  text,
const char *  lang_code,
nfc_encode_type_e  encode 
)

Creates a record with text type payload.

Since :
2.3.1
Remarks:
The record should be released using nfc_ndef_record_destroy().
This function does not encode the text. text will be assumed as that it is already encoded with encode type.
The text buffer will be deeply copied.
The record is created in this format
  • TNF : NFC_RECORD_TNF_WELL_KNOWN
  • type : "T"
  • payload : encode and header information + language code + text
    Defined in Record Type Definition Technical Specifications.
Parameters:
[out]recordA handle to record
[in]textThe encoded text
[in]lang_codeThe language code string value followed by IANA[RFC 3066] (ex: en-US, ko-KR)
[in]encodeThe encoding type
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_ndef_record_create()
nfc_ndef_record_create_uri()
nfc_ndef_record_create_mime()
nfc_ndef_record_destroy()
nfc_ndef_record_get_text()
nfc_ndef_record_get_langcode()
nfc_ndef_record_get_encode_type()
nfc_manager_initialize()
int nfc_ndef_record_create_uri ( nfc_ndef_record_h record,
const char *  uri 
)

Creates a record with URI type payload.

Since :
2.3.1
Remarks:
The record should be released using nfc_ndef_record_destroy().
The record should be released using free().
The URI string will be deep copied.
The record is created in this format
  • TNF : NFC_RECORD_TNF_WELL_KNOWN
  • type : "U"
  • payload : protocol scheme + URI
    Defined in Record Type Definition Technical Specifications.
Parameters:
[out]recordA handle to record
[in]uriThe URI string that will be stored in the payload
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_ndef_record_create()
nfc_ndef_record_create_text()
nfc_ndef_record_create_mime()
nfc_ndef_record_destroy()
nfc_ndef_record_get_uri()
nfc_manager_initialize()

Destroys the record handle.

Since :
2.3.1
Parameters:
[in]recordThe handle to record
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_ndef_record_create()
nfc_ndef_record_create_text()
nfc_ndef_record_create_uri()
nfc_ndef_record_create_mime()
nfc_manager_initialize()

Gets encoding type from text record.

Since :
2.3.1
Remarks:
This function is valid only for text type record.
The text type record 's tnf is NFC_RECORD_TNF_WELL_KNOWN and it's type is "T"
Parameters:
[in]recordThe handle to record
[out]encodeencode type nfc_encode_type_e
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_INVALID_RECORD_TYPEInvalid record type
See also:
nfc_ndef_record_create_text()
nfc_manager_initialize()
int nfc_ndef_record_get_id ( nfc_ndef_record_h  record,
unsigned char **  id,
int *  size 
)

Gets record ID.

Since :
2.3.1
Remarks:
It may return NULL pointer if the ID is not exist
This function gives you the pointer of ID that is contained by record
Do not free the ID. It will be released when record is destroyed by nfc_ndef_record_destroy().
Parameters:
[in]recordThe handle to record
[out]idThe record ID ( do not free )
[out]sizeThe size of ID in bytes
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_ndef_record_set_id()
nfc_manager_initialize()
int nfc_ndef_record_get_langcode ( nfc_ndef_record_h  record,
char **  lang_code 
)

Gets language code from text record.

Since :
2.3.1
Remarks:
This function returns newly allocated string, this value must be deallocated by caller.
This function is valid only for text type record.
The text type record 's tnf is NFC_RECORD_TNF_WELL_KNOWN and it's type is "T"
Parameters:
[in]recordThe handle to record
[out]lang_codelang code ( should be freed by caller )
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_INVALID_RECORD_TYPEInvalid record type
See also:
nfc_ndef_record_create_text()
nfc_manager_initialize()
int nfc_ndef_record_get_mime_type ( nfc_ndef_record_h  record,
char **  mime_type 
)

Gets MIME type from MIME type record.

Since :
2.3.1
Remarks:
The function returns newly allocated string, this value must be deallocated by caller.
This function is valid only for MIME type record.
The URI type record 's tnf is NFC_RECORD_TNF_MIME_MEDIA.
Parameters:
[in]recordThe handle to record
[out]mime_typeThe MIME type in record payload ( should be freed by caller )
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_INVALID_RECORD_TYPEInvalid record type
See also:
nfc_ndef_record_create_mime()
nfc_manager_initialize()
int nfc_ndef_record_get_payload ( nfc_ndef_record_h  record,
unsigned char **  payload,
unsigned int *  size 
)

Gets record payload.

Since :
2.3.1
Remarks:
This function gives you the pointer of payload that is contained by record
Do not free the payload. it will be freed when record is destroyed by nfc_ndef_record_destroy().
Parameters:
[in]recordThe handle to record
[out]payloadThe payload ( do not free this pointer )
[out]sizethe size of payload in byte
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_ndef_record_get_text ( nfc_ndef_record_h  record,
char **  text 
)

Gets text from text record.

Since :
2.3.1
Remarks:
This function returns newly allocated string, this value must be deallocated by caller.
This function is valid only for text type record.
The text type record 's tnf is NFC_RECORD_TNF_WELL_KNOWN and it's type is "T"
Parameters:
[in]recordThe handle to record
[out]textThe text in record payload ( should be freed by caller )
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_INVALID_RECORD_TYPEInvalid record type
See also:
nfc_ndef_record_create_text()
nfc_manager_initialize()

Gets record TNF (Type Name Format) value.

Since :
2.3.1
Parameters:
[in]recordThe handle to record
[out]tnfThe TNF (Type Name Format) value
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_ndef_record_get_type ( nfc_ndef_record_h  record,
unsigned char **  type,
int *  size 
)

Gets record type.

Since :
2.3.1
Remarks:
This function gives you the pointer of type that is contained by record.
Do not free the type. it will be freed when the record is freed.
Parameters:
[in]recordThe handle to record
[out]typeThe record type ( do not free this pointer )
[out]sizeThe size of type in byte
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_ndef_record_get_uri ( nfc_ndef_record_h  record,
char **  uri 
)

Gets URI from URI record.

Since :
2.3.1
Remarks:
The function returns newly allocated string, this value must be deallocated by caller.
This function is valid only for URI type record. The URI type record 's tnf is NFC_RECORD_TNF_WELL_KNOWN and it's type is "U"
Parameters:
[in]recordThe handle to record
[out]uriThe URI in record payload ( should be freed by caller )
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_INVALID_RECORD_TYPEInvalid record type
See also:
nfc_ndef_record_create_uri()
nfc_manager_initialize()
int nfc_ndef_record_set_id ( nfc_ndef_record_h  record,
unsigned char *  id,
int  id_size 
)

Sets record ID.

Since :
2.3.1
Remarks:
The ID buffer are deep copied.
Parameters:
[in]recordThe handle to record
[in]idThe record ID
[in]id_sizeThe size of ID in bytes
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_ndef_record_get_id()
nfc_manager_initialize()

Variable Documentation

const unsigned char NFC_RECORD_ALTERNATIVE_CARRIER_TYPE[2]

RTD (Record type definition) Type - Alternative Carrier type.

Since :
2.3.1
const unsigned char NFC_RECORD_HANDOVER_CARRIER_TYPE[2]

RTD (Record type definition) Type - Handover Carrier type.

Since :
2.3.1
const unsigned char NFC_RECORD_HANDOVER_REQUEST_TYPE[2]

RTD (Record type definition) Type - Handover Request type.

Since :
2.3.1
const unsigned char NFC_RECORD_HANDOVER_SELECT_TYPE[2]

RTD (Record type definition) Type - Handover Select type.

Since :
2.3.1
const unsigned char NFC_RECORD_SMART_POSTER_TYPE[2]

RTD (Record type definition) Type - Smart Poster type.

Since :
2.3.1
const unsigned char NFC_RECORD_TEXT_TYPE[1]

RTD (Record type definition) Type - Text type.

Since :
2.3.1
const unsigned char NFC_RECORD_URI_TYPE[1]

RTD (Record type definition) Type - URI type.

Since :
2.3.1