Skip to content

Commit

Permalink
Bluetooth: Host: improve GATT documentation
Browse files Browse the repository at this point in the history 
The gatt docs are very sparce, this commit adds imrpovements for the
GATT server API part. Others will follow.

Signed-off-by: Kyra Lengfeld <[email protected]>
  • Loading branch information
@KyraLengfeld
KyraLengfeld committed Feb 27, 2025
1 parent 3fa0cd5 commit b1f070a
Showing 1 changed file with 80 additions and 20 deletions.
100 changes: 80 additions & 20 deletions include/zephyr/bluetooth/gatt.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -573,14 +573,14 @@ void bt_gatt_cb_register(struct bt_gatt_cb *cb);
*
* @param cb Callback struct.
*
* @return Zero on success or negative error code otherwise
* @return Zero on success or negative error code otherwise.
*/
int bt_gatt_authorization_cb_register(const struct bt_gatt_authorization_cb *cb);

/** @brief Register GATT service.
*
* Register GATT service. Applications can make use of
* macros such as ``BT_GATT_PRIMARY_SERVICE``, ``BT_GATT_CHARACTERISTIC``,
* To register a GATT service, applications can make use of macros such as
* ``BT_GATT_PRIMARY_SERVICE``, ``BT_GATT_CHARACTERISTIC``,
* ``BT_GATT_DESCRIPTOR``, etc.
*
* When using @kconfig{CONFIG_BT_SETTINGS} then all services that should have
Expand Down Expand Up @@ -621,6 +621,9 @@ int bt_gatt_service_unregister(struct bt_gatt_service *svc);
*/
bool bt_gatt_service_is_registered(const struct bt_gatt_service *svc);

/** @brief to be used as return values for @ref bt_gatt_attr_func_t and @ref bt_gatt_read_func_t
* type callbacks.
*/
enum {
BT_GATT_ITER_STOP = 0,
BT_GATT_ITER_CONTINUE,
Expand All @@ -645,7 +648,8 @@ typedef uint8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
* Iterate attributes in the given range matching given UUID and/or data.
*
* @param start_handle Start handle.
* @param end_handle End handle.
* @param end_handle End handle. Often set to start_handle + attr_count or
* BT_ATT_LAST_ATTRIBUTE_HANDLE.
* @param uuid UUID to match, passing NULL skips UUID matching.
* @param attr_data Attribute data to match, passing NULL skips data matching.
* @param num_matches Number matches, passing 0 makes it unlimited.
Expand Down Expand Up @@ -893,6 +897,16 @@ 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);

/** @brief Gatt Characterisitc Initialization Macro.
*
* Helper macro used within the @ref BT_GATT_CHARACTERISTIC macro in the GATT attribute declaration
* to set the attribute user data.
*
* @param _uuid Characteristic attribute uuid.
* @param _handle Characcteristic attribute handle at init.
* @param _props Characteristic attribute properties,
* a bitmap of ``BT_GATT_CHRC_*`` macros.
*/
#define BT_GATT_CHRC_INIT(_uuid, _handle, _props) \
{ \
.uuid = _uuid, \
Expand Down Expand Up @@ -925,6 +939,17 @@ ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
})), \
BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _user_data)

/**
* @brief BT_GATT_CCC_MAX is defined depending on whether
* @kconfig{CONFIG_BT_SETTINGS_CCC_LAZY_LOADING} or @kconfig{CONFIG_BT_CONN} is set.
*
* @kconfig{CONFIG_BT_SETTINGS_CCC_LAZY_LOADING} will set BT_GATT_CCC_MAX to
* @kconfig{CONFIG_BT_MAX_CONN}
* @kconfig{CONFIG_BT_CONN} will set BT_GATT_CCC_MAX to @kconfig{CONFIG_BT_MAX_PAIRED} +
* @kconfig{CONFIG_BT_MAX_CONN}
* If neither are set, BT_GATT_CCC_MAX is 0.
*
*/
#if defined(CONFIG_BT_SETTINGS_CCC_LAZY_LOADING)
#define BT_GATT_CCC_MAX (CONFIG_BT_MAX_CONN)
#elif defined(CONFIG_BT_CONN)
Expand All @@ -933,13 +958,21 @@ ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
#define BT_GATT_CCC_MAX 0
#endif

/** @brief GATT CCC configuration entry. */
/** @brief GATT CCC configuration entry.
*
* bt_gatt_ccc_cfg is used within @ref bt_gatt_attr_read_ccc and @ref bt_gatt_attr_write_ccc to
* read and write the ccc configurations respectively.
*
*/
struct bt_gatt_ccc_cfg {
/** Local identity, BT_ID_DEFAULT in most cases. */
uint8_t id;
/** Remote peer address. */
bt_addr_le_t peer;
/** Configuration value. */
/** @brief Configuration value
* Value used to enable or disable notifications or indications for a specific
* characteristic.
*/
uint16_t value;
};

