Connection management

Connection management. More...

Data Structures
struct	bt_le_conn_param
struct	bt_conn_le_phy_info
struct	bt_conn_le_phy_param
struct	bt_conn_le_data_len_info
struct	bt_conn_le_data_len_param
struct	bt_conn_le_info
struct	bt_conn_br_info
struct	bt_conn_info
struct	bt_conn_le_remote_info
struct	bt_conn_br_remote_info
struct	bt_conn_remote_info
	Connection Remote Info Structure. More...
struct	bt_conn_le_tx_power
struct	bt_conn_le_create_param
struct	bt_conn_cb
	Connection callback structure. More...
struct	bt_conn_oob_info
struct	bt_conn_pairing_feat
	Pairing request and pairing response info structure. More...
struct	bt_conn_auth_cb
struct	bt_br_conn_param

Macros
#define	BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to)
	Initialize connection parameters. More...
#define	BT_LE_CONN_PARAM(int_min, int_max, lat, to)
#define	BT_LE_CONN_PARAM_DEFAULT
#define	BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy)
#define	BT_CONN_LE_PHY_PARAM(_pref_tx_phy, _pref_rx_phy)
#define	BT_CONN_LE_PHY_PARAM_1M
#define	BT_CONN_LE_PHY_PARAM_2M
#define	BT_CONN_LE_PHY_PARAM_CODED
#define	BT_CONN_LE_PHY_PARAM_ALL
#define	BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time)
#define	BT_CONN_LE_DATA_LEN_PARAM(_tx_max_len, _tx_max_time)
#define	BT_LE_DATA_LEN_PARAM_DEFAULT
#define	BT_LE_DATA_LEN_PARAM_MAX
#define	BT_CONN_ROLE_MASTER   __DEPRECATED_MACRO BT_CONN_ROLE_CENTRAL
#define	BT_CONN_ROLE_SLAVE   __DEPRECATED_MACRO BT_CONN_ROLE_PERIPHERAL
#define	BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window)
	Initialize create connection parameters. More...
#define	BT_CONN_LE_CREATE_PARAM(_options, _interval, _window)
#define	BT_CONN_LE_CREATE_CONN
#define	BT_CONN_LE_CREATE_CONN_AUTO
#define	BT_CONN_CB_DEFINE(_name)
	Register a callback structure for connection events. More...
#define	BT_PASSKEY_INVALID   0xffffffff
#define	BT_BR_CONN_PARAM_INIT(role_switch)
	Initialize BR/EDR connection parameters. More...
#define	BT_BR_CONN_PARAM(role_switch)
#define	BT_BR_CONN_PARAM_DEFAULT   BT_BR_CONN_PARAM(true)

Enumerations
enum	{ BT_CONN_LE_PHY_OPT_NONE = 0 , BT_CONN_LE_PHY_OPT_CODED_S2 = BIT(0) , BT_CONN_LE_PHY_OPT_CODED_S8 = BIT(1) }
enum	{   BT_CONN_TYPE_LE = BIT(0) , BT_CONN_TYPE_BR = BIT(1) , BT_CONN_TYPE_SCO = BIT(2) , BT_CONN_TYPE_ISO = BIT(3) ,   BT_CONN_TYPE_ALL }
enum	{ BT_CONN_ROLE_CENTRAL = 0 , BT_CONN_ROLE_PERIPHERAL = 1 }
enum	bt_conn_le_tx_power_phy {   BT_CONN_LE_TX_POWER_PHY_NONE , BT_CONN_LE_TX_POWER_PHY_1M , BT_CONN_LE_TX_POWER_PHY_2M , BT_CONN_LE_TX_POWER_PHY_CODED_S8 ,   BT_CONN_LE_TX_POWER_PHY_CODED_S2 }
enum	{ BT_CONN_LE_OPT_NONE = 0 , BT_CONN_LE_OPT_CODED = BIT(0) , BT_CONN_LE_OPT_NO_1M = BIT(1) }
enum	bt_security_t {   BT_SECURITY_L0 , BT_SECURITY_L1 , BT_SECURITY_L2 , BT_SECURITY_L3 ,   BT_SECURITY_L4 , BT_SECURITY_FORCE_PAIR = BIT(7) }
enum	bt_security_err {   BT_SECURITY_ERR_SUCCESS , BT_SECURITY_ERR_AUTH_FAIL , BT_SECURITY_ERR_PIN_OR_KEY_MISSING , BT_SECURITY_ERR_OOB_NOT_AVAILABLE ,   BT_SECURITY_ERR_AUTH_REQUIREMENT , BT_SECURITY_ERR_PAIR_NOT_SUPPORTED , BT_SECURITY_ERR_PAIR_NOT_ALLOWED , BT_SECURITY_ERR_INVALID_PARAM ,   BT_SECURITY_ERR_UNSPECIFIED }

Functions
struct bt_conn *	bt_conn_ref (struct bt_conn *conn)
	Increment a connection's reference count. More...
