Bluetooth connection context

Data related to a Bluetooth® connection can be stored in a Bluetooth connection context. You can use this library with Bluetooth Low Energy (LE) services that require the connection context to support multilink functionality for the GATT server role.

Each instance of the library can store the contexts for a configurable number of Bluetooth connections (see Connection Management in the Zephyr documentation).

The GATT Human Interface Device (HID) Service shows how to use this library.

API documentation

Header file: include/bluetooth/conn_ctx.h
Source file: subsys/bluetooth/conn_ctx.c
group bt_conn_ctx

API for the Bluetooth connection context library.

Defines

BT_CONN_CTX_DEF(_name, _max_clients, _ctx_sz)

Macro for defining a Bluetooth connection context library instance.

Parameters:

  • _name – Name of the instance.

  • _max_clients – Maximum number of clients connected at a time.

  • _ctx_sz – Context size in bytes for a single connection.

Functions

static inline size_t bt_conn_ctx_block_size_get(struct bt_conn_ctx_lib *ctx_lib)

Get the block size.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

Returns:

Block size in bytes.

static inline size_t bt_conn_ctx_count(struct bt_conn_ctx_lib *ctx_lib)

Get the number of connection contexts that are managed by the library.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

Returns:

Number of connection contexts that are managed by the library.

void *bt_conn_ctx_alloc(struct bt_conn_ctx_lib *ctx_lib, struct bt_conn *conn)

Allocate memory for the connection context data.

This function can set the pointer to the allocated memory.

This function should be used in conjunction with bt_conn_ctx_release to ensure proper operation.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

  • conn – Bluetooth connection.

Returns:

Pointer to the connection context data if the operation was successful. Otherwise NULL.

int bt_conn_ctx_free(struct bt_conn_ctx_lib *ctx_lib, struct bt_conn *conn)

Free the allocated memory for a connection.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

  • conn – Bluetooth connection.

Return values:

0 – If the operation was successful. Otherwise, a (negative) error code is returned.

void bt_conn_ctx_free_all(struct bt_conn_ctx_lib *ctx_lib)

Free all allocated context data.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

void *bt_conn_ctx_get(struct bt_conn_ctx_lib *ctx_lib, struct bt_conn *conn)

Get the context data of a connection from the memory pool.

This function finds a connection’s context data in the memory pool. The link to find is identified by the connection object.

This function should be used in conjunction with bt_conn_ctx_release to ensure proper operation.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

  • conn – Bluetooth connection.

Returns:

Pointer to the connection context data if the operation was successful. Otherwise NULL.

const struct bt_conn_ctx *bt_conn_ctx_get_by_id(struct bt_conn_ctx_lib *ctx_lib, uint8_t id)

Get a specific connection context from the memory pool.

This function finds the connection context and the associated connection object in the memory pool. The link to find is identified by its index in the connection context array.

This function should be used in conjunction with bt_conn_ctx_release to ensure proper operation.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

  • id – Connection context index.

Returns:

Pointer to the Bluetooth connection context library API struct if the operation was successful. Otherwise NULL.

void bt_conn_ctx_release(struct bt_conn_ctx_lib *ctx_lib, void *data)

Release a connection context from the memory pool.

This function finds and releases a connection context in the memory pool. The link to find is identified by its context data.

This function should be used in conjunction with bt_conn_ctx_alloc, bt_conn_ctx_get, or bt_conn_ctx_get_by_id to ensure proper operation.

Parameters:

  • ctx_lib – Bluetooth connection context library instance.

  • data – Context data for the connection.

struct bt_conn_ctx
#include <conn_ctx.h>

Context data for a connection.

Public Members

void *data

Any kind of data associated with a specific connection.

struct bt_conn *conn

The connection that the data is associated with.

struct bt_conn_ctx_lib
#include <conn_ctx.h>

Bluetooth connection context library structure.

Public Members

struct bt_conn_ctx ctx[CONFIG_BT_MAX_CONN]

Connection contexts.

struct k_mutex *const mutex

Context data mutex that ensures that only one connection context is manipulated at a time.

struct k_mem_slab *const mem_slab

Memory slab instance where the memory is allocated.