Expand Down Expand Up @@ -990,8 +1023,6 @@ struct _bt_gatt_ccc {
* Read CCC attribute value from local database storing the result into buffer
* after encoding it.
*
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
*
* @param conn Connection object.
* @param attr Attribute to read.
* @param buf Buffer to store the value read.
Expand All @@ -1001,6 +1032,11 @@ struct _bt_gatt_ccc {
* @return number of bytes read in case of success or negative values in
* case of error.
*/
/** @cond INTERNAL_HIDDEN
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
* _bt_gatt_ccc being the internal representation of CCC value.
*/
/** @endcond */
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);
Expand All @@ -1009,8 +1045,6 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
*
* Write value in the buffer into CCC attribute.
*
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
*
* @param conn Connection object.
* @param attr Attribute to read.
* @param buf Buffer to store the value read.
Expand All @@ -1021,6 +1055,11 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
* @return number of bytes written in case of success or negative values in
* case of error.
*/
/** @cond INTERNAL_HIDDEN
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
* _bt_gatt_ccc being the internal representation of CCC value.
*/
/** @endcond */
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);
Expand Down Expand Up @@ -1140,7 +1179,7 @@ ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn,
* Read CPF attribute value from local database storing the result into buffer
* after encoding it.
*
* @note Only use this with attributes which user_data is a bt_gatt_pf.
* @note Only use this with attributes which user_data is a @ref bt_gatt_cpf.
*
* @param conn Connection object
* @param attr Attribute to read
Expand Down Expand Up @@ -1212,6 +1251,10 @@ ssize_t bt_gatt_attr_read_cpf(struct bt_conn *conn,
*/
typedef void (*bt_gatt_complete_func_t) (struct bt_conn *conn, void *user_data);

/** @brief GATT notification parameters
*
* See also @ref bt_gatt_notify_cb and @ref bt_gatt_notify_multiple, using this parameter.
*/
struct bt_gatt_notify_params {
/** @brief Notification Attribute UUID type
*
Expand All @@ -1233,7 +1276,8 @@ struct bt_gatt_notify_params {
bt_gatt_complete_func_t func;
/** Notification Value callback user data */
void *user_data;
#if defined(CONFIG_BT_EATT)
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
/** Att channel options. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down Expand Up @@ -1407,10 +1451,22 @@ typedef void (*bt_gatt_indicate_func_t)(struct bt_conn *conn,
struct bt_gatt_indicate_params *params,
uint8_t err);

/** @typedef bt_gatt_indicate_params_destroy_t
* @brief Callback to destroy or clean up the GATT Indicate Value parameters.
*
* This callback function is invoked to clean up any resources associated with the
* `bt_gatt_indicate_params` structure once the GATT indication operation is completed.
*
* @param params Pointer to the GATT Indicate parameters structure to be cleaned up.
*/
typedef void (*bt_gatt_indicate_params_destroy_t)(
struct bt_gatt_indicate_params *params);

/** @brief GATT Indicate Value parameters */
/** @brief GATT Indicate Value parameters
*
* See also @ref bt_gatt_indicate, using this parameter.
*
*/
struct bt_gatt_indicate_params {
/** @brief Indicate Attribute UUID type
*
Expand All @@ -1434,7 +1490,8 @@ struct bt_gatt_indicate_params {
uint16_t len;
/** Private reference counter */
uint8_t _ref;
#if defined(CONFIG_BT_EATT)
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
/** Att channel options. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down Expand Up @@ -1467,10 +1524,9 @@ struct bt_gatt_indicate_params {
int bt_gatt_indicate(struct bt_conn *conn,
struct bt_gatt_indicate_params *params);


/** @brief Check if connection have subscribed to attribute
*
* Check if connection has subscribed to attribute value change.
* Check if the connection has subscribed to an attribute value change.
*
* The attribute object can be the so called Characteristic Declaration,
* which is usually declared with BT_GATT_CHARACTERISTIC followed
Expand Down Expand Up @@ -1685,7 +1741,8 @@ struct bt_gatt_discover_params {
/** Only for stack-internal use, used for automatic discovery. */
struct bt_gatt_subscribe_params *sub_params;
#endif /* defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__) */
#if defined(CONFIG_BT_EATT)
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
/** Att channel options. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down Expand Up @@ -1792,7 +1849,8 @@ struct bt_gatt_read_params {
const struct bt_uuid *uuid;
} by_uuid;
};
#if defined(CONFIG_BT_EATT)
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
/** Att channel options. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
/** Internal */
Expand Down Expand Up @@ -1867,7 +1925,8 @@ struct bt_gatt_write_params {
const void *data;
/** Length of the data */
uint16_t length;
#if defined(CONFIG_BT_EATT)
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
/** Att channel options. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down Expand Up @@ -2075,7 +2134,8 @@ struct bt_gatt_subscribe_params {
ATOMIC_DEFINE(flags, BT_GATT_SUBSCRIBE_NUM_FLAGS);

sys_snode_t node;
#if defined(CONFIG_BT_EATT)
#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)
/** Att channel options. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down

0 comments on commit b1f070a

Please sign in to comment.