void	bt_conn_unref (struct bt_conn *conn)
	Decrement a connection's reference count. More...
void	bt_conn_foreach (int type, void(*func)(struct bt_conn *conn, void *data), void *data)
	Iterate through all existing connections. More...
struct bt_conn *	bt_conn_lookup_addr_le (uint8_t id, const bt_addr_le_t *peer)
	Look up an existing connection by address. More...
const bt_addr_le_t *	bt_conn_get_dst (const struct bt_conn *conn)
	Get destination (peer) address of a connection. More...
uint8_t	bt_conn_index (struct bt_conn *conn)
	Get array index of a connection. More...
int	bt_conn_get_info (const struct bt_conn *conn, struct bt_conn_info *info)
	Get connection info. More...
int	bt_conn_get_remote_info (struct bt_conn *conn, struct bt_conn_remote_info *remote_info)
	Get connection info for the remote device. More...
int	bt_conn_le_get_tx_power_level (struct bt_conn *conn, struct bt_conn_le_tx_power *tx_power_level)
	Get connection transmit power level. More...
int	bt_conn_le_param_update (struct bt_conn *conn, const struct bt_le_conn_param *param)
	Update the connection parameters. More...
int	bt_conn_le_data_len_update (struct bt_conn *conn, const struct bt_conn_le_data_len_param *param)
	Update the connection transmit data length parameters. More...
int	bt_conn_le_phy_update (struct bt_conn *conn, const struct bt_conn_le_phy_param *param)
	Update the connection PHY parameters. More...
int	bt_conn_disconnect (struct bt_conn *conn, uint8_t reason)
	Disconnect from a remote device or cancel pending connection. More...
int	bt_conn_le_create (const bt_addr_le_t *peer, const struct bt_conn_le_create_param *create_param, const struct bt_le_conn_param *conn_param, struct bt_conn **conn)
	Initiate an LE connection to a remote device. More...
int	bt_conn_le_create_auto (const struct bt_conn_le_create_param *create_param, const struct bt_le_conn_param *conn_param)
	Automatically connect to remote devices in the filter accept list.. More...
int	bt_conn_create_auto_stop (void)
	Stop automatic connect creation. More...
int	bt_le_set_auto_conn (const bt_addr_le_t *addr, const struct bt_le_conn_param *param)
	Automatically connect to remote device if it's in range. More...
int	bt_conn_set_security (struct bt_conn *conn, bt_security_t sec)
	Set security level for a connection. More...
bt_security_t	bt_conn_get_security (struct bt_conn *conn)
	Get security level for a connection. More...
uint8_t	bt_conn_enc_key_size (struct bt_conn *conn)
	Get encryption key size. More...
void	bt_conn_cb_register (struct bt_conn_cb *cb)
	Register connection callbacks. More...
void	bt_set_bondable (bool enable)
	Enable/disable bonding. More...
void	bt_set_oob_data_flag (bool enable)
	Allow/disallow remote OOB data to be used for pairing. More...
int	bt_le_oob_set_legacy_tk (struct bt_conn *conn, const uint8_t *tk)
	Set OOB Temporary Key to be used for pairing. More...
int	bt_le_oob_set_sc_data (struct bt_conn *conn, const struct bt_le_oob_sc_data *oobd_local, const struct bt_le_oob_sc_data *oobd_remote)
	Set OOB data during LE Secure Connections (SC) pairing procedure. More...
int	bt_le_oob_get_sc_data (struct bt_conn *conn, const struct bt_le_oob_sc_data **oobd_local, const struct bt_le_oob_sc_data **oobd_remote)
	Get OOB data used for LE Secure Connections (SC) pairing procedure. More...
int	bt_passkey_set (unsigned int passkey)
	Set a fixed passkey to be used for pairing. More...
int	bt_conn_auth_cb_register (const struct bt_conn_auth_cb *cb)
	Register authentication callbacks. More...
int	bt_conn_auth_passkey_entry (struct bt_conn *conn, unsigned int passkey)
	Reply with entered passkey. More...
int	bt_conn_auth_cancel (struct bt_conn *conn)
	Cancel ongoing authenticated pairing. More...
int	bt_conn_auth_passkey_confirm (struct bt_conn *conn)
	Reply if passkey was confirmed to match by user. More...
int	bt_conn_auth_pairing_confirm (struct bt_conn *conn)
	Reply if incoming pairing was confirmed by user. More...
int	bt_conn_auth_pincode_entry (struct bt_conn *conn, const char *pin)
	Reply with entered PIN code. More...
struct bt_conn *	bt_conn_create_br (const bt_addr_t *peer, const struct bt_br_conn_param *param)
	Initiate an BR/EDR connection to a remote device. More...
struct bt_conn *	bt_conn_create_sco (const bt_addr_t *peer)
	Initiate an SCO connection to a remote device. More...

Detailed Description

Connection management.

Macro Definition Documentation

BT_BR_CONN_PARAM

#define BT_BR_CONN_PARAM

(

role_switch

)

