gatt.h

Go to the documentation of this file.

 
/*
 * Copyright (c) 2015-2016 Intel Corporation
 *
 * SPDX-License-Identifier: Apache-2.0
 */
#ifndef ZEPHYR_INCLUDE_BLUETOOTH_GATT_H_
#define ZEPHYR_INCLUDE_BLUETOOTH_GATT_H_
 
#include <stdint.h>
#include <stddef.h>
 
#include <sys/types.h>
 
#include <zephyr/sys/slist.h>
#include <zephyr/sys/util.h>
#include <zephyr/bluetooth/conn.h>
#include <zephyr/bluetooth/uuid.h>
#include <zephyr/bluetooth/att.h>
#include <zephyr/sys/iterable_sections.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
enum bt_gatt_perm {
        BT_GATT_PERM_NONE = 0,
 
        BT_GATT_PERM_READ = BIT(0),
 
        BT_GATT_PERM_WRITE = BIT(1),
 
        BT_GATT_PERM_READ_ENCRYPT = BIT(2),
 
        BT_GATT_PERM_WRITE_ENCRYPT = BIT(3),
 
        BT_GATT_PERM_READ_AUTHEN = BIT(4),
 
        BT_GATT_PERM_WRITE_AUTHEN = BIT(5),
 
        BT_GATT_PERM_PREPARE_WRITE = BIT(6),
 
        BT_GATT_PERM_READ_LESC = BIT(7),
 
        BT_GATT_PERM_WRITE_LESC = BIT(8),
};
 
#define BT_GATT_ERR(_att_err) (-(_att_err))
 
enum bt_gatt_attr_write_flag {
        BT_GATT_WRITE_FLAG_PREPARE = BIT(0),
 
        BT_GATT_WRITE_FLAG_CMD = BIT(1),
 
        BT_GATT_WRITE_FLAG_EXECUTE = BIT(2),
};
 
/* Forward declaration of GATT Attribute structure */
struct bt_gatt_attr;
 
typedef ssize_t (*bt_gatt_attr_read_func_t)(struct bt_conn *conn,
                                            const struct bt_gatt_attr *attr,
                                            void *buf, uint16_t len,
                                            uint16_t offset);
 
typedef ssize_t (*bt_gatt_attr_write_func_t)(struct bt_conn *conn,
                                             const struct bt_gatt_attr *attr,
                                             const void *buf, uint16_t len,
                                             uint16_t offset, uint8_t flags);
 
struct bt_gatt_attr {
        const struct bt_uuid *uuid;
 
        bt_gatt_attr_read_func_t read;
 
        bt_gatt_attr_write_func_t write;
 
        void *user_data;
 
        uint16_t handle;
 
        uint16_t perm: 15;
 
        bool _auto_assigned_handle: 1;
};
 
struct bt_gatt_service_static {
        const struct bt_gatt_attr *attrs;
        size_t attr_count;
};
 
struct bt_gatt_service {
        struct bt_gatt_attr *attrs;
        size_t attr_count;
        sys_snode_t node;
};
 
struct bt_gatt_service_val {
        const struct bt_uuid *uuid;
        uint16_t end_handle;
};
 
struct bt_gatt_include {
        const struct bt_uuid *uuid;
        uint16_t start_handle;
        uint16_t end_handle;
};
 
struct bt_gatt_cb {
        void (*att_mtu_updated)(struct bt_conn *conn, uint16_t tx, uint16_t rx);
 
        sys_snode_t node;
};
 
struct bt_gatt_authorization_cb {
        bool (*read_authorize)(struct bt_conn *conn,
                               const struct bt_gatt_attr *attr);
 
        bool (*write_authorize)(struct bt_conn *conn,
                                const struct bt_gatt_attr *attr);
};
 
#define BT_GATT_CHRC_BROADCAST                  0x01
#define BT_GATT_CHRC_READ                       0x02
#define BT_GATT_CHRC_WRITE_WITHOUT_RESP         0x04
#define BT_GATT_CHRC_WRITE                      0x08
#define BT_GATT_CHRC_NOTIFY                     0x10
#define BT_GATT_CHRC_INDICATE                   0x20
#define BT_GATT_CHRC_AUTH                       0x40
#define BT_GATT_CHRC_EXT_PROP                   0x80
 
struct bt_gatt_chrc {
        const struct bt_uuid *uuid;
        uint16_t value_handle;
        uint8_t properties;
};
 
#define BT_GATT_CEP_RELIABLE_WRITE              0x0001
#define BT_GATT_CEP_WRITABLE_AUX                0x0002
 
