Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bluetooth: Host: improve GATT documentation #86359

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+71 −9
Open

Bluetooth: Host: improve GATT documentation #86359

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 71 additions & 9 deletions include/zephyr/bluetooth/gatt.h
View file
Open in desktop
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,7 @@ 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 0xFFFF.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could consider referring to BT_ATT_LAST_ATTRIBUTE_HANDLE instead of 0xFFFF

* @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 +896,17 @@ 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.
Comment on lines +899 to +900
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The style in this file seems to be to have @brief on the same line as /**

*
* 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,7 +1023,10 @@ struct _bt_gatt_ccc {
* Read CCC attribute value from local database storing the result into buffer
* after encoding it.
*
* \internal
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
* _bt_gatt_ccc being the internal representation of CCC value.
* \endinternal
Comment on lines +1026 to +1029
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AFAIK the way to make things internal is to use @cond INTERNAL_HIDDEN + @endcond. @kartben please verify

*
* @param conn Connection object.
* @param attr Attribute to read.
Expand All @@ -1009,7 +1045,10 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
*
* Write value in the buffer into CCC attribute.
*
* \internal
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
* _bt_gatt_ccc being the internal representation of CCC value.
* \endinternal
*
* @param conn Connection object.
* @param attr Attribute to read.
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,11 @@ 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.
*
*/
Comment on lines +1256 to +1258
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* See also @ref bt_gatt_notify_cb and @ref bt_gatt_notify_multiple, using this parameter.
*
*/
* 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 @@ -1234,6 +1278,7 @@ struct bt_gatt_notify_params {
/** Notification Value callback user data */
void *user_data;
#if defined(CONFIG_BT_EATT)
/** Att channel options. Only available if @kconfig{CONFIG_BT_EATT} is set. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down Expand Up @@ -1407,10 +1452,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 @@ -1435,6 +1492,7 @@ struct bt_gatt_indicate_params {
/** Private reference counter */
uint8_t _ref;
#if defined(CONFIG_BT_EATT)
/** Att channel options. Only available if @kconfig{CONFIG_BT_EATT} is set. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down Expand Up @@ -1470,7 +1528,7 @@ int bt_gatt_indicate(struct bt_conn *conn,

/** @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 @@ -1686,6 +1744,7 @@ struct bt_gatt_discover_params {
struct bt_gatt_subscribe_params *sub_params;
#endif /* defined(CONFIG_BT_GATT_AUTO_DISCOVER_CCC) || defined(__DOXYGEN__) */
#if defined(CONFIG_BT_EATT)
/** Att channel options. Only available if @kconfig{CONFIG_BT_EATT} is set. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
Comment on lines 1746 to 1749
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe outside the scope of this PR, but AFAIk we need to do something like

#if defined(CONFIG_BT_EATT) || defined(__DOXYGEN__)

to ensure that they are in the Doxygen documentation when they are otherwise guarded. @kartben please verify

};
Expand Down Expand Up @@ -1793,6 +1852,7 @@ struct bt_gatt_read_params {
} by_uuid;
};
#if defined(CONFIG_BT_EATT)
/** Att channel options. Only available if @kconfig{CONFIG_BT_EATT} is set. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
/** Internal */
Expand Down Expand Up @@ -1868,6 +1928,7 @@ struct bt_gatt_write_params {
/** Length of the data */
uint16_t length;
#if defined(CONFIG_BT_EATT)
/** Att channel options. Only available if @kconfig{CONFIG_BT_EATT} is set. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down Expand Up @@ -2076,6 +2137,7 @@ struct bt_gatt_subscribe_params {

sys_snode_t node;
#if defined(CONFIG_BT_EATT)
/** Att channel options. Only available if @kconfig{CONFIG_BT_EATT} is set. */
enum bt_att_chan_opt chan_opt;
#endif /* CONFIG_BT_EATT */
};
Expand Down
Loading