8acb1cc577
This commit adds a warning and a Kconfig option to `bt_conn_le_create` and `bt_conn_le_create_synced` functions which are meant to warn a user of a potential leakage of an active connection object. This change is implemented due to frequent incorrect use of the connection pointer where a pointer to an existing connection object is overwritten by `bt_conn_le_create` and `bt_conn_le_create_synced` functions which in turns leads to sporadic critical bugs. See https://github.com/zephyrproject-rtos/zephyr/pull/78284#discussion_r1754304535 for more details. The Kconfig option is introduced instead of always returning the error to not affect current implementations. However, it is recommended to keep this option enabled to avoid potential bugs. Signed-off-by: Pavel Vasilyev <pavel.vasilyev@nordicsemi.no>
39 lines
1.8 KiB
ReStructuredText
39 lines
1.8 KiB
ReStructuredText
.. _bluetooth_connection_mgmt:
|
|
|
|
Connection Management
|
|
#####################
|
|
|
|
The Zephyr Bluetooth stack uses an abstraction called :c:struct:`bt_conn`
|
|
to represent connections to other devices. The internals of this struct
|
|
are not exposed to the application, but a limited amount of information
|
|
(such as the remote address) can be acquired using the
|
|
:c:func:`bt_conn_get_info` API. Connection objects are reference
|
|
counted, and the application is expected to use the
|
|
:c:func:`bt_conn_ref` API whenever storing a connection pointer for a
|
|
longer period of time, since this ensures that the object remains valid
|
|
(even if the connection would get disconnected). Similarly the
|
|
:c:func:`bt_conn_unref` API is to be used when releasing a reference
|
|
to a connection.
|
|
|
|
A common mistake is to forget unreleasing a reference to a connection
|
|
object created by functions :c:func:`bt_conn_le_create` and
|
|
:c:func:`bt_conn_le_create_synced`. To protect against this, use the
|
|
:kconfig:option:`CONFIG_BT_CONN_CHECK_NULL_BEFORE_CREATE` Kconfig option,
|
|
which forces these functions return an error if the connection pointer
|
|
passed to them is not NULL. This helps to spot such issues and avoid
|
|
sporadic bugs caused by not releasing the connection object.
|
|
|
|
An application may track connections by registering a
|
|
:c:struct:`bt_conn_cb` struct using the :c:func:`bt_conn_cb_register`
|
|
or :c:macro:`BT_CONN_CB_DEFINE` APIs. This struct lets the application
|
|
define callbacks for connection & disconnection events, as well as other
|
|
events related to a connection such as a change in the security level or
|
|
the connection parameters. When acting as a central the application will
|
|
also get hold of the connection object through the return value of the
|
|
:c:func:`bt_conn_le_create` API.
|
|
|
|
API Reference
|
|
*************
|
|
|
|
.. doxygengroup:: bt_conn
|