struct bt_gatt_cep {
        uint16_t properties;
};
 
#define BT_GATT_CCC_NOTIFY                      0x0001
#define BT_GATT_CCC_INDICATE                    0x0002
 
struct bt_gatt_ccc {
        uint16_t flags;
};
 
#define BT_GATT_SCC_BROADCAST                   0x0001
 
struct bt_gatt_scc {
        uint16_t flags;
};
 
struct bt_gatt_cpf {
        uint8_t format;
        int8_t exponent;
        uint16_t unit;
        uint8_t name_space;
        uint16_t description;
};
 
static inline const char *bt_gatt_err_to_str(int gatt_err)
{
        return bt_att_err_to_str((gatt_err) < 0 ? -(gatt_err) : (gatt_err));
}
 
void bt_gatt_cb_register(struct bt_gatt_cb *cb);
 
int bt_gatt_authorization_cb_register(const struct bt_gatt_authorization_cb *cb);
 
int bt_gatt_service_register(struct bt_gatt_service *svc);
 
int bt_gatt_service_unregister(struct bt_gatt_service *svc);
 
bool bt_gatt_service_is_registered(const struct bt_gatt_service *svc);
 
enum {
        BT_GATT_ITER_STOP = 0,
        BT_GATT_ITER_CONTINUE,
};
 
typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
                                       uint16_t handle,
                                       void *user_data);
 
void bt_gatt_foreach_attr_type(uint16_t start_handle, uint16_t end_handle,
                               const struct bt_uuid *uuid,
                               const void *attr_data, uint16_t num_matches,
                               bt_gatt_attr_func_t func,
                               void *user_data);
 
static inline void bt_gatt_foreach_attr(uint16_t start_handle, uint16_t end_handle,
                                        bt_gatt_attr_func_t func,
                                        void *user_data)
{
        bt_gatt_foreach_attr_type(start_handle, end_handle, NULL, NULL, 0, func,
                                  user_data);
}
 
struct bt_gatt_attr *bt_gatt_attr_next(const struct bt_gatt_attr *attr);
 
struct bt_gatt_attr *bt_gatt_find_by_uuid(const struct bt_gatt_attr *attr,
                                          uint16_t attr_count,
                                          const struct bt_uuid *uuid);
 
uint16_t bt_gatt_attr_get_handle(const struct bt_gatt_attr *attr);
 
uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr);
 
ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
                          void *buf, uint16_t buf_len, uint16_t offset,
                          const void *value, uint16_t value_len);
 
ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
                                  const struct bt_gatt_attr *attr,
                                  void *buf, uint16_t len, uint16_t offset);
 
#define BT_GATT_SERVICE_DEFINE(_name, ...)                              \
        const struct bt_gatt_attr attr_##_name[] = { __VA_ARGS__ };     \
        const STRUCT_SECTION_ITERABLE(bt_gatt_service_static, _name) =  \
                                        BT_GATT_SERVICE(attr_##_name)
 
#define _BT_GATT_ATTRS_ARRAY_DEFINE(n, _instances, _attrs_def)  \
        static struct bt_gatt_attr attrs_##n[] = _attrs_def(_instances[n])
 
#define _BT_GATT_SERVICE_ARRAY_ITEM(_n, _) BT_GATT_SERVICE(attrs_##_n)
 
#define BT_GATT_SERVICE_INSTANCE_DEFINE(                                 \
        _name, _instances, _instance_num, _attrs_def)                    \
        BUILD_ASSERT(ARRAY_SIZE(_instances) == _instance_num,            \
                "The number of array elements does not match its size"); \
        LISTIFY(_instance_num, _BT_GATT_ATTRS_ARRAY_DEFINE, (;),         \
                _instances, _attrs_def);                                 \
        static struct bt_gatt_service _name[] = {                        \
                LISTIFY(_instance_num, _BT_GATT_SERVICE_ARRAY_ITEM, (,)) \
        }
 
#define BT_GATT_SERVICE(_attrs)                                         \
{                                                                       \
        .attrs = _attrs,                                                \
        .attr_count = ARRAY_SIZE(_attrs),                               \
}
 
#define BT_GATT_PRIMARY_SERVICE(_service)                               \
        BT_GATT_ATTRIBUTE(BT_UUID_GATT_PRIMARY, BT_GATT_PERM_READ,      \
                         bt_gatt_attr_read_service, NULL, (void *)_service)
 
#define BT_GATT_SECONDARY_SERVICE(_service)                             \
        BT_GATT_ATTRIBUTE(BT_UUID_GATT_SECONDARY, BT_GATT_PERM_READ,    \
                         bt_gatt_attr_read_service, NULL, (void *)_service)
 
