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(*	le_param_update_rejected )(struct bt_conn *conn, uint8_t hci_err)
	LE connection parameter update was rejected by the peer.
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.
struct bt_conn_br_cb	br
	BR/EDR specific callbacks.
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.
void(*	cte_report_cb )(struct bt_conn conn, const struct bt_df_conn_iq_samples_report iq_report)
	Callback for IQ samples report collected when sampling CTE received by data channel PDU.
void(*	tx_power_report )(struct bt_conn conn, const struct bt_conn_le_tx_power_report report)
	LE Read Remote Transmit Power Level procedure has completed or LE Transmit Power Reporting event.
void(*	path_loss_threshold_report )(struct bt_conn conn, const struct bt_conn_le_path_loss_threshold_report report)
	LE Path Loss Threshold event.
void(*	subrate_changed )(struct bt_conn conn, const struct bt_conn_le_subrate_changed params)
	LE Subrate Changed event.
void(*	conn_rate_changed )(struct bt_conn conn, uint8_t status, const struct bt_conn_le_conn_rate_changed params)
	LE Connection Rate Changed event.
void(*	read_all_remote_feat_complete )(struct bt_conn conn, const struct bt_conn_le_read_all_remote_feat_complete params)
	Read all remote features complete event.
void(*	frame_space_updated )(struct bt_conn conn, const struct bt_conn_le_frame_space_updated params)
	Frame Space Update Complete event.
void(*	le_cs_read_remote_capabilities_complete )(struct bt_conn conn, uint8_t status, struct bt_conn_le_cs_capabilities params)
	LE CS Read Remote Supported Capabilities Complete event.
void(*	le_cs_read_remote_fae_table_complete )(struct bt_conn conn, uint8_t status, struct bt_conn_le_cs_fae_table params)
	LE CS Read Remote FAE Table Complete event.
void(*	le_cs_config_complete )(struct bt_conn conn, uint8_t status, struct bt_conn_le_cs_config config)
	LE CS Config created.
void(*	le_cs_config_removed )(struct bt_conn *conn, uint8_t config_id)
	LE CS Config removed.
void(*	le_cs_subevent_data_available )(struct bt_conn conn, struct bt_conn_le_cs_subevent_result result)
	Subevent Results from a CS procedure are available.
void(*	le_cs_security_enable_complete )(struct bt_conn *conn, uint8_t status)
	LE CS Security Enabled.
void(*	le_cs_procedure_enable_complete )(struct bt_conn conn, uint8_t status, struct bt_conn_le_cs_procedure_enable_complete params)
	LE CS Procedure Enabled.

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

◆ br

struct bt_conn_br_cb bt_conn_cb::br

BR/EDR specific callbacks.

◆ conn_rate_changed

void(* bt_conn_cb::conn_rate_changed) (struct bt_conn *conn, uint8_t status, const struct bt_conn_le_conn_rate_changed *params)

LE Connection Rate Changed event.

This callback notifies the application that the connection rate parameters (including both connection interval and subrating) of the connection may have changed.

Parameters

conn	Connection object.
status	HCI Status from LE Connection Rate Change event. Possible Status codes: Success (0x00) Unknown Connection Identifier (0x02) Command Disallowed (0x0C) Unsupported Feature or Parameter Value (0x11) Invalid HCI Command Parameters (0x12) Unsupported Remote Feature (0x1A) Unsupported LL Parameter Value (0x20)
params	New connection rate parameters. The connection rate parameters will be NULL if `status` is not BT_HCI_ERR_SUCCESS.

◆ 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.

◆ cte_report_cb

void(* bt_conn_cb::cte_report_cb) (struct bt_conn *conn, const struct bt_df_conn_iq_samples_report *iq_report)

Callback for IQ samples report collected when sampling CTE received by data channel PDU.

Parameters

conn	The connection object.
iq_report	Report data for collected IQ samples.

◆ 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's recommended to rely instead on bt_conn_cb::recycled which notifies the application when a connection object has actually been freed.

Parameters

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

◆ frame_space_updated