#include <include/bluetooth/conn.h>

Value:

        ((struct bt_br_conn_param[]) { \
                BT_BR_CONN_PARAM_INIT(role_switch) \
         })

Helper to declare BR/EDR connection parameters inline

Parameters

role_switch

True if role switch is allowed

BT_BR_CONN_PARAM_DEFAULT

#define BT_BR_CONN_PARAM_DEFAULT   BT_BR_CONN_PARAM(true)

#include <include/bluetooth/conn.h>

Default BR/EDR connection parameters: Role switch allowed

BT_BR_CONN_PARAM_INIT

#define BT_BR_CONN_PARAM_INIT

(

role_switch

)

#include <include/bluetooth/conn.h>

Value:

{ \
        .allow_role_switch = (role_switch), \
}

Initialize BR/EDR connection parameters.

Parameters

role_switch

True if role switch is allowed

BT_CONN_CB_DEFINE

#define BT_CONN_CB_DEFINE

(

_name

)

#include <include/bluetooth/conn.h>

Value:

        static const STRUCT_SECTION_ITERABLE(bt_conn_cb,                \
                                                _CONCAT(bt_conn_cb_,    \
                                                        _name))

Register a callback structure for connection events.

Parameters

_name

Name of callback structure.

BT_CONN_LE_CREATE_CONN

#define BT_CONN_LE_CREATE_CONN

#include <include/bluetooth/conn.h>

Value:

        BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
                                BT_GAP_SCAN_FAST_INTERVAL, \
                                BT_GAP_SCAN_FAST_INTERVAL)

Default LE create connection parameters. Scan continuously by setting scan interval equal to scan window.

BT_CONN_LE_CREATE_CONN_AUTO

#define BT_CONN_LE_CREATE_CONN_AUTO

#include <include/bluetooth/conn.h>

Value:

        BT_CONN_LE_CREATE_PARAM(BT_CONN_LE_OPT_NONE, \
                                BT_GAP_SCAN_FAST_INTERVAL, \
                                BT_GAP_SCAN_FAST_WINDOW)

Default LE create connection using filter accept list parameters. Scan window: 30 ms. Scan interval: 60 ms.

BT_CONN_LE_CREATE_PARAM

#define BT_CONN_LE_CREATE_PARAM	(		_options,
			_interval,
			_window
	)

#include <include/bluetooth/conn.h>

Value:

        ((struct bt_conn_le_create_param[]) { \
                BT_CONN_LE_CREATE_PARAM_INIT(_options, _interval, _window) \
         })

Helper to declare create connection parameters inline

Parameters

_options	Create connection options.
_interval	Create connection scan interval (N * 0.625 ms).
_window	Create connection scan window (N * 0.625 ms).

BT_CONN_LE_CREATE_PARAM_INIT

#define BT_CONN_LE_CREATE_PARAM_INIT	(		_options,
			_interval,
			_window
	)

#include <include/bluetooth/conn.h>

Value:

{ \
        .options = (_options), \
        .interval = (_interval), \
        .window = (_window), \
        .interval_coded = 0, \
        .window_coded = 0, \
        .timeout = 0, \
}

Initialize create connection parameters.

Parameters

_options	Create connection options.
_interval	Create connection scan interval (N * 0.625 ms).
_window	Create connection scan window (N * 0.625 ms).

BT_CONN_LE_DATA_LEN_PARAM

#define BT_CONN_LE_DATA_LEN_PARAM	(		_tx_max_len,
			_tx_max_time
	)

#include <include/bluetooth/conn.h>

Value:

        ((struct bt_conn_le_data_len_param[]) { \
                BT_CONN_LE_DATA_LEN_PARAM_INIT(_tx_max_len, _tx_max_time) \
         })

Helper to declare transmit data length parameters inline

Parameters

_tx_max_len	Maximum Link Layer transmission payload size in bytes.
_tx_max_time	Maximum Link Layer transmission payload time in us.

BT_CONN_LE_DATA_LEN_PARAM_INIT

#define BT_CONN_LE_DATA_LEN_PARAM_INIT	(		_tx_max_len,
			_tx_max_time
	)

#include <include/bluetooth/conn.h>

Value:

{ \
        .tx_max_len = (_tx_max_len), \
        .tx_max_time = (_tx_max_time), \
}

Initialize transmit data length parameters

Parameters

_tx_max_len	Maximum Link Layer transmission payload size in bytes.
_tx_max_time	Maximum Link Layer transmission payload time in us.

BT_CONN_LE_PHY_PARAM

#define BT_CONN_LE_PHY_PARAM	(		_pref_tx_phy,
			_pref_rx_phy
	)

#include <include/bluetooth/conn.h>

Value:

        ((struct bt_conn_le_phy_param []) { \
                BT_CONN_LE_PHY_PARAM_INIT(_pref_tx_phy, _pref_rx_phy) \
         })

Helper to declare PHY parameters inline

Parameters

_pref_tx_phy	Bitmask of preferred transmit PHYs.
_pref_rx_phy	Bitmask of preferred receive PHYs.

