BLE connection state functions

Functions
void	ble_conn_state_init (void)
	Function for initializing or resetting the module. More...
bool	ble_conn_state_valid (uint16_t conn_handle)
	Function for querying whether a connection handle represents a valid connection. More...
uint8_t	ble_conn_state_role (uint16_t conn_handle)
	Function for querying the role of the local device in a connection. More...
ble_conn_state_status_t	ble_conn_state_status (uint16_t conn_handle)
	Function for querying the status of a connection. More...
bool	ble_conn_state_encrypted (uint16_t conn_handle)
	Function for querying whether a connection is encrypted. More...
bool	ble_conn_state_mitm_protected (uint16_t conn_handle)
	Function for querying whether a connection encryption is protected from Man in the Middle attacks. More...
bool	ble_conn_state_lesc (uint16_t conn_handle)
	Function for querying whether a connection was bonded using LE Secure Connections (LESC). More...
uint32_t	ble_conn_state_conn_count (void)
	Function for querying the total number of connections. More...
uint32_t	ble_conn_state_central_conn_count (void)
	Function for querying the total number of connections in which the role of the local device is BLE_GAP_ROLE_CENTRAL. More...
uint32_t	ble_conn_state_peripheral_conn_count (void)
	Function for querying the total number of connections in which the role of the local device is BLE_GAP_ROLE_PERIPH. More...
ble_conn_state_conn_handle_list_t	ble_conn_state_conn_handles (void)
	Function for obtaining a list of all connection handles for which the module has a record. More...
ble_conn_state_conn_handle_list_t	ble_conn_state_central_handles (void)
	Function for obtaining a list of connection handles in which the role of the local device is BLE_GAP_ROLE_CENTRAL. More...
ble_conn_state_conn_handle_list_t	ble_conn_state_periph_handles (void)
	Function for obtaining the handle for the connection in which the role of the local device is BLE_GAP_ROLE_PERIPH. More...
uint16_t	ble_conn_state_conn_idx (uint16_t conn_handle)
	Function for translating a connection handle to a value that can be used as an array index. More...
ble_conn_state_user_flag_id_t	ble_conn_state_user_flag_acquire (void)
	Function for obtaining exclusive access to one of the user flag collections. More...
bool	ble_conn_state_user_flag_get (uint16_t conn_handle, ble_conn_state_user_flag_id_t flag_id)
	Function for reading the value of a user flag. More...
void	ble_conn_state_user_flag_set (uint16_t conn_handle, ble_conn_state_user_flag_id_t flag_id, bool value)
	Function for setting the value of a user flag. More...
uint32_t	ble_conn_state_for_each_connected (ble_conn_state_user_function_t user_function, void *p_context)
	Function for running a function for each active connection. More...
uint32_t	ble_conn_state_for_each_set_user_flag (ble_conn_state_user_flag_id_t flag_id, ble_conn_state_user_function_t user_function, void *p_context)
	Function for running a function for each flag that is set in a user flag collection. More...

Detailed Description

Function Documentation

uint32_t ble_conn_state_central_conn_count

(

void

)

Function for querying the total number of connections in which the role of the local device is BLE_GAP_ROLE_CENTRAL.

Returns

The number of connections in which the role of the local device is BLE_GAP_ROLE_CENTRAL.

ble_conn_state_conn_handle_list_t ble_conn_state_central_handles

(

void

)

Function for obtaining a list of connection handles in which the role of the local device is BLE_GAP_ROLE_CENTRAL.

This function takes into account connections whose state is BLE_CONN_STATUS_DISCONNECTED.

Returns

A list of all valid connection handles for which the module has a record and in which the role of local device is BLE_GAP_ROLE_CENTRAL.

uint32_t ble_conn_state_conn_count

(

void

)

Function for querying the total number of connections.

Returns

The total number of valid connections for which the module has a record.

ble_conn_state_conn_handle_list_t ble_conn_state_conn_handles

(

void

)

Function for obtaining a list of all connection handles for which the module has a record.

This function takes into account connections whose state is BLE_CONN_STATUS_DISCONNECTED.

Returns

A list of all valid connection handles for which the module has a record.

uint16_t ble_conn_state_conn_idx

(

uint16_t

conn_handle

)

Function for translating a connection handle to a value that can be used as an array index.

Function for mapping connection handles onto the range <0 - MAX_CONNECTIONS>.

Note

The index will be the same as long as a connection is invalid. A subsequent connection with the same connection handle might have a different index.

Parameters

[in]

conn_handle

The connection for which to retrieve an index.

Returns

An index unique to this connection. Or BLE_CONN_STATE_MAX_CONNECTIONS if conn_handle refers to an invalid connection.

bool ble_conn_state_encrypted

(

uint16_t

conn_handle

)

Function for querying whether a connection is encrypted.

Parameters

[in]

conn_handle

Handle of connection to get the encryption state for.

Return values

true	If the connection is encrypted.
false	If the connection is not encrypted or conn_handle is invalid.

