1.. _bluetooth_connection_mgmt: 2 3Connection Management 4##################### 5 6The Zephyr Bluetooth stack uses an abstraction called :c:struct:`bt_conn` 7to represent connections to other devices. The internals of this struct 8are not exposed to the application, but a limited amount of information 9(such as the remote address) can be acquired using the 10:c:func:`bt_conn_get_info` API. Connection objects are reference 11counted, and the application is expected to use the 12:c:func:`bt_conn_ref` API whenever storing a connection pointer for a 13longer period of time, since this ensures that the object remains valid 14(even if the connection would get disconnected). Similarly the 15:c:func:`bt_conn_unref` API is to be used when releasing a reference 16to a connection. 17 18A common mistake is to forget unreleasing a reference to a connection 19object created by functions :c:func:`bt_conn_le_create` and 20:c:func:`bt_conn_le_create_synced`. To protect against this, use the 21:kconfig:option:`CONFIG_BT_CONN_CHECK_NULL_BEFORE_CREATE` Kconfig option, 22which forces these functions return an error if the connection pointer 23passed to them is not NULL. This helps to spot such issues and avoid 24sporadic bugs caused by not releasing the connection object. 25 26An application may track connections by registering a 27:c:struct:`bt_conn_cb` struct using the :c:func:`bt_conn_cb_register` 28or :c:macro:`BT_CONN_CB_DEFINE` APIs. This struct lets the application 29define callbacks for connection & disconnection events, as well as other 30events related to a connection such as a change in the security level or 31the connection parameters. When acting as a central the application will 32also get hold of the connection object through the return value of the 33:c:func:`bt_conn_le_create` API. 34 35API Reference 36************* 37 38.. doxygengroup:: bt_conn 39