BT_CONN_LE_PHY_PARAM_1M

#define BT_CONN_LE_PHY_PARAM_1M

#include <include/bluetooth/conn.h>

Value:

                                                     BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M, \
                                                     BT_GAP_LE_PHY_1M)

Only LE 1M PHY

BT_CONN_LE_PHY_PARAM_2M

#define BT_CONN_LE_PHY_PARAM_2M

#include <include/bluetooth/conn.h>

Value:

                                                     BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_2M, \
                                                     BT_GAP_LE_PHY_2M)

Only LE 2M PHY

BT_CONN_LE_PHY_PARAM_ALL

#define BT_CONN_LE_PHY_PARAM_ALL

#include <include/bluetooth/conn.h>

Value:

                                                      BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_1M |   \
                                                      BT_GAP_LE_PHY_2M |   \
                                                      BT_GAP_LE_PHY_CODED, \
                                                      BT_GAP_LE_PHY_1M |   \
                                                      BT_GAP_LE_PHY_2M |   \
                                                      BT_GAP_LE_PHY_CODED)

All LE PHYs.

BT_CONN_LE_PHY_PARAM_CODED

#define BT_CONN_LE_PHY_PARAM_CODED

#include <include/bluetooth/conn.h>

Value:

                                                        BT_CONN_LE_PHY_PARAM(BT_GAP_LE_PHY_CODED, \
                                                        BT_GAP_LE_PHY_CODED)

Only LE Coded PHY.

BT_CONN_LE_PHY_PARAM_INIT

#define BT_CONN_LE_PHY_PARAM_INIT	(		_pref_tx_phy,
			_pref_rx_phy
	)

#include <include/bluetooth/conn.h>

Value:

{ \
        .options = BT_CONN_LE_PHY_OPT_NONE, \
        .pref_tx_phy = (_pref_tx_phy), \
        .pref_rx_phy = (_pref_rx_phy), \
}

Initialize PHY parameters

Parameters

_pref_tx_phy	Bitmask of preferred transmit PHYs.
_pref_rx_phy	Bitmask of preferred receive PHYs.

BT_CONN_ROLE_MASTER

#define BT_CONN_ROLE_MASTER   __DEPRECATED_MACRO BT_CONN_ROLE_CENTRAL

#include <include/bluetooth/conn.h>

Connection role (central or peripheral)

BT_CONN_ROLE_SLAVE

#define BT_CONN_ROLE_SLAVE   __DEPRECATED_MACRO BT_CONN_ROLE_PERIPHERAL

#include <include/bluetooth/conn.h>

BT_LE_CONN_PARAM

#define BT_LE_CONN_PARAM	(		int_min,
			int_max,
			lat,
			to
	)

#include <include/bluetooth/conn.h>

Value:

        ((struct bt_le_conn_param[]) { \
                BT_LE_CONN_PARAM_INIT(int_min, int_max, lat, to) \
         })

Helper to declare connection parameters inline

Parameters

int_min	Minimum Connection Interval (N * 1.25 ms)
int_max	Maximum Connection Interval (N * 1.25 ms)
lat	Connection Latency
to	Supervision Timeout (N * 10 ms)

BT_LE_CONN_PARAM_DEFAULT

#define BT_LE_CONN_PARAM_DEFAULT

#include <include/bluetooth/conn.h>

Value:

                                                  BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, \
                                                  BT_GAP_INIT_CONN_INT_MAX, \
                                                  0, 400)

Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s

BT_LE_CONN_PARAM_INIT

#define BT_LE_CONN_PARAM_INIT	(		int_min,
			int_max,
			lat,
			to
	)

#include <include/bluetooth/conn.h>

Value:

{ \
        .interval_min = (int_min), \
        .interval_max = (int_max), \
        .latency = (lat), \
        .timeout = (to), \
}

Initialize connection parameters.

Parameters

int_min	Minimum Connection Interval (N * 1.25 ms)
int_max	Maximum Connection Interval (N * 1.25 ms)
lat	Connection Latency
to	Supervision Timeout (N * 10 ms)

BT_LE_DATA_LEN_PARAM_DEFAULT

#define BT_LE_DATA_LEN_PARAM_DEFAULT

#include <include/bluetooth/conn.h>

Value:

        BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_DEFAULT, \
                                  BT_GAP_DATA_TIME_DEFAULT)

Default LE data length parameters.

BT_LE_DATA_LEN_PARAM_MAX

#define BT_LE_DATA_LEN_PARAM_MAX

#include <include/bluetooth/conn.h>

Value:

        BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \
                                  BT_GAP_DATA_TIME_MAX)

Maximum LE data length parameters.

BT_PASSKEY_INVALID

#define BT_PASSKEY_INVALID   0xffffffff

#include <include/bluetooth/conn.h>

Special passkey value that can be used to disable a previously set fixed passkey.

Enumeration Type Documentation

anonymous enum

anonymous enum

#include <include/bluetooth/conn.h>

