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
|