ssize_t bt_gatt_attr_read_included(struct bt_conn *conn,
                                   const struct bt_gatt_attr *attr,
                                   void *buf, uint16_t len, uint16_t offset);
 
#define BT_GATT_INCLUDE_SERVICE(_service_incl)                          \
        BT_GATT_ATTRIBUTE(BT_UUID_GATT_INCLUDE, BT_GATT_PERM_READ,      \
                          bt_gatt_attr_read_included, NULL, _service_incl)
 
ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
                               const struct bt_gatt_attr *attr, void *buf,
                               uint16_t len, uint16_t offset);
 
#define BT_GATT_CHRC_INIT(_uuid, _handle, _props) \
{                                                 \
        .uuid = _uuid,                            \
        .value_handle = _handle,                  \
        .properties = _props,                     \
}
 
#define BT_GATT_CHARACTERISTIC(_uuid, _props, _perm, _read, _write, _user_data) \
        BT_GATT_ATTRIBUTE(BT_UUID_GATT_CHRC, BT_GATT_PERM_READ,                 \
                          bt_gatt_attr_read_chrc, NULL,                         \
                          ((struct bt_gatt_chrc[]) {                            \
                                BT_GATT_CHRC_INIT(_uuid, 0U, _props),           \
                                                   })),                         \
        BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data)
 
#if defined(CONFIG_BT_SETTINGS_CCC_LAZY_LOADING)
        #define BT_GATT_CCC_MAX (CONFIG_BT_MAX_CONN)
#elif defined(CONFIG_BT_CONN)
        #define BT_GATT_CCC_MAX (CONFIG_BT_MAX_PAIRED + CONFIG_BT_MAX_CONN)
#else
        #define BT_GATT_CCC_MAX 0
#endif
 
struct bt_gatt_ccc_cfg {
        uint8_t id;
        bt_addr_le_t peer;
        uint16_t value;
};
 
struct _bt_gatt_ccc {
        struct bt_gatt_ccc_cfg cfg[BT_GATT_CCC_MAX];
 
        uint16_t value;
 
        void (*cfg_changed)(const struct bt_gatt_attr *attr, uint16_t value);
 
        ssize_t (*cfg_write)(struct bt_conn *conn,
                             const struct bt_gatt_attr *attr, uint16_t value);
 
        bool (*cfg_match)(struct bt_conn *conn,
                          const struct bt_gatt_attr *attr);
};
 
ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
                              const struct bt_gatt_attr *attr, void *buf,
                              uint16_t len, uint16_t offset);
 
ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
                               const struct bt_gatt_attr *attr, const void *buf,
                               uint16_t len, uint16_t offset, uint8_t flags);
 
#define BT_GATT_CCC_INITIALIZER(_changed, _write, _match) \
        {                                            \
                .cfg = {},                           \
                .cfg_changed = _changed,             \
                .cfg_write = _write,                 \
                .cfg_match = _match,                 \
        }
 
#define BT_GATT_CCC_MANAGED(_ccc, _perm)                                \
        BT_GATT_ATTRIBUTE(BT_UUID_GATT_CCC, _perm,                      \
                        bt_gatt_attr_read_ccc, bt_gatt_attr_write_ccc,  \
                        _ccc)
 
#define BT_GATT_CCC(_changed, _perm)                            \
        BT_GATT_CCC_MANAGED(((struct _bt_gatt_ccc[])                    \
                {BT_GATT_CCC_INITIALIZER(_changed, NULL, NULL)}), _perm)
 
ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn,
                              const struct bt_gatt_attr *attr, void *buf,
                              uint16_t len, uint16_t offset);
 
#define BT_GATT_CEP(_value)                                             \
        BT_GATT_DESCRIPTOR(BT_UUID_GATT_CEP, BT_GATT_PERM_READ,         \
                          bt_gatt_attr_read_cep, NULL, (void *)_value)
 
ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn,
                              const struct bt_gatt_attr *attr, void *buf,
                              uint16_t len, uint16_t offset);
 
#define BT_GATT_CUD(_value, _perm)                                      \
        BT_GATT_DESCRIPTOR(BT_UUID_GATT_CUD, _perm, bt_gatt_attr_read_cud, \
                           NULL, (void *)_value)
 
ssize_t bt_gatt_attr_read_cpf(struct bt_conn *conn,
                              const struct bt_gatt_attr *attr, void *buf,
                              uint16_t len, uint16_t offset);
 