Connection PHY options

Enumerator
BT_CONN_LE_PHY_OPT_NONE	Convenience value when no options are specified.
BT_CONN_LE_PHY_OPT_CODED_S2	LE Coded using S=2 coding preferred when transmitting.
BT_CONN_LE_PHY_OPT_CODED_S8	LE Coded using S=8 coding preferred when transmitting.

anonymous enum

anonymous enum

#include <include/bluetooth/conn.h>

Connection Type

Enumerator
BT_CONN_TYPE_LE	LE Connection Type
BT_CONN_TYPE_BR	BR/EDR Connection Type
BT_CONN_TYPE_SCO	SCO Connection Type
BT_CONN_TYPE_ISO	ISO Connection Type
BT_CONN_TYPE_ALL	All Connection Type

anonymous enum

anonymous enum

#include <include/bluetooth/conn.h>

Enumerator
BT_CONN_ROLE_CENTRAL
BT_CONN_ROLE_PERIPHERAL

anonymous enum

anonymous enum

#include <include/bluetooth/conn.h>

Enumerator
BT_CONN_LE_OPT_NONE	Convenience value when no options are specified.
BT_CONN_LE_OPT_CODED	Enable LE Coded PHY. Enable scanning on the LE Coded PHY.
BT_CONN_LE_OPT_NO_1M	Disable LE 1M PHY. Disable scanning on the LE 1M PHY. @note Requires @ref BT_CONN_LE_OPT_CODED.

bt_conn_le_tx_power_phy

enum bt_conn_le_tx_power_phy

#include <include/bluetooth/conn.h>

Enumerator
BT_CONN_LE_TX_POWER_PHY_NONE	Convenience macro for when no PHY is set.
BT_CONN_LE_TX_POWER_PHY_1M	LE 1M PHY
BT_CONN_LE_TX_POWER_PHY_2M	LE 2M PHY
BT_CONN_LE_TX_POWER_PHY_CODED_S8	LE Coded PHY using S=8 coding.
BT_CONN_LE_TX_POWER_PHY_CODED_S2	LE Coded PHY using S=2 coding.

bt_security_err

enum bt_security_err

#include <include/bluetooth/conn.h>

Enumerator
BT_SECURITY_ERR_SUCCESS	Security procedure successful.
BT_SECURITY_ERR_AUTH_FAIL	Authentication failed.
BT_SECURITY_ERR_PIN_OR_KEY_MISSING	PIN or encryption key is missing.
BT_SECURITY_ERR_OOB_NOT_AVAILABLE	OOB data is not available.
BT_SECURITY_ERR_AUTH_REQUIREMENT	The requested security level could not be reached.
BT_SECURITY_ERR_PAIR_NOT_SUPPORTED	Pairing is not supported
BT_SECURITY_ERR_PAIR_NOT_ALLOWED	Pairing is not allowed.
BT_SECURITY_ERR_INVALID_PARAM	Invalid parameters.
BT_SECURITY_ERR_UNSPECIFIED	Pairing failed but the exact reason could not be specified.

bt_security_t

enum bt_security_t

#include <include/bluetooth/conn.h>

Security level.

Enumerator
BT_SECURITY_L0	Level 0: Only for BR/EDR special cases, like SDP
BT_SECURITY_L1	Level 1: No encryption and no authentication.
BT_SECURITY_L2	Level 2: Encryption and no authentication (no MITM).
BT_SECURITY_L3	Level 3: Encryption and authentication (MITM).
BT_SECURITY_L4	Level 4: Authenticated Secure Connections and 128-bit key.
BT_SECURITY_FORCE_PAIR	Bit to force new pairing procedure, bit-wise OR with requested security level.

Function Documentation

bt_conn_auth_cancel()

int bt_conn_auth_cancel

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Cancel ongoing authenticated pairing.

This function allows to cancel ongoing authenticated pairing.

Parameters

conn	Connection object.

Returns

Zero on success or negative error code otherwise

bt_conn_auth_cb_register()

int bt_conn_auth_cb_register

(

const struct bt_conn_auth_cb *

cb

)

#include <include/bluetooth/conn.h>

Register authentication callbacks.

Register callbacks to handle authenticated pairing. Passing NULL unregisters a previous callbacks structure.

Parameters

cb	Callback struct.

Returns

Zero on success or negative error code otherwise

bt_conn_auth_pairing_confirm()

int bt_conn_auth_pairing_confirm

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Reply if incoming pairing was confirmed by user.

This function should be called only after pairing_confirm callback from bt_conn_auth_cb structure was called if user confirmed incoming pairing.

Parameters

conn	Connection object.

Returns

Zero on success or negative error code otherwise

bt_conn_auth_passkey_confirm()

int bt_conn_auth_passkey_confirm

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Reply if passkey was confirmed to match by user.

This function should be called only after passkey_confirm callback from bt_conn_auth_cb structure was called.

Parameters

conn	Connection object.

Returns

Zero on success or negative error code otherwise

