Connection Handover messages and records

Connection Handover records and the corresponding messages are used to negotiate and activate an alternative communication carrier. The negotiated communication carrier can then be used to perform certain activities between the two devices, such as Bluetooth® pairing.

Connection Handover records 

The Connection Handover library provides functions for creating and encoding the following Connection Handover records:

Handover Request record
Handover Select record
Handover Mediation record
Handover Initiate record
Handover Carrier record
Local records:
- Alternative Carrier record
- Collision Resolution record

Connection Handover messages 

The Connection Handover message library provides functions for encoding the following messages:

Bluetooth LE OOB message
Handover Select message
Handover Request message
Handover Mediation message
Handover Initiate message

This library is used in the Bluetooth: NFC pairing sample.

The following code sample demonstrates how to create a Handover Select message with one Alternative Carrier record that has a reference to the Bluetooth LE OOB record:

static int tnep_initial_msg_encode(struct nfc_ndef_msg_desc *msg)
{
	int err;
	struct nfc_ndef_ch_msg_records ch_records;
	static struct nfc_ndef_le_oob_rec_payload_desc rec_payload;

	NFC_NDEF_LE_OOB_RECORD_DESC_DEF(oob_rec, '0', &rec_payload);
	NFC_NDEF_CH_AC_RECORD_DESC_DEF(oob_ac, NFC_AC_CPS_ACTIVE, 1, "0", 0);
	NFC_NDEF_CH_HS_RECORD_DESC_DEF(hs_rec, NFC_NDEF_CH_MSG_MAJOR_VER,
				       NFC_NDEF_CH_MSG_MINOR_VER, 1);

	memset(&rec_payload, 0, sizeof(rec_payload));

	rec_payload.addr = &oob_local.addr;
	rec_payload.le_sc_data = &oob_local.le_sc_data;
	rec_payload.tk_value = tk_value;
	rec_payload.local_name = bt_get_name();
	rec_payload.le_role = NFC_NDEF_LE_OOB_REC_LE_ROLE(
		NFC_NDEF_LE_OOB_REC_LE_ROLE_PERIPH_ONLY);
	rec_payload.appearance = NFC_NDEF_LE_OOB_REC_APPEARANCE(
		CONFIG_BT_DEVICE_APPEARANCE);
	rec_payload.flags = NFC_NDEF_LE_OOB_REC_FLAGS(BT_LE_AD_NO_BREDR);

	ch_records.ac = &NFC_NDEF_CH_AC_RECORD_DESC(oob_ac);
	ch_records.carrier = &NFC_NDEF_LE_OOB_RECORD_DESC(oob_rec);
	ch_records.cnt = 1;

	err =  nfc_ndef_ch_msg_hs_create(msg,
					 &NFC_NDEF_CH_RECORD_DESC(hs_rec),
					 &ch_records);
	if (err) {
		return err;
	}

	return nfc_tnep_initial_msg_encode(msg, NULL, 0);
}

API documentation 

Connection Handover records 

Header file: include/nfc/ndef/ch.h

Source file: subsys/nfc/ndef/ch.c

group nfc_ndef_ch

Generation of NFC NDEF Connection Handover records for NDEF messages.

Defines

NFC_NDEF_CH_REC_TYPE_LENGTH: Size of the type field of the Connection Handover records. Record types are defined in the file ch_rec.c.

NFC_NDEF_CH_AC_CPS_MASK: Mask of Carrier Power State bits in a first ac record byte.

NFC_NDEF_CH_RECORD_DESC_DEF(_name, _rec_type_field, _major_version, _minor_version, _max_records)

Macro for creating and initializing an NFC NDEF record descriptor for the Connection Handover.

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_ch_rec, which together constitute an instance of a Connection Handover record.

Use the macro NFC_NDEF_CH_RECORD_DESC to access the NDEF Connection Handover record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_rec_type_field – [in] The NFC Forum Well Known Type Connection Handover record type.
_major_version – [in] Major version number of the supported Connection Handover specification.
_minor_version – [in] Minor version number of the supported Connection Handover specification.
_max_records – [in] Maximum number of local records.

