bt_conn_cb Struct Reference

Connection callback structure. More...

#include <conn.h>

Data Fields
void(*	connected )(struct bt_conn *conn, uint8_t err)
	A new connection has been established.
void(*	disconnected )(struct bt_conn *conn, uint8_t reason)
	A connection has been disconnected.
void(*	recycled )(void)
	A connection object has been returned to the pool.
bool(*	le_param_req )(struct bt_conn *conn, struct bt_le_conn_param *param)
	LE connection parameter update request.
void(*	le_param_updated )(struct bt_conn *conn, uint16_t interval, uint16_t latency, uint16_t timeout)
	The parameters for an LE connection have been updated.
void(*	identity_resolved )(struct bt_conn *conn, const bt_addr_le_t *rpa, const bt_addr_le_t *identity)
	Remote Identity Address has been resolved.
void(*	security_changed )(struct bt_conn *conn, bt_security_t level, enum bt_security_err err)
	The security level of a connection has changed.
void(*	remote_info_available )(struct bt_conn *conn, struct bt_conn_remote_info *remote_info)
	Remote information procedures has completed.
void(*	le_phy_updated )(struct bt_conn *conn, struct bt_conn_le_phy_info *param)
	The PHY of the connection has changed.
void(*	le_data_len_updated )(struct bt_conn *conn, struct bt_conn_le_data_len_info *info)
	The data length parameters of the connection has changed.

Detailed Description

Connection callback structure.

This structure is used for tracking the state of a connection. It is registered with the help of the bt_conn_cb_register() API. It's permissible to register multiple instances of this bt_conn_cb type, in case different modules of an application are interested in tracking the connection state. If a callback is not of interest for an instance, it may be set to NULL and will as a consequence not be used for that instance.

Field Documentation

connected

void(* bt_conn_cb::connected) (struct bt_conn *conn, uint8_t err)

A new connection has been established.

This callback notifies the application of a new connection. In case the err parameter is non-zero it means that the connection establishment failed.

Note

If the connection was established from an advertising set then the advertising set cannot be restarted directly from this callback. Instead use the connected callback of the advertising set.

Parameters

conn	New connection object.
err	HCI error. Zero for success, non-zero otherwise.

err can mean either of the following:

• BT_HCI_ERR_UNKNOWN_CONN_ID Creating the connection started by bt_conn_le_create was canceled either by the user through bt_conn_disconnect or by the timeout in the host through bt_conn_le_create_param timeout parameter, which defaults to

  CONFIG_BT_CREATE_CONN_TIMEOUT 

  seconds.
• BT_HCI_ERR_ADV_TIMEOUT High duty cycle directed connectable advertiser started by bt_le_adv_start failed to be connected within the timeout.

disconnected

void(* bt_conn_cb::disconnected) (struct bt_conn *conn, uint8_t reason)

A connection has been disconnected.

This callback notifies the application that a connection has been disconnected.

When this callback is called the stack still has one reference to the connection object. If the application in this callback tries to start either a connectable advertiser or create a new connection this might fail because there are no free connection objects available. To avoid this issue it is recommended to either start connectable advertise or create a new connection using k_work_submit or increase

CONFIG_BT_MAX_CONN 

.

Parameters

conn	Connection object.
reason	BT_HCI_ERR_* reason for the disconnection.

identity_resolved

void(* bt_conn_cb::identity_resolved) (struct bt_conn *conn, const bt_addr_le_t *rpa, const bt_addr_le_t *identity)

Remote Identity Address has been resolved.

This callback notifies the application that a remote Identity Address has been resolved

Parameters

conn	Connection object.
rpa	Resolvable Private Address.
identity	Identity Address.

le_data_len_updated

void(* bt_conn_cb::le_data_len_updated) (struct bt_conn *conn, struct bt_conn_le_data_len_info *info)

The data length parameters of the connection has changed.

This callback notifies the application that the maximum Link Layer payload length or transmission time has changed.

Parameters

conn	Connection object.
info	Connection data length information.

le_param_req

bool(* bt_conn_cb::le_param_req) (struct bt_conn *conn, struct bt_le_conn_param *param)

LE connection parameter update request.

This callback notifies the application that a remote device is requesting to update the connection parameters. The application accepts the parameters by returning true, or rejects them by returning false. Before accepting, the application may also adjust the parameters to better suit its needs.

It is recommended for an application to have just one of these callbacks for simplicity. However, if an application registers multiple it needs to manage the potentially different requirements for each callback. Each callback gets the parameters as returned by previous callbacks, i.e. they are not necessarily the same ones as the remote originally sent.

If the application does not have this callback then the default is to accept the parameters.

Parameters

conn	Connection object.
param	Proposed connection parameters.

Returns

true to accept the parameters, or false to reject them.

le_param_updated

void(* bt_conn_cb::le_param_updated) (struct bt_conn *conn, uint16_t interval, uint16_t latency, uint16_t timeout)

The parameters for an LE connection have been updated.

This callback notifies the application that the connection parameters for an LE connection have been updated.

Parameters

conn	Connection object.
interval	Connection interval.
latency	Connection latency.
timeout	Connection supervision timeout.

le_phy_updated

void(* bt_conn_cb::le_phy_updated) (struct bt_conn *conn, struct bt_conn_le_phy_info *param)

The PHY of the connection has changed.

This callback notifies the application that the PHY of the connection has changed.

Parameters

conn	Connection object.
info	Connection LE PHY information.

recycled

void(* bt_conn_cb::recycled) (void)

A connection object has been returned to the pool.

This callback notifies the application that it might be able to allocate a connection object. No guarantee, first come, first serve.

Use this to e.g. re-start connectable advertising or scanning.

Treat this callback as an ISR, as it originates from bt_conn_unref which is used by the BT stack. Making Bluetooth API calls in this context is error-prone and strongly discouraged.

remote_info_available

void(* bt_conn_cb::remote_info_available) (struct bt_conn *conn, struct bt_conn_remote_info *remote_info)

Remote information procedures has completed.

This callback notifies the application that the remote information has been retrieved from the remote peer.

Parameters

conn	Connection object.
remote_info	Connection information of remote device.

security_changed

void(* bt_conn_cb::security_changed) (struct bt_conn *conn, bt_security_t level, enum bt_security_err err)

The security level of a connection has changed.

This callback notifies the application that the security of a connection has changed.

The security level of the connection can either have been increased or remain unchanged. An increased security level means that the pairing procedure has been performed or the bond information from a previous connection has been applied. If the security level remains unchanged this means that the encryption key has been refreshed for the connection.

Parameters

conn	Connection object.
level	New security level of the connection.
err	Security error. Zero for success, non-zero otherwise.

---

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

• include/zephyr/bluetooth/conn.h