#define BT_GATT_CPF(_value)                                             \
        BT_GATT_DESCRIPTOR(BT_UUID_GATT_CPF, BT_GATT_PERM_READ,         \
                          bt_gatt_attr_read_cpf, NULL, (void *)_value)
 
#define BT_GATT_DESCRIPTOR(_uuid, _perm, _read, _write, _user_data)     \
        BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data)
 
#define BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data)      \
{                                                                       \
        .uuid = _uuid,                                                  \
        .read = _read,                                                  \
        .write = _write,                                                \
        .user_data = _user_data,                                        \
        .handle = 0,                                                    \
        .perm = _perm,                                                  \
}
 
typedef void (*bt_gatt_complete_func_t) (struct bt_conn *conn, void *user_data);
 
struct bt_gatt_notify_params {
        const struct bt_uuid *uuid;
        const struct bt_gatt_attr *attr;
        const void *data;
        uint16_t len;
        bt_gatt_complete_func_t func;
        void *user_data;
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
        enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
 
int bt_gatt_notify_cb(struct bt_conn *conn,
                      struct bt_gatt_notify_params *params);
 
int bt_gatt_notify_multiple(struct bt_conn *conn,
                            uint16_t num_params,
                            struct bt_gatt_notify_params params[]);
 
static inline int bt_gatt_notify(struct bt_conn *conn,
                                 const struct bt_gatt_attr *attr,
                                 const void *data, uint16_t len)
{
        struct bt_gatt_notify_params params;
 
        memset(&params, 0, sizeof(params));
 
        params.attr = attr;
        params.data = data;
        params.len = len;
#if defined(CONFIG_BT_EATT)
        params.chan_opt = BT_ATT_CHAN_OPT_NONE;
#endif /* CONFIG_BT_EATT */
 
        return bt_gatt_notify_cb(conn, &params);
}
 
static inline int bt_gatt_notify_uuid(struct bt_conn *conn,
                                      const struct bt_uuid *uuid,
                                      const struct bt_gatt_attr *attr,
                                      const void *data, uint16_t len)
{
        struct bt_gatt_notify_params params;
 
        memset(&params, 0, sizeof(params));
 
        params.uuid = uuid;
        params.attr = attr;
        params.data = data;
        params.len = len;
#if defined(CONFIG_BT_EATT)
        params.chan_opt = BT_ATT_CHAN_OPT_NONE;
#endif /* CONFIG_BT_EATT */
 
        return bt_gatt_notify_cb(conn, &params);
}
 
/* Forward declaration of the bt_gatt_indicate_params structure */
struct bt_gatt_indicate_params;
 
typedef void (*bt_gatt_indicate_func_t)(struct bt_conn *conn,
                                        struct bt_gatt_indicate_params *params,
                                        uint8_t err);
 
typedef void (*bt_gatt_indicate_params_destroy_t)(
                struct bt_gatt_indicate_params *params);
 
struct bt_gatt_indicate_params {
        const struct bt_uuid *uuid;
        const struct bt_gatt_attr *attr;
        bt_gatt_indicate_func_t func;
        bt_gatt_indicate_params_destroy_t destroy;
        const void *data;
        uint16_t len;
        uint8_t _ref;
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
        enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
 
int bt_gatt_indicate(struct bt_conn *conn,
                     struct bt_gatt_indicate_params *params);
 
bool bt_gatt_is_subscribed(struct bt_conn *conn,
                           const struct bt_gatt_attr *attr, uint16_t ccc_type);
 
uint16_t bt_gatt_get_mtu(struct bt_conn *conn);
 
uint16_t bt_gatt_get_uatt_mtu(struct bt_conn *conn);
 
struct bt_gatt_exchange_params {
        void (*func)(struct bt_conn *conn, uint8_t err,
                     struct bt_gatt_exchange_params *params);
};
 
int bt_gatt_exchange_mtu(struct bt_conn *conn,
                         struct bt_gatt_exchange_params *params);
 
struct bt_gatt_discover_params;
 
typedef uint8_t (*bt_gatt_discover_func_t)(struct bt_conn *conn,
                                        const struct bt_gatt_attr *attr,
                                        struct bt_gatt_discover_params *params);
 
enum bt_gatt_discover_type {
        BT_GATT_DISCOVER_PRIMARY,
        BT_GATT_DISCOVER_SECONDARY,
        BT_GATT_DISCOVER_INCLUDE,
        BT_GATT_DISCOVER_CHARACTERISTIC,
        BT_GATT_DISCOVER_DESCRIPTOR,
        BT_GATT_DISCOVER_ATTRIBUTE,
        BT_GATT_DISCOVER_STD_CHAR_DESC,
};
 
#define BT_GATT_AUTO_DISCOVER_CCC_HANDLE 0x0000U
 
struct bt_gatt_discover_params {
        const struct bt_uuid *uuid;
        bt_gatt_discover_func_t func;
        union {
                struct {
                        uint16_t attr_handle;
                        uint16_t start_handle;
                        uint16_t end_handle;
                } _included;
                uint16_t start_handle;
        };
        uint16_t end_handle;
        uint8_t type;
#if defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__)
        struct bt_gatt_subscribe_params *sub_params;
#endif /* defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__) */
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
        enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
 
int bt_gatt_discover(struct bt_conn *conn,
                     struct bt_gatt_discover_params *params);
 
struct bt_gatt_read_params;
 
typedef uint8_t (*bt_gatt_read_func_t)(struct bt_conn *conn, uint8_t err,
                                    struct bt_gatt_read_params *params,
                                    const void *data, uint16_t length);
 
struct bt_gatt_read_params {
        bt_gatt_read_func_t func;
        size_t handle_count;
        union {
                struct {
                        uint16_t handle;
                        uint16_t offset;
                } single;
                struct {
                        uint16_t *handles;
                        bool variable;
                } multiple;
                struct {
                        uint16_t start_handle;
                        uint16_t end_handle;
                        const struct bt_uuid *uuid;
                } by_uuid;
        };
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
        enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
        uint16_t _att_mtu;
};
 
int bt_gatt_read(struct bt_conn *conn, struct bt_gatt_read_params *params);
 
struct bt_gatt_write_params;
 
typedef void (*bt_gatt_write_func_t)(struct bt_conn *conn, uint8_t err,
                                     struct bt_gatt_write_params *params);
 
struct bt_gatt_write_params {
        bt_gatt_write_func_t func;
        uint16_t handle;
        uint16_t offset;
        const void *data;
        uint16_t length;
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
        enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
 
int bt_gatt_write(struct bt_conn *conn, struct bt_gatt_write_params *params);
 
int bt_gatt_write_without_response_cb(struct bt_conn *conn, uint16_t handle,
                                      const void *data, uint16_t length,
                                      bool sign, bt_gatt_complete_func_t func,
                                      void *user_data);
 
static inline int bt_gatt_write_without_response(struct bt_conn *conn,
                                                 uint16_t handle, const void *data,
                                                 uint16_t length, bool sign)
{
        return bt_gatt_write_without_response_cb(conn, handle, data, length,
                                                 sign, NULL, NULL);
}
 
struct bt_gatt_subscribe_params;
 
typedef uint8_t (*bt_gatt_notify_func_t)(struct bt_conn *conn,
                                      struct bt_gatt_subscribe_params *params,
                                      const void *data, uint16_t length);
 
typedef void (*bt_gatt_subscribe_func_t)(struct bt_conn *conn, uint8_t err,
                                         struct bt_gatt_subscribe_params *params);
 
enum bt_gatt_sub_flag {
        BT_GATT_SUBSCRIBE_FLAG_VOLATILE,
 
