Text records

Text records contain descriptive text and can be added to any type of message. This kind of record can be used in a message together with other records to provide extra information. The Text Records module provides functions for creating and encoding text records.

Text records contain a payload (the actual text string) and a language identifier. Note that a message can contain only one text record per language code, so you cannot add two different text records with language code “en” to the same message, for example.

The following code example shows how to generate a raw text message that contains a text record.

First, generate the text record. In this example, the record contains the text “Hello World!” and the language code “en”:

static const uint8_t en_payload[] = {
     'H', 'e', 'l', 'l', 'o', ' ', 'W', 'o', 'r', 'l', 'd', '!'
};
static const uint8_t en_code[] = {'e', 'n'};

int err;

/* Create NFC NDEF text record description in English */
NFC_NDEF_TEXT_RECORD_DESC_DEF(nfc_en_text_rec,
                              UTF_8,
                              en_code,
                              sizeof(en_code),
                              en_payload,
                              sizeof(en_payload));

Next, create an empty message descriptor. At this time, you specify how many records the message will contain, but you do not specify the actual records yet:

NFC_NDEF_MSG_DEF(nfc_text_msg, MAX_REC_COUNT);

Add the record that you created to the message:

err = nfc_ndef_msg_record_add(&NFC_NDEF_MSG(nfc_text_msg),
                           &NFC_NDEF_TEXT_RECORD_DESC(nfc_en_text_rec));
if (err < 0) {
        printk("Cannot add first record!\n");
        return err;
}

Finally, encode the message:

err = nfc_ndef_msg_encode(&NFC_NDEF_MSG(nfc_text_msg),
                                      buffer,
                                      len);
if (err < 0) {
     printk("Cannot encode message!\n");
     return err;
}

API documentation

Header file: include/nfc/ndef/text_rec.h
Source file: subsys/nfc/ndef/text_rec.c
group nfc_text_rec

Generation of NFC NDEF Text record descriptions.

Defines

NFC_NDEF_TEXT_REC_TYPE_LENGTH

Size of the type field of the Text record, defined in the file text_rec.c. It is used in the NFC_NDEF_TEXT_RECORD_DESC_DEF macro.

NFC_NDEF_TEXT_RECORD_DESC_DEF(name, utf_arg, lang_code_arg, lang_code_len_arg, data_arg, data_len_arg)

Macro for creating and initializing an NFC NDEF record descriptor for a Text record.

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_text_rec_payload, which together constitute an instance of a Text record.

Use the macro NFC_NDEF_TEXT_RECORD_DESC to access the NDEF Text record descriptor instance.

Parameters
  • name – Name of the created record descriptor instance.

  • utf_arg – Unicode Transformation Format.

  • lang_code_arg – Pointer to the IANA language code.

  • lang_code_len_arg – Length of the IANA language code.

  • data_arg – Pointer to the user text.

  • data_len_arg – Length of the user text.

NFC_NDEF_TEXT_RECORD_DESC(name)

Macro for accessing the NFC NDEF Text record descriptor instance that was created with NFC_NDEF_TEXT_RECORD_DESC_DEF.

Enums

enum nfc_ndef_text_rec_utf

Type of the Unicode Transformation Format.

Values to specify the type of UTF for an NFC NDEF Text record.

Values:

enumerator UTF_8

Unicode Transformation Format 8.

enumerator UTF_16

Unicode Transformation Format 16.

Functions

int nfc_ndef_text_rec_payload_encode(struct nfc_ndef_text_rec_payload *nfc_rec_text_payload_desc, uint8_t *buff, uint32_t *len)

Constructor for an NFC NDEF Text record payload.

Parameters
  • nfc_rec_text_payload_desc – Pointer to the Text record description.

  • buff – Pointer to the payload destination. If NULL, function will calculate the expected size of the Text record payload.

  • len – Size of the available memory to write as input. Size of the generated record payload as output.

Return values

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

Variables

const uint8_t nfc_ndef_text_rec_type_field[]

External reference to the type field of the Text record, defined in the file text_rec.c. It is used in the NFC_NDEF_TEXT_RECORD_DESC_DEF macro.

struct nfc_ndef_text_rec_payload
#include <text_rec.h>

Text record payload descriptor.

Public Members

enum nfc_ndef_text_rec_utf utf

Type of the Unicode Transformation Format.

uint8_t const *lang_code

Pointer to the IANA language code.

uint8_t lang_code_len

Length of the IANA language code.

uint8_t const *data

Pointer to the user text.

uint32_t data_len

Length of the user text.