NFC_NDEF_CH_HS_RECORD_DESC_DEF(_name, _major_version, _minor_version, _max_records)

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

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_ch_rec, which together constitute an instance of a Handover Select record.

Use the macro NFC_NDEF_CH_RECORD_DESC to access the NDEF Handover Select record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_major_version – [in] Major version number of the supported Connection Handover specification.
_minor_version – [in] Minor version number of the supported Connection Handover specification.
_max_records – [in] Maximum number of local records struct (ac records plus optional err record).

NFC_NDEF_CH_HR_RECORD_DESC_DEF(_name, _major_version, _minor_version, _max_records)

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

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_ch_rec, which together constitute an instance of a Handover Request record.

Use the macro NFC_NDEF_CH_RECORD_DESC to access the NDEF Handover Request record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_major_version – [in] Major version number of the supported Connection Handover specification.
_minor_version – [in] Minor version number of the supported Connection Handover specification.
_max_records – [in] Maximum number of local records (cr record plus ac records).

NFC_NDEF_CH_HM_RECORD_DESC_DEF(_name, _major_version, _minor_version, _max_records)

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

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_ch_rec, which together constitute an instance of a Handover Mediation record.

Use the macro NFC_NDEF_CH_RECORD_DESC to access the NDEF Handover Mediation record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_major_version – [in] Major version number of the supported Connection Handover specification.
_minor_version – [in] Minor version number of the supported Connection Handover specification.
_max_records – [in] Maximum number of local records (ac records).

NFC_NDEF_CH_HI_RECORD_DESC_DEF(_name, _major_version, _minor_version, _max_records)

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

This macro creates and initializes an instance of type nfc_ndef_record_desc.

Use the macro NFC_NDEF_CH_RECORD_DESC to access the NDEF Handover Initiate record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_major_version – [in] Major version number of the supported Connection Handover specification.
_minor_version – [in] Minor version number of the supported Connection Handover specification.
_max_records – [in] Maximum number of local records (ac records).

NFC_NDEF_CH_RECORD_DESC(_name): Macro for accessing the NFC NDEF Handover Select record descriptor instance that was created with NFC_NDEF_CH_HS_RECORD_DESC_DEF.

NFC_NDEF_CH_HC_RECORD_DESC_DEF(_name, _payload_id, _payload_id_length, _payload_desc)

Macro for creating and initializing an NFC NDEF record descriptor for the Handover Carrier record.

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_ch_rec, which together constitute an instance of a Connection Handover record.

Use the macro NFC_NDEF_CH_HC_RECORD_DESC to access the NDEF Connection Handover record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_payload_id – [in] ID of the payload.
_payload_id_length – [in] Length of the payload.
_payload_desc – [in] Description of the payload.

NFC_NDEF_CH_HC_RECORD_DESC(_name): Macro for accessing the NFC NDEF Handover Carrier record descriptor instance that was created with NFC_NDEF_CH_HC_GENERIC_RECORD_DESC_DEF.

NFC_NDEF_CH_AC_RECORD_DESC_DEF(_name, _cps, _carr_data_ref_len, _carr_data_ref, _max_aux_data_ref_cnt)

Macro for creating and initializing an NFC NDEF record descriptor for an Alternative Carrier record.

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_ch_ac_rec, which together constitute an instance of an Alternative Carrier record.

Use the macro NFC_NDEF_CH_AC_RECORD_DESC to access the NDEF Alternative Carrier record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_cps – [in] Carrier Power State value.
_carr_data_ref_len – [in] Length of the Carrier Data Reference field.
_carr_data_ref – [in] Pointer to the Carrier Data Reference field.
_max_aux_data_ref_cnt – [in] Maximum number of Auxiliary Data Reference fields.

NFC_NDEF_CH_AC_RECORD_DESC(_name): Macro for accessing the NFC NDEF Alternative Carrier record descriptor instance that was created with NFC_NDEF_AC_RECORD_DESC_DEF.

