nfc-ndef.h

Go to the documentation of this file.

/**********************************************************************/
/**
 * @file
 * @brief Utility functions to manipulate with NFC NDEF.
 *
 * @author SE, Jetro AS
 ***********************************************************************/

#include <stddef.h>
#include <stdbool.h>
#include <stdint.h>

#ifndef NFC_NDEF_H
#define NFC_NDEF_H

/**
 * \defgroup ndef NFC NDEF manipulation
 * \ingroup util
 * \{
 *
 * Utility functions to manipulate with NFC NDEF.
 */

#define NDEF_MB             (1 << 7) //!< NDEF message first byte: Message begin flag
#define NDEF_ME             (1 << 6) //!< NDEF message first byte: Message end flag
#define NDEF_CF             (1 << 5) //!< NDEF message first byte: Message chunk flag
#define NDEF_SR             (1 << 4) //!< NDEF message first byte: Short record flag: payload length is 1 byte (otherwise 4 bytes)
#define NDEF_IL             (1 << 3) //!< NDEF message first byte: ID length flag: ID is present if this flag is set
#define NDEF_TNF_EMPTY      0x00     //!< NDEF message first byte: Empty Type
#define NDEF_TNF_WELLKNOWN  0x01     //!< NDEF message first byte: Well-known Type
#define NDEF_TNF_MEDIA      0x02     //!< NDEF message first byte: Media Type
#define NDEF_TNF_URI        0x03     //!< NDEF message first byte: Absolute URI Type
#define NDEF_TNF_EXT        0x04     //!< NDEF message first byte: External Type
#define NDEF_TNF_UNKNOWN    0x05     //!< NDEF message first byte: Unknown Type
#define NDEF_TNF_UNCHANGED  0x06     //!< NDEF message first byte: Unchanged Type
#define NDEF_TNF_RESERVED   0x07     //!< NDEF message first byte: Reserved Type

/******************************************************************************
 *  NFC driver public types
 *****************************************************************************/

/**
 * @brief The callback is called on NDEF write attempt in card emulation mode
 * @param Nfc       NFC driver descriptor
 * @param Offset    Requested NDEF offset to write to
 * @param Data      Data to write
 * @param DataLen   Data Length
 * @return bool     true on success, false on error
 */
typedef bool nfc_ndef_changed_cb_t(const void* Nfc_p,
                                   uint8_t* Type, uint32_t TypeLen,
                                   uint8_t* Data, uint32_t DataLen);

/**
 * @brief Table element of interrupt handlers called on NDEF write attempt for
 *        supported NFC message types.
 */
struct nfc_ndef_changed_cb_table_t
{
  nfc_ndef_changed_cb_t* NdefChangedCb; //!< Callback to call on NDEF write attempt in card emulation mode
  const char* TypeName;                 //!< NFC message type name
};

/**
 * @brief Structure describes one parsed NDEF record. See standard NFC Data
 *        Exchange Format specification.
 */
struct ndef_record_t
{
  uint8_t MessageBegin:1; //!< Flag: Record is the beginning of the message
  uint8_t MessageEnd:1;   //!< Flag: Record is the end of the message
  uint8_t RecordType:3;   //!< Type Name Format Field (Well-known, External etc.)
  uint8_t* TypeName;      //!< Pointer to Type Name
  uint8_t TypeLen;        //!< Type Name length
  uint8_t* Id;            //!< Pointer to Record ID
  uint8_t IdLen;          //!< Record ID length
  uint8_t* Data;          //!< Pointer to Record Payload
  uint32_t DataLen;       //!< Record Payload length
};


/**
 * @brief Nullify NDEF messege output buffer.
 *
 * @param  NdefFile       Pointer to the NDEF message buffer.
 * @param  NdefFileSize   NDEF message buffer size.
 * @return bool           true on success, false on error
 */
bool NfcNdefResetBuffer(uint8_t* NdefFile, uint16_t NdefFileSize);

/**
 * @brief Get current NDEF messege length.
 *
 * @param [in]  NdefFile       Pointer to the NDEF message buffer.
 * @param [in]  NdefFileSize   NDEF message buffer size.
 * @param [out] DataLength     NDEF message length.
 * @return bool                true on success, false on error
 */
bool NfcNdefGetDataLength(uint8_t* NdefFile, uint16_t NdefFileSize,
                          uint16_t* DataLength);

/**
 * @brief Increase current NDEF messege length.
 * The function must be used when adding a record to the NDEF message with
 * external tool or manually (not NfcNdefAddRecord()).
 *
 * @param  NdefFile       Pointer to the NDEF message buffer.
 * @param  NdefFileSize   NDEF message buffer size.
 * @param  DataLength     Additional length added to the  NDEF message.
 * @return bool           true on success, false on error
 */
bool NfcNdefAddDataLength(uint8_t* NdefFile, uint16_t NdefFileSize,
                          uint16_t DataLength);

/**
 * @brief Add a new record to the NDEF messege.
 *
 * @param  NdefFile       Pointer to the NDEF message buffer.
 * @param  NdefFileSize   NDEF message buffer size.
 * @param  NdefRec        Pointer to a structure holding the NDEF record to add.
 * @return bool           true on success, false on error
 */
bool NfcNdefAddRecord(uint8_t* NdefFile, uint16_t NdefFileSize,
                      struct ndef_record_t* NdefRec);

/**
 * @brief Close the NDEF messege.
 * The function must be used after NDEF message altering either with
 * NfcNdefAddRecord() or NfcNdefAddDataLength() before supplying to NFC library
 * to ensure all the record headers are valid.
 *
 * @param  NdefFile       Pointer to the NDEF message buffer.
 * @param  NdefFileSize   NDEF message buffer size.
 * @return bool           true on success, false on error
 */
bool NfcNdefFinalize(uint8_t* NdefFile, uint16_t NdefFileSize);


/**
 * @brief Get the pointer to the first record inside an NDEF message.
 *
 * @param NdefFile  [in]  Pointer to the NDEF message buffer.
 * @param NewRecord [out] Pointer to the first record pointer, NULL on error.
 */
void NfcNdefGetFirstRecord(uint8_t* NdefFile, uint8_t** NewRecord);

/**
 * @brief Get the pointer to the next record inside an NDEF message.
 *
 * @param NdefFile   [in] Pointer to the NDEF message buffer.
 * @param PrevRecord [in] The previus record pointer.
 * @param NewRecord [out] Pointer to the next record pointer, NULL on error.
 */
void NfcNdefGetRecord(uint8_t* NdefFile, uint8_t* PrevRecord, uint8_t** NewRecord);

/**
 * @brief Parse raw NDEF record into the structure.
 *
 * @param Record  [in]   Pointer to the NDEF record buffer (Typically a pointer
 *                        to NDEF message buffer content obtained with
 *                        NfcNdefGetFirstRecord() / NfcNdefGetRecord().
 * @param NdefRec [out]  Pointer to a descriptor of NDEF record to add,
 *                       NULL on error.
 */
void NfcNdefRecordParse(uint8_t* Record, struct ndef_record_t* NdefRec);

/** \} */

#endif /* NFC_NDEF_H */