void(* bt_conn_cb::frame_space_updated) (struct bt_conn *conn, const struct bt_conn_le_frame_space_updated *params)

Frame Space Update Complete event.

This callback notifies the application that the frame space of the connection may have changed. The frame space update parameters will be invalid if status is not BT_HCI_ERR_SUCCESS.

This callback can be triggered by calling bt_conn_le_frame_space_update, by the procedure running autonomously in the controller or by the peer.

Parameters

conn	Connection object.
params	New frame space update parameters.

◆ 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_cs_config_complete

void(* bt_conn_cb::le_cs_config_complete) (struct bt_conn *conn, uint8_t status, struct bt_conn_le_cs_config *config)

LE CS Config created.

This callback notifies the application that a Channel Sounding Configuration procedure has completed.

If status is BT_HCI_ERR_SUCCESS, a new CS config is created.

Parameters

conn	Connection object.
status	HCI status of complete event.
config	Pointer to CS configuration on success or NULL otherwise.

◆ le_cs_config_removed

void(* bt_conn_cb::le_cs_config_removed) (struct bt_conn *conn, uint8_t config_id)

LE CS Config removed.

This callback notifies the application that a Channel Sounding Configuration procedure has completed and a CS config is removed

Parameters

conn	Connection object.
config_id	ID of the CS configuration that was removed.

◆ le_cs_procedure_enable_complete

void(* bt_conn_cb::le_cs_procedure_enable_complete) (struct bt_conn *conn, uint8_t status, struct bt_conn_le_cs_procedure_enable_complete *params)

LE CS Procedure Enabled.

This callback notifies the application that a Channel Sounding Procedure Enable procedure has completed.

If status is BT_HCI_ERR_SUCCESS, CS procedure is enabled.

Parameters

conn	Connection object.
status	HCI status.
params	Pointer to CS Procedure Enable parameters on success or NULL otherwise.

◆ le_cs_read_remote_capabilities_complete

void(* bt_conn_cb::le_cs_read_remote_capabilities_complete) (struct bt_conn *conn, uint8_t status, struct bt_conn_le_cs_capabilities *params)

LE CS Read Remote Supported Capabilities Complete event.

This callback notifies the application that a Channel Sounding Capabilities Exchange procedure has completed.

If status is BT_HCI_ERR_SUCCESS, the remote channel sounding capabilities have been received from the peer.

Parameters

conn	Connection object.
status	HCI status of complete event.
params	Pointer to CS Capabilities on success or NULL otherwise.

◆ le_cs_read_remote_fae_table_complete

void(* bt_conn_cb::le_cs_read_remote_fae_table_complete) (struct bt_conn *conn, uint8_t status, struct bt_conn_le_cs_fae_table *params)

LE CS Read Remote FAE Table Complete event.

This callback notifies the application that a Channel Sounding Mode-0 FAE Table Request procedure has completed.

If status is BT_HCI_ERR_SUCCESS, the remote mode-0 FAE Table has been received from the peer.

Parameters

conn	Connection object.
status	HCI status of complete event.
params	Pointer to FAE Table on success or NULL otherwise.

◆ le_cs_security_enable_complete

void(* bt_conn_cb::le_cs_security_enable_complete) (struct bt_conn *conn, uint8_t status)

LE CS Security Enabled.

This callback notifies the application that a Channel Sounding Security Enable procedure has completed.

If status is BT_HCI_ERR_SUCCESS, CS Security is enabled.

Parameters

conn	Connection object.
status	HCI status of complete event.

◆ le_cs_subevent_data_available

void(* bt_conn_cb::le_cs_subevent_data_available) (struct bt_conn *conn, struct bt_conn_le_cs_subevent_result *result)

Subevent Results from a CS procedure are available.

This callback notifies the user that CS subevent results are available for the given connection object.

Parameters

conn	Connection objects.
result	Subevent results

◆ 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_update_rejected

void(* bt_conn_cb::le_param_update_rejected) (struct bt_conn *conn, uint8_t hci_err)

LE connection parameter update was rejected by the peer.