        BT_GATT_SUBSCRIBE_FLAG_NO_RESUB,
 
        BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING,
 
        BT_GATT_SUBSCRIBE_FLAG_SENT,
 
        BT_GATT_SUBSCRIBE_NUM_FLAGS
};
 
struct bt_gatt_subscribe_params {
        bt_gatt_notify_func_t notify;
        bt_gatt_subscribe_func_t subscribe;
 
        uint16_t value_handle;
        uint16_t ccc_handle;
#if defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__)
        uint16_t end_handle;
        struct bt_gatt_discover_params *disc_params;
#endif /* defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__) */
        uint16_t value;
#if defined(CONFIG_BT_SMP)
        bt_security_t min_security;
#endif
        ATOMIC_DEFINE(flags, BT_GATT_SUBSCRIBE_NUM_FLAGS);
 
        sys_snode_t node;
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
        enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
 
int bt_gatt_subscribe(struct bt_conn *conn,
                      struct bt_gatt_subscribe_params *params);
 
int bt_gatt_resubscribe(uint8_t id, const bt_addr_le_t *peer,
                        struct bt_gatt_subscribe_params *params);
 
int bt_gatt_unsubscribe(struct bt_conn *conn,
                        struct bt_gatt_subscribe_params *params);
 
void bt_gatt_cancel(struct bt_conn *conn, void *params);
 
#ifdef __cplusplus
}
#endif
 
#endif /* ZEPHYR_INCLUDE_BLUETOOTH_GATT_H_ */