bt_conn_auth_passkey_entry()

int bt_conn_auth_passkey_entry	(	struct bt_conn *	conn,
		unsigned int	passkey
	)

#include <include/bluetooth/conn.h>

Reply with entered passkey.

This function should be called only after passkey_entry callback from bt_conn_auth_cb structure was called.

Parameters

conn	Connection object.
passkey	Entered passkey.

Returns

Zero on success or negative error code otherwise

bt_conn_auth_pincode_entry()

int bt_conn_auth_pincode_entry	(	struct bt_conn *	conn,
		const char *	pin
	)

#include <include/bluetooth/conn.h>

Reply with entered PIN code.

This function should be called only after PIN code callback from bt_conn_auth_cb structure was called. It's for legacy 2.0 devices.

Parameters

conn	Connection object.
pin	Entered PIN code.

Returns

Zero on success or negative error code otherwise

bt_conn_cb_register()

void bt_conn_cb_register

(

struct bt_conn_cb *

cb

)

#include <include/bluetooth/conn.h>

Register connection callbacks.

Register callbacks to monitor the state of connections.

Parameters

cb	Callback struct. Must point to memory that remains valid.

bt_conn_create_auto_stop()

int bt_conn_create_auto_stop

(

void

)

#include <include/bluetooth/conn.h>

Stop automatic connect creation.

Returns

Zero on success or (negative) error code on failure.

bt_conn_create_br()

struct bt_conn * bt_conn_create_br	(	const bt_addr_t *	peer,
		const struct bt_br_conn_param *	param
	)

#include <include/bluetooth/conn.h>

Initiate an BR/EDR connection to a remote device.

Allows initiate new BR/EDR link to remote peer using its address.

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

Parameters

peer	Remote address.
param	Initial connection parameters.

Returns

Valid connection object on success or NULL otherwise.

bt_conn_create_sco()

struct bt_conn * bt_conn_create_sco

(

const bt_addr_t *

peer

)

#include <include/bluetooth/conn.h>

Initiate an SCO connection to a remote device.

Allows initiate new SCO link to remote peer using its address.

The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.

Parameters

peer	Remote address.

Returns

Valid connection object on success or NULL otherwise.

bt_conn_disconnect()

int bt_conn_disconnect	(	struct bt_conn *	conn,
		uint8_t	reason
	)

#include <include/bluetooth/conn.h>

Disconnect from a remote device or cancel pending connection.

Disconnect an active connection with the specified reason code or cancel pending outgoing connection.

The disconnect reason for a normal disconnect should be: BT_HCI_ERR_REMOTE_USER_TERM_CONN.

The following disconnect reasons are accepted:

• BT_HCI_ERR_AUTH_FAIL
• BT_HCI_ERR_REMOTE_USER_TERM_CONN
• BT_HCI_ERR_REMOTE_LOW_RESOURCES
• BT_HCI_ERR_REMOTE_POWER_OFF
• BT_HCI_ERR_UNSUPP_REMOTE_FEATURE
• BT_HCI_ERR_PAIRING_NOT_SUPPORTED
• BT_HCI_ERR_UNACCEPT_CONN_PARAM

Parameters

conn	Connection to disconnect.
reason	Reason code for the disconnection.

Returns

Zero on success or (negative) error code on failure.

bt_conn_enc_key_size()

uint8_t bt_conn_enc_key_size

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Get encryption key size.

This function gets encryption key size. If there is no security (encryption) enabled 0 will be returned.

Parameters

conn	Existing connection object.

Returns

Encryption key size.

bt_conn_foreach()

void bt_conn_foreach	(	int	type,
		void(*)(struct bt_conn *conn, void *data)	func,
		void *	data
	)

#include <include/bluetooth/conn.h>

Iterate through all existing connections.

Parameters

type	Connection Type
func	Function to call for each connection.
data	Data to pass to the callback function.

bt_conn_get_dst()

const bt_addr_le_t * bt_conn_get_dst

