Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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
connNew connection object.
errHCI error. Zero for success, non-zero otherwise.

err can mean either of the following:

◆ 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
connConnection object.
reasonBT_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
connConnection object.
rpaResolvable Private Address.
identityIdentity 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
connConnection object.
infoConnection 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
connConnection object.
paramProposed 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
connConnection object.
intervalConnection interval.
latencyConnection latency.
timeoutConnection 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
connConnection object.
infoConnection 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
connConnection object.
remote_infoConnection 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
connConnection object.
levelNew security level of the connection.
errSecurity error. Zero for success, non-zero otherwise.

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