Zephyr API Documentation 3.7.99
A Scalable Open Source RTOS
|
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. | |
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.
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.
conn | New connection object. |
err | HCI error. Zero for success, non-zero otherwise. |
err
can mean either of the following:
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. 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
.
conn | Connection object. |
reason | BT_HCI_ERR_* reason for the disconnection. |
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
conn | Connection object. |
rpa | Resolvable Private Address. |
identity | Identity Address. |
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.
conn | Connection object. |
info | Connection data length information. |
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.
conn | Connection object. |
param | Proposed connection parameters. |
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.
conn | Connection object. |
interval | Connection interval. |
latency | Connection latency. |
timeout | Connection supervision timeout. |
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.
conn | Connection object. |
info | Connection LE PHY information. |
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.
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.
conn | Connection object. |
remote_info | Connection information of remote device. |
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.
conn | Connection object. |
level | New security level of the connection. |
err | Security error. Zero for success, non-zero otherwise. |