(

const struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Get destination (peer) address of a connection.

Parameters

conn	Connection object.

Returns

Destination address.

bt_conn_get_info()

int bt_conn_get_info	(	const struct bt_conn *	conn,
		struct bt_conn_info *	info
	)

#include <include/bluetooth/conn.h>

Get connection info.

Parameters

conn	Connection object.
info	Connection info object.

Returns

Zero on success or (negative) error code on failure.

bt_conn_get_remote_info()

int bt_conn_get_remote_info	(	struct bt_conn *	conn,
		struct bt_conn_remote_info *	remote_info
	)

#include <include/bluetooth/conn.h>

Get connection info for the remote device.

Parameters

conn	Connection object.
remote_info	Connection remote info object.

Note

In order to retrieve the remote version (version, manufacturer and subversion)

embed:rst:inline :kconfig:`CONFIG_BT_REMOTE_VERSION` 

must be enabled

The remote information is exchanged directly after the connection has been established. The application can be notified about when the remote information is available through the remote_info_available callback.

Returns

Zero on success or (negative) error code on failure.

-EBUSY The remote information is not yet available.

bt_conn_get_security()

bt_security_t bt_conn_get_security

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Get security level for a connection.

Returns

Connection security level

bt_conn_index()

uint8_t bt_conn_index

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Get array index of a connection.

This function is used to map bt_conn to index of an array of connections. The array has CONFIG_BT_MAX_CONN elements.

Parameters

conn	Connection object.

Returns

Index of the connection object. The range of the returned value is 0..CONFIG_BT_MAX_CONN-1

bt_conn_le_create()

int bt_conn_le_create	(	const bt_addr_le_t *	peer,
		const struct bt_conn_le_create_param *	create_param,
		const struct bt_le_conn_param *	conn_param,
		struct bt_conn **	conn
	)

#include <include/bluetooth/conn.h>

Initiate an LE connection to a remote device.

Allows initiate new LE link to remote peer using its address.

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.

The application must disable explicit scanning before initiating a new LE connection.

Parameters

[in]	peer	Remote address.
[in]	create_param	Create connection parameters.
[in]	conn_param	Initial connection parameters.
[out]	conn	Valid connection object on success.

Returns

Zero on success or (negative) error code on failure.

bt_conn_le_create_auto()

int bt_conn_le_create_auto	(	const struct bt_conn_le_create_param *	create_param,
		const struct bt_le_conn_param *	conn_param
	)

#include <include/bluetooth/conn.h>

Automatically connect to remote devices in the filter accept list..

This uses the Auto Connection Establishment procedure. The procedure will continue until a single connection is established or the procedure is stopped through bt_conn_create_auto_stop. To establish connections to all devices in the the filter accept list the procedure should be started again in the connected callback after a new connection has been established.

Parameters

create_param	Create connection parameters
conn_param	Initial connection parameters.

Returns

Zero on success or (negative) error code on failure.

-ENOMEM No free connection object available.

bt_conn_le_data_len_update()

int bt_conn_le_data_len_update	(	struct bt_conn *	conn,
		const struct bt_conn_le_data_len_param *	param
	)

#include <include/bluetooth/conn.h>

Update the connection transmit data length parameters.

Parameters

conn	Connection object.
param	Updated data length parameters.

Returns

Zero on success or (negative) error code on failure.

bt_conn_le_get_tx_power_level()

int bt_conn_le_get_tx_power_level	(	struct bt_conn *	conn,
		struct bt_conn_le_tx_power *	tx_power_level
	)

#include <include/bluetooth/conn.h>

Get connection transmit power level.

Parameters

conn	Connection object.
tx_power_level	Transmit power level descriptor.

Returns

Zero on success or (negative) error code on failure.

-ENOBUFS HCI command buffer is not available.

bt_conn_le_param_update()

int bt_conn_le_param_update	(	struct bt_conn *	conn,
		const struct bt_le_conn_param *	param
	)

#include <include/bluetooth/conn.h>

Update the connection parameters.

If the local device is in the peripheral role then updating the connection parameters will be delayed. This delay can be configured by through the

embed:rst:inline :kconfig:`CONFIG_BT_CONN_PARAM_UPDATE_TIMEOUT` 

option.

Parameters

conn	Connection object.
param	Updated connection parameters.

Returns

Zero on success or (negative) error code on failure.

bt_conn_le_phy_update()

int bt_conn_le_phy_update	(	struct bt_conn *	conn,
		const struct bt_conn_le_phy_param *	param
	)

#include <include/bluetooth/conn.h>

Update the connection PHY parameters.

Update the preferred transmit and receive PHYs of the connection. Use BT_GAP_LE_PHY_NONE to indicate no preference.

Parameters

conn	Connection object.
param	Updated connection parameters.

Returns

Zero on success or (negative) error code on failure.

bt_conn_lookup_addr_le()

struct bt_conn * bt_conn_lookup_addr_le	(	uint8_t	id,
		const bt_addr_le_t *	peer
	)

#include <include/bluetooth/conn.h>

Look up an existing connection by 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.

Parameters

id	Local identity (in most cases BT_ID_DEFAULT).
peer	Remote address.

Returns

Connection object or NULL if not found.

bt_conn_ref()

struct bt_conn * bt_conn_ref

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Increment a connection's reference count.

Increment the reference count of a connection object.

Note

Will return NULL if the reference count is zero.

Parameters

conn	Connection object.

Returns

Connection object with incremented reference count, or NULL if the reference count is zero.

bt_conn_set_security()

int bt_conn_set_security	(	struct bt_conn *	conn,
		bt_security_t	sec
	)

#include <include/bluetooth/conn.h>

Set security level for a connection.

This function enable security (encryption) for a connection. If the device has bond information for the peer with sufficiently strong key encryption will be enabled. If the connection is already encrypted with sufficiently strong key this function does nothing.

If the device has no bond information for the peer and is not already paired then the pairing procedure will be initiated. If the device has bond information or is already paired and the keys are too weak then the pairing procedure will be initiated.

This function may return error if required level of security is not possible to achieve due to local or remote device limitation (e.g., input output capabilities), or if the maximum number of paired devices has been reached.

This function may return error if the pairing procedure has already been initiated by the local device or the peer device.

Note

When

embed:rst:inline :kconfig:`CONFIG_BT_SMP_SC_ONLY` 

is enabled then the security level will always be level 4.

When

embed:rst:inline :kconfig:`CONFIG_BT_SMP_OOB_LEGACY_PAIR_ONLY` 

is enabled then the security level will always be level 3.

Parameters

conn	Connection object.
sec	Requested security level.

Returns

0 on success or negative error

bt_conn_unref()

void bt_conn_unref

(

struct bt_conn *

conn

)

#include <include/bluetooth/conn.h>

Decrement a connection's reference count.

Decrement the reference count of a connection object.

Parameters

conn	Connection object.

bt_le_oob_get_sc_data()

int bt_le_oob_get_sc_data	(	struct bt_conn *	conn,
		const struct bt_le_oob_sc_data **	oobd_local,
		const struct bt_le_oob_sc_data **	oobd_remote
	)

#include <include/bluetooth/conn.h>

Get OOB data used for LE Secure Connections (SC) pairing procedure.

This function allows to get OOB data during the LE SC pairing procedure that were set by the bt_le_oob_set_sc_data() API.

Note

The OOB data will only be available as long as the connection object associated with it is valid.

Parameters

conn	Connection object
oobd_local	Local OOB data or NULL if not set
oobd_remote	Remote OOB data or NULL if not set

Returns

Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

bt_le_oob_set_legacy_tk()

int bt_le_oob_set_legacy_tk	(	struct bt_conn *	conn,
		const uint8_t *	tk
	)

#include <include/bluetooth/conn.h>

Set OOB Temporary Key to be used for pairing.

This function allows to set OOB data for the LE legacy pairing procedure. The function should only be called in response to the oob_data_request() callback provided that the legacy method is user pairing.

Parameters

conn	Connection object
tk	Pointer to 16 byte long TK array

Returns

Zero on success or -EINVAL if NULL

bt_le_oob_set_sc_data()

int bt_le_oob_set_sc_data	(	struct bt_conn *	conn,
		const struct bt_le_oob_sc_data *	oobd_local,
		const struct bt_le_oob_sc_data *	oobd_remote
	)

#include <include/bluetooth/conn.h>

Set OOB data during LE Secure Connections (SC) pairing procedure.

This function allows to set OOB data during the LE SC pairing procedure. The function should only be called in response to the oob_data_request() callback provided that LE SC method is used for pairing.

The user should submit OOB data according to the information received in the callback. This may yield three different configurations: with only local OOB data present, with only remote OOB data present or with both local and remote OOB data present.

Parameters

conn	Connection object
oobd_local	Local OOB data or NULL if not present
oobd_remote	Remote OOB data or NULL if not present

Returns

Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error.

bt_le_set_auto_conn()

int bt_le_set_auto_conn	(	const bt_addr_le_t *	addr,
		const struct bt_le_conn_param *	param
	)

#include <include/bluetooth/conn.h>

Automatically connect to remote device if it's in range.

This function enables/disables automatic connection initiation. Every time the device loses the connection with peer, this connection will be re-established if connectable advertisement from peer is received.

Note

Auto connect is disabled during explicit scanning.

Parameters

addr	Remote Bluetooth address.
param	If non-NULL, auto connect is enabled with the given parameters. If NULL, auto connect is disabled.

Returns

Zero on success or error code otherwise.

bt_passkey_set()

int bt_passkey_set

(

unsigned int

passkey

)

#include <include/bluetooth/conn.h>

Set a fixed passkey to be used for pairing.

This API is only available when the CONFIG_BT_FIXED_PASSKEY configuration option has been enabled.

Sets a fixed passkey to be used for pairing. If set, the pairing_confim() callback will be called for all incoming pairings.

Parameters

passkey

A valid passkey (0 - 999999) or BT_PASSKEY_INVALID to disable a previously set fixed passkey.

Returns

0 on success or a negative error code on failure.

bt_set_bondable()

void bt_set_bondable

(

bool

enable

)

#include <include/bluetooth/conn.h>

Enable/disable bonding.

Set/clear the Bonding flag in the Authentication Requirements of SMP Pairing Request/Response data. The initial value of this flag depends on BT_BONDABLE Kconfig setting. For the vast majority of applications calling this function shouldn't be needed.

Parameters

enable

Value allowing/disallowing to be bondable.

bt_set_oob_data_flag()

void bt_set_oob_data_flag

(

bool

enable

)

#include <include/bluetooth/conn.h>

Allow/disallow remote OOB data to be used for pairing.

Set/clear the OOB data flag for SMP Pairing Request/Response data. The initial value of this flag depends on BT_OOB_DATA_PRESENT Kconfig setting.

Parameters

enable

Value allowing/disallowing remote OOB data.