uint32_t ble_conn_state_for_each_connected	(	ble_conn_state_user_function_t	user_function,
		void *	p_context
	)

Function for running a function for each active connection.

Parameters

[in]	user_function	The function to run for each connection.
[in]	p_context	Arbitrary context to be passed to user_function.

Returns

The number of times user_function was run.

uint32_t ble_conn_state_for_each_set_user_flag	(	ble_conn_state_user_flag_id_t	flag_id,
		ble_conn_state_user_function_t	user_function,
		void *	p_context
	)

Function for running a function for each flag that is set in a user flag collection.

Parameters

[in]	flag_id	Which flags to check.
[in]	user_function	The function to run when a flag is set.
[in]	p_context	Arbitrary context to be passed to user_function.

Returns

The number of times user_function was run.

void ble_conn_state_init

(

void

)

Function for initializing or resetting the module.

This function sets all states to their default, removing all records of connection handles.

bool ble_conn_state_lesc

(

uint16_t

conn_handle

)

Function for querying whether a connection was bonded using LE Secure Connections (LESC).

The connection must currently be encrypted.

Note

This function will report false if bonded, and the LESC bonding was unauthenticated ("Just Works") and happened in a previous connection. To detect such cases as well, check the stored bonding key, e.g. in Peer Manager, which has a LESC flag associated with it.

Parameters

[in]

conn_handle

Handle of connection to get the LESC state for.

Return values

true	If the connection was bonded using LESC.
false	If the connection has not been bonded using LESC, or conn_handle is invalid.

bool ble_conn_state_mitm_protected

(

uint16_t

conn_handle

)

Function for querying whether a connection encryption is protected from Man in the Middle attacks.

Parameters

[in]

conn_handle

Handle of connection to get the MITM state for.

Return values

true	If the connection is encrypted with MITM protection.
false	If the connection is not encrypted, or encryption is not MITM protected, or conn_handle is invalid.

ble_conn_state_conn_handle_list_t ble_conn_state_periph_handles

(

void

)

Function for obtaining the handle for the connection in which the role of the local device is BLE_GAP_ROLE_PERIPH.

This function takes into account connections whose state is BLE_CONN_STATUS_DISCONNECTED.

Returns

A list of all valid connection handles for which the module has a record and in which the role of local device is BLE_GAP_ROLE_PERIPH.

uint32_t ble_conn_state_peripheral_conn_count

(

void

)

Function for querying the total number of connections in which the role of the local device is BLE_GAP_ROLE_PERIPH.

Returns

The number of connections in which the role of the local device is BLE_GAP_ROLE_PERIPH.

uint8_t ble_conn_state_role

(

uint16_t

conn_handle

)

Function for querying the role of the local device in a connection.

Parameters

[in]

conn_handle

Handle of the connection to get the role for.

Returns

The role of the local device in the connection (see GAP Roles). If conn_handle is not valid, the function returns BLE_GAP_ROLE_INVALID.

ble_conn_state_status_t ble_conn_state_status

(

uint16_t

conn_handle

)

Function for querying the status of a connection.

Parameters

[in]

conn_handle

Handle of the connection.

Returns

The status of the connection. If conn_handle is not valid, the function returns BLE_CONN_STATE_INVALID.

ble_conn_state_user_flag_id_t ble_conn_state_user_flag_acquire

(

void

)

Function for obtaining exclusive access to one of the user flag collections.

The acquired collection contains one flag for each connection. These flags can be set and read individually for each connection.

The state of user flags will not be modified by the connection state module, except to set it to 0 for a connection when that connection is invalidated.

Returns

The ID of the acquired flag, or BLE_CONN_STATE_USER_FLAG_INVALID if none are available.

bool ble_conn_state_user_flag_get	(	uint16_t	conn_handle,
		ble_conn_state_user_flag_id_t	flag_id
	)

Function for reading the value of a user flag.

Parameters

[in]	conn_handle	Handle of connection to get the flag state for.
[in]	flag_id	Which flag to get the state for.

Returns

The state of the flag. If conn_handle is invalid, the function returns false.

void ble_conn_state_user_flag_set	(	uint16_t	conn_handle,
		ble_conn_state_user_flag_id_t	flag_id,
		bool	value
	)

Function for setting the value of a user flag.

Parameters

[in]	conn_handle	Handle of connection to set the flag state for.
[in]	flag_id	Which flag to set the state for.
[in]	value	Value to set the flag state to.

bool ble_conn_state_valid

(

uint16_t

conn_handle

)

Function for querying whether a connection handle represents a valid connection.

A connection might be valid and have a BLE_CONN_STATUS_DISCONNECTED status. Those connections are invalidated after a new connection occurs.

Parameters

[in]

conn_handle

Handle of the connection.

Return values

true	If conn_handle represents a valid connection, thus a connection for which we have a record.
false	If conn_handle is BLE_GAP_ROLE_INVALID, or if it has never been recorded.