NFC_NDEF_CH_CR_RECORD_DESC_DEF(_name, _random_number)

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

This macro creates and initializes an instance of type nfc_ndef_record_desc and an instance of type nfc_ndef_ch_cr_rec, which together constitute an instance of an Collision Resolution record.

Use the macro NFC_NDEF_CR_RECORD_DESC to access the NDEF Collision Resolution record descriptor instance.

Parameters:

_name – [in] Name of the created record descriptor instance.
_random_number – [in] Generated random number required to resolve a collision.

NFC_NDEF_CR_RECORD_DESC(_name): Macro for accessing the NFC NDEF Alternative Carrier record descriptor instance that was created with NFC_NDEF_CH_CR_RECORD_DESC_DEF.

Enums

enum nfc_ndef_ch_ac_rec_cps

Carrier Power State.

Possible Carrier Power State field values in an Alternative Carrier record.

Values:

enumerator NFC_AC_CPS_INACTIVE: Alternative Carrier inactive.

enumerator NFC_AC_CPS_ACTIVE: Alternative Carrier active.

enumerator NFC_AC_CPS_ACTIVATING: Alternative Carrier activating.

enumerator NFC_AC_CPS_UNKNOWN: Alternative Carrier power status unknown.

Functions

int nfc_ndef_ch_rec_payload_encode(const struct nfc_ndef_ch_rec *ch_rec, uint8_t *buf, uint32_t *len)

Constructor for an NFC Connection Handover generic record payload.

Parameters:

ch_rec – [in] Pointer to the Connection Handover record description.
buf – [out] Pointer to the payload destination. If NULL, function will calculate the expected size of the Handover Connection record payload.
len – [inout] 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.

void nfc_ndef_ch_rec_local_record_clear(struct nfc_ndef_record_desc *ch_rec)

Function for clearing local records in the NFC NDEF Connection Handover records.

This function clears local records of the Connection Handover records.

Parameters:

ch_rec – [inout] Pointer to the Connection Handover record descriptor.

Return values:

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

int nfc_ndef_ch_rec_local_record_add(struct nfc_ndef_record_desc *ch_rec, const struct nfc_ndef_record_desc *local_rec)

Function for adding a local record to an NFC NDEF Handover Select record.

Parameters:

ch_rec – [inout] Pointer to a Connection Handover record.
local_rec – [in] Pointer to a local record to add.

Return values:

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

int nfc_ndef_ch_hc_rec_payload_encode(const struct nfc_ndef_ch_hc_rec *hc_rec, uint8_t *buf, uint32_t *len)

Constructor for an NFC Connection Handover Carrier Record payload.

Parameters:

hc_rec – [in] Pointer to the Connection Handover Carrier record description.
buf – [out] Pointer to the payload destination. If NULL, function will calculate the expected size of the Handover Connection Carrier Record payload.
len – [inout] 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.

int nfc_ndef_ch_ac_rec_payload_encode(const struct nfc_ndef_ch_ac_rec *nfc_rec_ac, uint8_t *buf, uint32_t *len)

Constructor for an NFC NDEF Alternative Carrier record payload.

Parameters:

nfc_rec_ac – [in] Pointer to the Alternative Carrier record description.
buf – [in] Pointer to the payload destination. If NULL, function will calculate the expected size of the Alternative Carrier record payload.
len – [inout] 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.

void nfc_ndef_ch_ac_rec_auxiliary_data_ref_clear(struct nfc_ndef_record_desc *ac_rec)

Function for clearing an Auxiliary Data Reference in an NFC NDEF Alternative Carrier record.

This function clears the Auxiliary Data References from the Alternative Carrier record.

Parameters:

ac_rec – [inout] Pointer to the Alternative Carrier record descriptor.

int nfc_ndef_ch_ac_rec_auxiliary_data_ref_add(struct nfc_ndef_record_desc *ac_rec, const uint8_t *aux_data, uint8_t aux_length)

Function for adding an Auxiliary Data Reference to an NFC NDEF Alternative Carrier record.

