Tizen Native API  6.5

Message API provides functions to create NDEF message and insert/remove records in NDEF message.

Required Header

#include <nfc.h>

Overview

The NDEF message api provides functions to make NDEF message

  • create / destroy NDEF message
  • insert / remove NDEF record
  • get NDEF record from NDEF message

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_message_create (nfc_ndef_message_h *ndef_message)
 Creates NDEF message handle.
int nfc_ndef_message_create_from_rawdata (nfc_ndef_message_h *ndef_message, const unsigned char *rawdata, unsigned int rawdata_size)
 Creates NDEF message handle from raw serial bytes.
int nfc_ndef_message_destroy (nfc_ndef_message_h ndef_message)
 Destroys NDEF message handle.
int nfc_ndef_message_get_record_count (nfc_ndef_message_h ndef_message, int *count)
 Gets the number of record in NDEF message.
int nfc_ndef_message_get_rawdata (nfc_ndef_message_h ndef_message, unsigned char **rawdata, unsigned int *rawdata_size)
 Gets serial bytes array of NDEF message.
int nfc_ndef_message_append_record (nfc_ndef_message_h ndef_message, nfc_ndef_record_h record)
 Appends a record into NDEF message.
int nfc_ndef_message_insert_record (nfc_ndef_message_h ndef_message, int index, nfc_ndef_record_h record)
 Inserts a record at index into NDEF message.
int nfc_ndef_message_remove_record (nfc_ndef_message_h ndef_message, int index)
 Removes the record that indicated by index number and this deleted record will be freed.
int nfc_ndef_message_get_record (nfc_ndef_message_h ndef_message, int index, nfc_ndef_record_h *record)
 Gets record by index.

Typedefs

typedef struct _ndef_message_s * nfc_ndef_message_h
 The handle to the NDEF message.

Typedef Documentation

typedef struct _ndef_message_s* nfc_ndef_message_h

The handle to the NDEF message.

Since :
2.3

Function Documentation

Appends a record into NDEF message.

Since :
2.3
Remarks:
Appended record is handled by frameworks. The record is released by frameworks when message is released.
Parameters:
[in]ndef_messageThe handle to NDEF message
[in]recordThe record that will be appended into NDEF message
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_message_insert_record()
nfc_ndef_message_remove_record()
nfc_manager_initialize()

Creates NDEF message handle.

Since :
2.3
Remarks:
The ndef_message should be released using nfc_ndef_message_destroy().
Parameters:
[out]ndef_messageA handle to NDEF message
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_message_create_from_rawdata()
nfc_ndef_message_destroy()
nfc_manager_initialize()
int nfc_ndef_message_create_from_rawdata ( nfc_ndef_message_h ndef_message,
const unsigned char *  rawdata,
unsigned int  rawdata_size 
)

Creates NDEF message handle from raw serial bytes.

Since :
2.3
Remarks:
The ndef_message should be released using nfc_ndef_message_destroy().
It consumes the bytes array until get the ME (Message End) flag*. It returns error if the bytes array does not have ME flag.
*The ME flag is a 1-bit field that when set indicates the end of an NDEF message.
Parameters:
[out]ndef_messageThe handle to NDEF message
[in]rawdataThe NDEF message in form of bytes array
[in]rawdata_sizeThe size of 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_INVALID_PARAMETERInvalid parameter
NFC_ERROR_OUT_OF_MEMORYOut of memory
See also:
nfc_ndef_message_create()
nfc_ndef_message_destroy()
nfc_ndef_message_get_rawdata()
nfc_manager_initialize()

Destroys NDEF message handle.

Since :
2.3
Remarks:
This function will free all these memory including record handles.
Parameters:
[in]ndef_messageThe handle to NDEF message to destroy
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_message_create()
nfc_ndef_message_create_from_rawdata()
nfc_manager_initialize()
int nfc_ndef_message_get_rawdata ( nfc_ndef_message_h  ndef_message,
unsigned char **  rawdata,
unsigned int *  rawdata_size 
)

Gets serial bytes array of NDEF message.

Since :
2.3
Remarks:
It gets copy of the bytes array from NDEF message. rawdata must be released with free() by you.
Parameters:
[in]ndef_messageThe handle to NDEF message
[out]rawdataThe bytes array of bytes array
[out]rawdata_sizeThe size of bytes array 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
NFC_ERROR_OUT_OF_MEMORYOut of memory
NFC_ERROR_INVALID_NDEF_MESSAGEInvalid NDEF message
See also:
nfc_ndef_message_create_from_rawdata()
nfc_manager_initialize()
int nfc_ndef_message_get_record ( nfc_ndef_message_h  ndef_message,
int  index,
nfc_ndef_record_h record 
)

Gets record by index.

Since :
2.3
Remarks:
The record should not be released.
The record is managed by the platform and will be released when MTP service stops.
This function just return the pointer of record. if you change the record value it directly affects the NDEF message
Parameters:
[in]ndef_messageThe handle to NDEF message
[in]indexThe index of record ( starts from 0 )
[out]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_manager_initialize()
int nfc_ndef_message_get_record_count ( nfc_ndef_message_h  ndef_message,
int *  count 
)

Gets the number of record in NDEF message.

Since :
2.3
Parameters:
[in]ndef_messageThe handle to NDEF message
[out]countThe number of 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_manager_initialize()
int nfc_ndef_message_insert_record ( nfc_ndef_message_h  ndef_message,
int  index,
nfc_ndef_record_h  record 
)

Inserts a record at index into NDEF message.

Since :
2.3
Remarks:
Appended record is handled by frameworks. The record is released by frameworks when message is released.
The index value should not bigger than nfc_ndef_message_get_record_count()
Parameters:
[in]ndef_messageThe handle to NDEF message
[in]indexThe index of record ( starts from 0 )
[in]recordThe record that will be appended into NDEF message
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_NDEF_MESSAGEInvalid NDEF message
See also:
nfc_ndef_message_append_record()
nfc_ndef_message_remove_record()
nfc_manager_initialize()
int nfc_ndef_message_remove_record ( nfc_ndef_message_h  ndef_message,
int  index 
)

Removes the record that indicated by index number and this deleted record will be freed.

Since :
2.3
Parameters:
[in]ndef_messageThe handle to NDEF message
[in]indexThe index of record ( starts from 0 )
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_NDEF_MESSAGEInvalid NDEF message
See also:
nfc_ndef_message_append_record()
nfc_ndef_message_insert_record()
nfc_manager_initialize()