michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Bluetooth: host: Document bt_conn_unref responsibility of caller

Browse source 
Document the need for the caller to call  bt_conn_unref on the
connection object returned from API functions.

Signed-off-by: Joakim Andersson <joakim.andersson@nordicsemi.no>
This commit is contained in:
Joakim Andersson 2020-02-25 09:55:32 +01:00 • committed by Johan Hedberg
commit 1db7a11c3f
1 changed files with 15 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

22
include/bluetooth/conn.h
View file

@ -93,12 +93,13 @@ void bt_conn_foreach(int type, void (*func)(struct bt_conn *conn, void *data),
* *
* Look up an existing connection based on the remote address. * Look up an existing connection based on the remote address.
* *
* The caller gets a new reference to the connection object which must be
* released with bt_conn_unref() once done using the object.
*
* @param id Local identity (in most cases BT_ID_DEFAULT). * @param id Local identity (in most cases BT_ID_DEFAULT).
* @param peer Remote address. * @param peer Remote address.
* *
* @return Connection object or NULL if not found. The caller gets a * @return Connection object or NULL if not found.
* new reference to the connection object which must be released with
* bt_conn_unref() once done using the object.
*/ */
struct bt_conn *bt_conn_lookup_addr_le(u8_t id, const bt_addr_le_t *peer); struct bt_conn *bt_conn_lookup_addr_le(u8_t id, const bt_addr_le_t *peer);
@ -280,7 +281,9 @@ int bt_conn_disconnect(struct bt_conn *conn, u8_t reason);
/** @brief Initiate an LE connection to a remote device. /** @brief Initiate an LE connection to a remote device.
* *
* Allows initiate new LE link to remote peer using its address. * Allows initiate new LE link to remote peer using its address.
* Returns a new reference that the the caller is responsible for managing. *
* The caller gets a new reference to the connection object which must be
* released with bt_conn_unref() once done using the object.
* *
* This uses the General Connection Establishment procedure. * This uses the General Connection Establishment procedure.
* *
@ -345,7 +348,8 @@ int bt_le_set_auto_conn(const bt_addr_le_t *addr,
* *
* The advertising may be canceled with bt_conn_disconnect(). * The advertising may be canceled with bt_conn_disconnect().
* *
* Returns a new reference that the the caller is responsible for managing. * The caller gets a new reference to the connection object which must be
* released with bt_conn_unref() once done using the object.
* *
* @param peer Remote address. * @param peer Remote address.
* @param param Directed advertising parameters. * @param param Directed advertising parameters.
@ -1023,7 +1027,9 @@ struct bt_br_conn_param {
/** @brief Initiate an BR/EDR connection to a remote device. /** @brief Initiate an BR/EDR connection to a remote device.
* *
* Allows initiate new BR/EDR link to remote peer using its address. * Allows initiate new BR/EDR link to remote peer using its address.
* Returns a new reference that the the caller is responsible for managing. *
* The caller gets a new reference to the connection object which must be
* released with bt_conn_unref() once done using the object.
* *
* @param peer Remote address. * @param peer Remote address.
* @param param Initial connection parameters. * @param param Initial connection parameters.
@ -1036,7 +1042,9 @@ struct bt_conn *bt_conn_create_br(const bt_addr_t *peer,
/** @brief Initiate an SCO connection to a remote device. /** @brief Initiate an SCO connection to a remote device.
* *
* Allows initiate new SCO link to remote peer using its address. * Allows initiate new SCO link to remote peer using its address.
* Returns a new reference that the the caller is responsible for managing. *
* The caller gets a new reference to the connection object which must be
* released with bt_conn_unref() once done using the object.
* *
* @param peer Remote address. * @param peer Remote address.
* *