Parameters:

ac_rec – [inout] Pointer to an ac record.
aux_data – [in] Pointer to the Auxiliary Data Reference data buffer.
aux_length – [in] Length of the Auxiliary Data Reference data.

Return values:

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

int nfc_ndef_ch_cr_rec_payload_encode(const struct nfc_ndef_ch_cr_rec *nfc_rec_cr, uint8_t *buf, uint32_t *len)

Constructor for an NFC NDEF Collision Resolution record payload.

Parameters:

nfc_rec_cr – [in] Pointer to the Collision Resolution record description.
buf – [out] Pointer to the payload destination. If NULL, function will calculate the expected size of the Collision Resolution record payload.
len – [inout] 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.

struct nfc_ndef_ch_hc_rec

#include <ch.h>

Handover Carrier record payload descriptor.

Public Members

enum nfc_ndef_record_tnf ctf

Carrier Type Format, it has the same semantics like TNF. Supported TNF:

NFC Forum Well Known Type
Media Type
Absolute URI
NFC Forum external type

uint8_t type_len: Carrier type field length.

const uint8_t *type: A unique identification of the alternative carrier. It shall follow the structure, encoding, and format implied by the value of the CTF field.

uint8_t data_len: Optional data length.

uint8_t *data: Optional information about alternative carrier. It length can be calculated using following formula: (NDEF Record Payload length - carrier type length) - 2

struct nfc_ndef_ch_hc_rec.[anonymous] carrier: Carrier description.

struct nfc_ndef_ch_ac_rec_ref

#include <ch.h>

Carrier Data Reference and Auxiliary Data Reference descriptor.

Public Members

uint8_t length: Length of the data field.

const uint8_t *data: Pointer to the Data Reference characters. Not relevant if length is 0.

struct nfc_ndef_ch_ac_rec

#include <ch.h>

Alternative Carrier record payload descriptor.

Public Members

enum nfc_ndef_ch_ac_rec_cps cps: Carrier Power State value.

struct nfc_ndef_ch_ac_rec_ref carrier_data_ref: Carrier Data Reference.

const uint8_t max_aux_data_ref_cnt: Maximum number of Auxiliary Data Reference fields.

uint8_t aux_data_ref_cnt: Number of Auxiliary Data Reference fields.

struct nfc_ndef_ch_ac_rec_ref *aux_data_ref: Pointer to the Auxiliary Data Reference fields.

struct nfc_ndef_ch_cr_rec

#include <ch.h>

Collision Resolution record payload descriptor.

Public Members

uint16_t random: Randomly generated number.

struct nfc_ndef_ch_rec

#include <ch.h>

Handover Select record payload descriptor.

Public Members

uint8_t major_version: Major version number of the supported Connection Handover specification.

uint8_t minor_version: Minor version number of the supported Connection Handover specification.

struct nfc_ndef_msg_desc *local_records: Pointer to a message encapsulating local records.

Connection Handover messages 

Header file: include/nfc/ndef/ch_msg.h

Source file: subsys/nfc/ndef/ch_msg.c

group nfc_ndef_ch_msg

Generation of The Connection Handover NDEF messages.

Defines

NFC_NDEF_CH_MSG_MAJOR_VER

NFC_NDEF_CH_MSG_MINOR_VER

Functions

int nfc_ndef_ch_msg_le_oob_encode(const struct nfc_ndef_le_oob_rec_payload_desc *oob, uint8_t *buf, size_t *len)

Encode an NFC NDEF LE OOB message.

This function encodes an NFC NDEF message into a buffer.

Parameters:

oob – [in] Pointer to the LE OOB Record payload descriptor.
buf – [out] Pointer to the buffer for the message.
len – [inout] Size of the available memory for the message as input. Size of the generated message as output.

Return values:

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

int nfc_ndef_ch_msg_hs_create(struct nfc_ndef_msg_desc *msg, struct nfc_ndef_record_desc *hs_rec, const struct nfc_ndef_ch_msg_records *records)