This callback notifies the application that a connection parameter update request initiated by bt_conn_le_param_update was rejected by the peer.

Note: Only called for explicit HCI rejections and L2CAP Connection Parameter Update Procedure (CPUP) rejections. Mutually exclusive with le_param_updated for the same event. If the remote does not support the Connection Parameter Request (CPR) procedure and the L2CAP fallback is rejected, hci_err will be BT_CONN_PARAM_REJECT_ERR_L2CAP_CPUP.

Parameters

conn	Connection object.
hci_err	HCI error code (BT_HCI_ERR_*) for CPR rejection, or BT_CONN_PARAM_REJECT_ERR_L2CAP_CPUP for L2CAP fallback rejection.

◆ 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.
param	Connection LE PHY information.

◆ path_loss_threshold_report

void(* bt_conn_cb::path_loss_threshold_report) (struct bt_conn *conn, const struct bt_conn_le_path_loss_threshold_report *report)

LE Path Loss Threshold event.

This callback notifies the application that there has been a path loss threshold crossing or reporting the initial path loss threshold zone after using bt_conn_le_set_path_loss_mon_enable.

Parameters

conn	Connection object.
report	Path loss threshold report.

◆ read_all_remote_feat_complete

void(* bt_conn_cb::read_all_remote_feat_complete) (struct bt_conn *conn, const struct bt_conn_le_read_all_remote_feat_complete *params)

Read all remote features complete event.

This callback notifies the application that a 'read all remote features' procedure of the connection is completed. The other params will not be populated if status is not BT_HCI_ERR_SUCCESS.

This callback can be triggered by calling bt_conn_le_read_all_remote_features or by the procedure running autonomously in the controller.

Parameters

conn	Connection object.
params	Remote features.

◆ 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. Only connections that are configurable by

CONFIG_BT_MAX_CONN

trigger this callback, i.e. connections of type BT_CONN_TYPE_LE or BT_CONN_TYPE_BR.

The maximum number of simultaneous connections is configured by

CONFIG_BT_MAX_CONN

.

This is the event to listen for to start a new connection or connectable advertiser, both when the intention is to start it after the system is completely finished with an earlier connection, and when the application wants to start a connection for any reason but failed and is waiting for the right time to retry.

◆ 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.

◆ subrate_changed

void(* bt_conn_cb::subrate_changed) (struct bt_conn *conn, const struct bt_conn_le_subrate_changed *params)

LE Subrate Changed event.

This callback notifies the application that the subrating parameters of the connection may have changed. The connection subrating parameters will be unchanged if status is not BT_HCI_ERR_SUCCESS.

Parameters

conn	Connection object.
params	New subrating parameters.

◆ tx_power_report

void(* bt_conn_cb::tx_power_report) (struct bt_conn *conn, const struct bt_conn_le_tx_power_report *report)

LE Read Remote Transmit Power Level procedure has completed or LE Transmit Power Reporting event.

This callback notifies the application that either the remote transmit power level has been read from the peer or transmit power level has changed for the local or remote controller when transmit power reporting is enabled for the respective side using bt_conn_le_set_tx_power_report_enable.

Parameters

conn	Connection object.
report	Transmit power report.

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

include/zephyr/bluetooth/conn.h

Data Fields

Detailed Description

Field Documentation

◆ br

◆ conn_rate_changed

◆ connected

◆ cte_report_cb

◆ disconnected

◆ frame_space_updated

◆ identity_resolved

◆ le_cs_config_complete

◆ le_cs_config_removed

◆ le_cs_procedure_enable_complete

◆ le_cs_read_remote_capabilities_complete

◆ le_cs_read_remote_fae_table_complete

◆ le_cs_security_enable_complete

◆ le_cs_subevent_data_available

◆ le_data_len_updated

◆ le_param_req

◆ le_param_update_rejected

◆ le_param_updated

◆ le_phy_updated

◆ path_loss_threshold_report

◆ read_all_remote_feat_complete

◆ recycled

◆ remote_info_available

◆ security_changed

◆ subrate_changed

◆ tx_power_report