bt_conn_auth_cb Struct Reference

Authenticated pairing callback structure. More...

#include <conn.h>

Data Fields
enum bt_security_err(*	pairing_accept )(struct bt_conn *conn, const struct bt_conn_pairing_feat *const feat)
	Query to proceed incoming pairing or not.
void(*	passkey_display )(struct bt_conn *conn, unsigned int passkey)
	Display a passkey to the user.
void(*	passkey_entry )(struct bt_conn *conn)
	Request the user to enter a passkey.
void(*	passkey_confirm )(struct bt_conn *conn, unsigned int passkey)
	Request the user to confirm a passkey.
void(*	oob_data_request )(struct bt_conn *conn, struct bt_conn_oob_info *info)
	Request the user to provide Out of Band (OOB) data.
void(*	cancel )(struct bt_conn *conn)
	Cancel the ongoing user request.
void(*	pairing_confirm )(struct bt_conn *conn)
	Request confirmation for an incoming pairing.
void(*	pincode_entry )(struct bt_conn *conn, bool highsec)
	Request the user to enter a passkey.

Detailed Description

Authenticated pairing callback structure.

Field Documentation

cancel

void(* bt_conn_auth_cb::cancel) (struct bt_conn *conn)

Cancel the ongoing user request.

This callback will be called to notify the application that it should cancel any previous user request (passkey display, entry or confirmation).

This may be set to NULL, but must always be provided whenever the passkey_display, passkey_entry passkey_confirm or pairing_confirm callback has been provided.

Parameters

conn	Connection where pairing is currently active.

oob_data_request

void(* bt_conn_auth_cb::oob_data_request) (struct bt_conn *conn, struct bt_conn_oob_info *info)

Request the user to provide Out of Band (OOB) data.

When called the user is expected to provide OOB data. The required data are indicated by the information structure.

For LE Secure Connections OOB pairing, the user should provide local OOB data, remote OOB data or both depending on their availability. Their value should be given to the stack using the bt_le_oob_set_sc_data() API.

This callback must be set to non-NULL in order to support OOB pairing.

Parameters

conn	Connection where pairing is currently active.
info	OOB pairing information.

pairing_accept

enum bt_security_err(* bt_conn_auth_cb::pairing_accept) (struct bt_conn *conn, const struct bt_conn_pairing_feat *const feat)

Query to proceed incoming pairing or not.

On any incoming pairing req/rsp this callback will be called for the application to decide whether to allow for the pairing to continue.

The pairing info received from the peer is passed to assist making the decision.

As this callback is synchronous the application should return a response value immediately. Otherwise it may affect the timing during pairing. Hence, this information should not be conveyed to the user to take action.

The remaining callbacks are not affected by this, but do notice that other callbacks can be called during the pairing. Eg. if pairing_confirm is registered both will be called for Just-Works pairings.

This callback may be unregistered in which case pairing continues as if the Kconfig flag was not set.

For BR/EDR Secure Simple Pairing (SSP), this callback is called when receiving the BT_HCI_EVT_IO_CAPA_REQ hci event.

Parameters

conn	Connection where pairing is initiated.
feat	Pairing req/resp info.

pairing_confirm

void(* bt_conn_auth_cb::pairing_confirm) (struct bt_conn *conn)

Request confirmation for an incoming pairing.

This callback will be called to confirm an incoming pairing request where none of the other user callbacks is applicable.

If the user decides to accept the pairing the bt_conn_auth_pairing_confirm() API should be called. If the user decides to reject the pairing the bt_conn_auth_cancel() API should be called.

This callback may be set to NULL, which means that the local device lacks the ability to confirm a pairing request. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a pairing request.

Parameters

conn	Connection where pairing is currently active.

passkey_confirm

void(* bt_conn_auth_cb::passkey_confirm) (struct bt_conn *conn, unsigned int passkey)

Request the user to confirm a passkey.

When called the user is expected to confirm that the given passkey is also shown on the peer device.. The passkey will be in the range of 0 - 999999, and should be zero-padded to always be six digits (e.g. 37 would be shown as 000037).

Once the user has confirmed the passkey to match, the bt_conn_auth_passkey_confirm() API should be called. If the user concluded that the passkey doesn't match the bt_conn_auth_cancel() API should be called.

This callback may be set to NULL, which means that the local device lacks the ability to confirm a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to confirm a passkey.

Parameters

conn	Connection where pairing is currently active.
passkey	Passkey to be confirmed.

passkey_display

void(* bt_conn_auth_cb::passkey_display) (struct bt_conn *conn, unsigned int passkey)

Display a passkey to the user.

When called the application is expected to display the given passkey to the user, with the expectation that the passkey will then be entered on the peer device. The passkey will be in the range of 0 - 999999, and is expected to be padded with zeroes so that six digits are always shown. E.g. the value 37 should be shown as 000037.

This callback may be set to NULL, which means that the local device lacks the ability do display a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop displaying the passkey.

Parameters

conn	Connection where pairing is currently active.
passkey	Passkey to show to the user.

passkey_entry

void(* bt_conn_auth_cb::passkey_entry) (struct bt_conn *conn)

Request the user to enter a passkey.

When called the user is expected to enter a passkey. The passkey must be in the range of 0 - 999999, and should be expected to be zero-padded, as that's how the peer device will typically be showing it (e.g. 37 would be shown as 000037).

Once the user has entered the passkey its value should be given to the stack using the bt_conn_auth_passkey_entry() API.

This callback may be set to NULL, which means that the local device lacks the ability to enter a passkey. If set to non-NULL the cancel callback must also be provided, since this is the only way the application can find out that it should stop requesting the user to enter a passkey.

Parameters

conn	Connection where pairing is currently active.

pincode_entry

void(* bt_conn_auth_cb::pincode_entry) (struct bt_conn *conn, bool highsec)

Request the user to enter a passkey.

This callback will be called for a BR/EDR (Bluetooth Classic) connection where pairing is being performed. Once called the user is expected to enter a PIN code with a length between 1 and 16 digits. If the highsec parameter is set to true the PIN code must be 16 digits long.

Once entered, the PIN code should be given to the stack using the bt_conn_auth_pincode_entry() API.

This callback may be set to NULL, however in that case pairing over BR/EDR will not be possible. If provided, the cancel callback must be provided as well.

Parameters

conn	Connection where pairing is currently active.
highsec	true if 16 digit PIN is required.

---

The documentation for this struct was generated from the following file:

• zephyr/bluetooth/conn.h