Create an NFC NDEF Handover Select message.

This function create an NFC NDEF message. It create a nested NDEF message with the Alternative Carrier Records. Next the Records with the Carrier data are added into the main Connection Hanover Select message. Number of the Alternative Carrier Records must be equal to the number of the Carrier Records.

Parameters:

msg – [inout] Pointer to NDEF message. This message is initialized with Connection Handover Record. The message must be able to keep at least count of the Alternative Carrier Records + 1 records.
hs_rec – [out] Pointer to the Handover Select Record.
records – [in] Pointer to structure which contains the Alternative Carrier Records and the Carrier Records

Return values:

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

int nfc_ndef_ch_msg_hr_create(struct nfc_ndef_msg_desc *msg, struct nfc_ndef_record_desc *hr_rec, const struct nfc_ndef_record_desc *cr_rec, const struct nfc_ndef_ch_msg_records *records)

Encode an NFC NDEF Handover Request message.

This function create an NFC NDEF message. It create a nested NDEF message with the Alternative Carrier Records. Next the Records with the Carrier data are added into the main Connection Hanover Request message. Number of the Alternative Carrier Records must be equal to the number of the Carrier Records.

Parameters:

msg – [inout] Pointer to NDEF message. This message is initialized with Connection Handover Record. The message must be able to keep at least count of the Alternative Carrier Records + 1 records.
hr_rec – [out] Pointer to the Handover Request Record.
cr_rec – [in] Pointer to the Collision Resolution Record.
records – [in] Pointer to structure which contains the Alternative Carrier Records and the Carrier Records

Return values:

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

int nfc_ndef_ch_msg_hm_create(struct nfc_ndef_msg_desc *msg, struct nfc_ndef_record_desc *hm_rec, const struct nfc_ndef_ch_msg_records *records)

Create an NFC NDEF Handover Mediation message.

This function creates an NFC NDEF message. It create a nested NDEF message with the Alternative Carrier Records. Next the Records with the Carrier data are added into the main Connection Hanover Mediation message. Number of the Alternative Carrier Records must be equal to the number of the Carrier Records.

Parameters:

msg – [inout] Pointer to NDEF message. This message is initialized with Connection Handover Record. The message must be able to keep at least count of the Alternative Carrier Records + 1 records.
hm_rec – [out] Pointer to the Handover Mediation Record.
records – [in] Pointer to structure which contains the Alternative Carrier Records and the Carrier Records

Return values:

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

int nfc_ndef_ch_msg_hi_create(struct nfc_ndef_msg_desc *msg, struct nfc_ndef_record_desc *hi_rec, const struct nfc_ndef_ch_msg_records *records)

Create an NFC NDEF Handover Initiate message.

This function creates an NFC NDEF message. It create a nested NDEF message with the Alternative Carrier Records. Next the Records with the Carrier data are added into the main Connection Hanover Initiate message. Number of the Alternative Carrier Records must be equal to the number of the Carrier Records.

Parameters:

msg – [inout] Pointer to NDEF message. This message is initialized with Connection Handover Record. The message must be able to keep at least count of the Alternative Carrier Records + 1 records.
hi_rec – [out] Pointer to the Handover Initiate Record.
records – [in] Pointer to structure which contains the Alternative Carrier Records and the Carrier Records

Return values:

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

struct nfc_ndef_ch_msg_records

#include <ch_msg.h>

NFC NDEF Connection Handover message structure. This structure contains all needed records needed to create the Connection Handover message. It can contain one or more the Alternative Carrier Records and the Carrier Records.

Public Members

const struct nfc_ndef_record_desc *ac: Array of the Alternative Carrier Records.

const struct nfc_ndef_record_desc *carrier: Array of the Carrier Records.

size_t cnt: Count of the Alternative Carrier Records and the Carrier Records.

Connection Handover messages and records

Connection Handover records

Connection Handover messages

API documentation

Connection Handover records

Connection Handover messages

Connection Handover records 

Connection Handover messages 

API documentation 

Connection Handover records 

Connection Handover messages 