Use the Custom NDEF messages and Custom NDEF records modules to create standardized messages and records that are not covered by other modules, or to create your own custom messages.

To generate a custom NDEF message, start by creating the records that make up the message. Next, generate an empty message of the required length and add the records to the message. Finally, encode and create the message.

You can choose the tag's platform with NFC_NDEF_MSG_TAG_TYPE in sdk_config.h. In case of Type 2 Tag platform, an NDEF message is encoded according to the NDEF message and record format. In case of Type 4 Tag an additional field is added in front of an NDEF message. See NDEF file format for more details.

You can also encapsulate a message as payload for a record. For example, a Handover Request message contains several Alternative Carrier records. These records themselves are full messages that contain information about alternative carriers that can be used for further communication.

Creating a record descriptor

You can provide the payload of the record in binary format or in a different format that is then converted into binary format. The content of the record is defined in a record descriptor.

Use the NFC_NDEF_RECORD_BIN_DATA_DEF macro for binary data or the NFC_NDEF_GENERIC_RECORD_DESC_DEF macro for other data to create the record descriptor. You must provide header information for the record (for example, ID and type) and the payload data to the macro. For generic data that is not in binary format, you must also provide a payload constructor. This constructor converts the payload data to the needed format. For binary data, the module provides this constructor.

The following code example shows how to generate a record descriptor:

ret_code_t error_code;
uint32_t length;
 
/// Declare record descriptor by macro - create and initialize an instance of 
/// nfc_ndef_record_desc_t.
NFC_NDEF_GENERIC_RECORD_DESC_DEF( record,
 3,
 id_string,
 sizeof(id_string),
 type_string,
 sizeof(type_string),
 payload_constructor, // implementation provided by user
 &payload_constructor_data // structure depends on user implementation
 );
// If required, get the record size to length variable.
error_code = nfc_ndef_record_encode( &NFC_NDEF_GENERIC_RECORD_DESC_DEF(record),
 NDEF_MIDDLE_RECORD,
 NULL,
 &length);

Creating a message

A message consists of one or more records. Accordingly, a message descriptor (that holds the content of the message) contains an array of pointers to record descriptors.

Use the NFC_NDEF_MSG_DEF macro to create the message descriptor and the array of pointers. When creating the message descriptor, you specify how many records the message will contain, but you do not specify the actual records yet.

To add the records, use the nfc_ndef_msg_record_add function.

After adding all records, call nfc_ndef_msg_encode to actually create the message from the message descriptor. nfc_ndef_msg_encode internally calls nfc_ndef_record_encode to encode each record. The NDEF records are always encoded in long format. If no ID field is specified, a record without ID field is generated.

The following code example shows how to create two messages:

ret_code_t error_code;
uint8_t buffer_for_message[512];
uint8_t buffer_for_message_2[128];
uint32_t length;
// Declare message descriptor by macro - create and initialize an instance of 
// nfc_ndef_msg_desc_t and an array of pointers to nfc_ndef_record_desc_t.
// The declared message can contain up to 2 records.
NFC_NDEF_MSG_DEF(my_message, 2);
// Add record_1 and record_2 to the message.
// record_1 and record_2 are record descriptors as created in the previous
// code example.
error_code = nfc_ndef_msg_record_add( &NFC_NDEF_MSG(my_message), record_1);
error_code = nfc_ndef_msg_record_add( &NFC_NDEF_MSG(my_message), record_2);
// Get the message size to the length variable.
error_code_t = nfc_ndef_msg_encode( &NFC_NDEF_MSG(my_message),
 NULL,
 &length);
 
// Encode the message to buffer_for_message.
ASSERT(length <= 512); // make sure the message fits into the buffer
error_code_t = nfc_ndef_msg_encode( &NFC_NDEF_MSG(my_message),
 buffer_for_message,
 &length);
// Clear the message description. 
nfc_ndef_msg_clear( &NFC_NDEF_MSG(my_message));
// Add record_3 to the message.
// record_3 is a record descriptors as created in the previous code example.
error_code = nfc_ndef_msg_record_add( &NFC_NDEF_MSG(my_message), record_3);
// Encode another message to buffer_for_message_2.
length = 128; // amount of memory available for message
error_code_t = nfc_ndef_msg_encode( &NFC_NDEF_MSG(my_message),
 buffer_for_message_2,
 &length);

Encapsulating a message

To encapsulate a message in a record so that it can be added to another message, use the NFC_NDEF_NESTED_NDEF_MSG_RECORD_DEF macro to create the record descriptor. This record descriptor uses nfc_ndef_msg_encode as payload constructor. You can then add this record descriptor to a message like any other record descriptor.

The following code example shows how to encapsulate a message as payload for a record:

// nested_message_desc is a message descriptor
// declare a record descriptor with an NDEF message nested in payload
// create and initialize instance of nfc_ndef_record_desc_t
NFC_NDEF_NESTED_NDEF_MSG_RECORD_DEF( compound_record,
 3,
 sizeof(id_string),
 id_string,
 type_string,
 sizeof(type_string),
 &nested_message_desc );
 
// add compound record to a message like any other record 
error_code = nfc_ndef_msg_record_add( &NFC_NDEF_MSG(my_message), &NFC_NDEF_NESTED_NDEF_MSG_RECORD(compound_record));