michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Bluetooth: host: Minor header file doxygen fixes

Browse source 
Minor header file doxygen fixes:
 - Use /** @brief consistently
 - Indent all comments to the same level
 - Use @note instead of NOTE:
 - Align @note text
 - Align @return text
 - Add /** to documentation comments

Signed-off-by: Joakim Andersson <joakim.andersson@nordicsemi.no>
This commit is contained in:
Joakim Andersson 2020-03-17 10:32:20 +01:00 • committed by Johan Hedberg
commit 6339cd0c96
6 changed files with 267 additions and 263 deletions
Download patch file Download diff file Expand all files Collapse all files

67
include/bluetooth/bluetooth.h
View file

@ -45,8 +45,7 @@ extern "C" {
*/ */
#define BT_ID_DEFAULT 0 #define BT_ID_DEFAULT 0
/** /** @typedef bt_ready_cb_t
* @typedef bt_ready_cb_t
* @brief Callback for notifying that Bluetooth has been enabled. * @brief Callback for notifying that Bluetooth has been enabled.
* *
* @param err zero on success or (negative) error code otherwise. * @param err zero on success or (negative) error code otherwise.
@ -106,7 +105,7 @@ int bt_set_id_addr(const bt_addr_le_t *addr);
* identifier that some APIs expect (such as advertising parameters) is * identifier that some APIs expect (such as advertising parameters) is
* simply the index of the identity in the @a addrs array. * simply the index of the identity in the @a addrs array.
* *
* Note: Deleted identities may show up as BT_LE_ADDR_ANY in the returned * @note Deleted identities may show up as BT_LE_ADDR_ANY in the returned
* array. * array.
* *
* @param addrs Array where to store the configured identities. * @param addrs Array where to store the configured identities.
@ -165,7 +164,7 @@ int bt_id_create(bt_addr_le_t *addr, u8_t *irk);
* a new identity in the same slot, based on the @a addr and @a irk * a new identity in the same slot, based on the @a addr and @a irk
* parameters. * parameters.
* *
* Note: the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this * @note the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this
* API will return an error if asked to do that. * API will return an error if asked to do that.
* *
* @param id Existing identity identifier. * @param id Existing identity identifier.
@ -195,7 +194,7 @@ int bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_t *irk);
* operations. To take back into use the slot the identity was occupying the * operations. To take back into use the slot the identity was occupying the
* bt_id_reset() API needs to be used. * bt_id_reset() API needs to be used.
* *
* Note: the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this * @note the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this
* API will return an error if asked to do that. * API will return an error if asked to do that.
* *
* @param id Existing identity identifier. * @param id Existing identity identifier.
@ -204,7 +203,7 @@ int bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_t *irk);
*/ */
int bt_id_delete(u8_t id); int bt_id_delete(u8_t id);
/* Advertising API */ /** Advertising API */
/** Description of different data types that can be encoded into /** Description of different data types that can be encoded into
* advertising data. Used to form arrays that are passed to the * advertising data. Used to form arrays that are passed to the
@ -420,21 +419,21 @@ typedef void bt_le_scan_cb_t(const bt_addr_le_t *addr, s8_t rssi,
u8_t adv_type, struct net_buf_simple *buf); u8_t adv_type, struct net_buf_simple *buf);
enum { enum {
/* Filter duplicates. */ /** Filter duplicates. */
BT_LE_SCAN_FILTER_DUPLICATE = BIT(0), BT_LE_SCAN_FILTER_DUPLICATE = BIT(0),
/* Filter using whitelist. */ /** Filter using whitelist. */
BT_LE_SCAN_FILTER_WHITELIST = BIT(1), BT_LE_SCAN_FILTER_WHITELIST = BIT(1),
/* Filter using extended filter policies. */ /** Filter using extended filter policies. */
BT_LE_SCAN_FILTER_EXTENDED = BIT(2), BT_LE_SCAN_FILTER_EXTENDED = BIT(2),
}; };
enum { enum {
/* Scan without requesting additional information from advertisers. */ /** Scan without requesting additional information from advertisers. */
BT_LE_SCAN_TYPE_PASSIVE = 0x00, BT_LE_SCAN_TYPE_PASSIVE = 0x00,
/* Scan and request additional information from advertisers. */ /** Scan and request additional information from advertisers. */
BT_LE_SCAN_TYPE_ACTIVE = 0x01, BT_LE_SCAN_TYPE_ACTIVE = 0x01,
}; };
@ -516,7 +515,7 @@ struct bt_le_scan_cb {
* Start LE scanning with given parameters and provide results through * Start LE scanning with given parameters and provide results through
* the specified callback. * the specified callback.
* *
* Note: The LE scanner by default does not use the Identity Address of the * @note The LE scanner by default does not use the Identity Address of the
* local device when :option:`CONFIG_BT_PRIVACY` is disabled. This is to * local device when :option:`CONFIG_BT_PRIVACY` is disabled. This is to
* prevent the active scanner from disclosing the identity information * prevent the active scanner from disclosing the identity information
* when requesting additional information from advertisers. * when requesting additional information from advertisers.
@ -527,8 +526,8 @@ struct bt_le_scan_cb {
* @param cb Callback to notify scan results. May be NULL if callback * @param cb Callback to notify scan results. May be NULL if callback
* registration through @ref bt_le_scan_cb_register is preferred. * registration through @ref bt_le_scan_cb_register is preferred.
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb); int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
@ -536,8 +535,8 @@ int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb);
* *
* Stops ongoing LE scanning. * Stops ongoing LE scanning.
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_scan_stop(void); int bt_le_scan_stop(void);
@ -563,8 +562,8 @@ void bt_le_scan_cb_register(struct bt_le_scan_cb *cb);
* *
* @param addr Bluetooth LE identity address. * @param addr Bluetooth LE identity address.
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error. * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_whitelist_add(const bt_addr_le_t *addr); int bt_le_whitelist_add(const bt_addr_le_t *addr);
@ -578,8 +577,8 @@ int bt_le_whitelist_add(const bt_addr_le_t *addr);
* *
* @param addr Bluetooth LE identity address. * @param addr Bluetooth LE identity address.
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error. * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_whitelist_rem(const bt_addr_le_t *addr); int bt_le_whitelist_rem(const bt_addr_le_t *addr);
@ -591,8 +590,8 @@ int bt_le_whitelist_rem(const bt_addr_le_t *addr);
* the whitelist, i.e advertiser or scanner using a whitelist or automatic * the whitelist, i.e advertiser or scanner using a whitelist or automatic
* connecting to devices using whitelist. * connecting to devices using whitelist.
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error. * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_whitelist_clear(void); int bt_le_whitelist_clear(void);
@ -600,8 +599,8 @@ int bt_le_whitelist_clear(void);
* *
* @param chan_map Channel map. * @param chan_map Channel map.
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_set_chan_map(u8_t chan_map[5]); int bt_le_set_chan_map(u8_t chan_map[5]);
@ -663,8 +662,8 @@ struct bt_le_oob {
* @param[in] id Local identity, in most cases BT_ID_DEFAULT. * @param[in] id Local identity, in most cases BT_ID_DEFAULT.
* @param[out] oob LE OOB information * @param[out] oob LE OOB information
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error. * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_oob_get_local(u8_t id, struct bt_le_oob *oob); int bt_le_oob_get_local(u8_t id, struct bt_le_oob *oob);
@ -736,8 +735,8 @@ int bt_br_discovery_start(const struct bt_br_discovery_param *param,
* Stops ongoing BR/EDR discovery. If discovery was stopped by this call * Stops ongoing BR/EDR discovery. If discovery was stopped by this call
* results won't be reported * results won't be reported
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_br_discovery_stop(void); int bt_br_discovery_stop(void);
@ -746,8 +745,7 @@ struct bt_br_oob {
bt_addr_t addr; bt_addr_t addr;
}; };
/** /** @brief Get BR/EDR local Out Of Band information
* @brief Get BR/EDR local Out Of Band information
* *
* This function allows to get local controller information that are useful * This function allows to get local controller information that are useful
* for Out Of Band pairing or connection creation process. * for Out Of Band pairing or connection creation process.
@ -831,8 +829,7 @@ static inline int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str,
addr->a.val[2], addr->a.val[1], addr->a.val[0], type); addr->a.val[2], addr->a.val[1], addr->a.val[0], type);
} }
/** /** @brief Convert Bluetooth address from string to binary.
* @brief Convert Bluetooth address from string to binary.
* *
* @param[in] str The string representation of a Bluetooth address. * @param[in] str The string representation of a Bluetooth address.
* @param[out] addr Address of buffer to store the Bluetooth address * @param[out] addr Address of buffer to store the Bluetooth address
@ -841,11 +838,11 @@ static inline int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str,
*/ */
int bt_addr_from_str(const char *str, bt_addr_t *addr); int bt_addr_from_str(const char *str, bt_addr_t *addr);
/** /** @brief Convert LE Bluetooth address from string to binary.
* @brief Convert LE Bluetooth address from string to binary.
* *
* @param[in] str The string representation of an LE Bluetooth address. * @param[in] str The string representation of an LE Bluetooth address.
* @param[in] type The string representation of the LE Bluetooth address type. * @param[in] type The string representation of the LE Bluetooth address
* type.
* @param[out] addr Address of buffer to store the LE Bluetooth address * @param[out] addr Address of buffer to store the LE Bluetooth address
* *
* @return Zero on success or (negative) error code otherwise. * @return Zero on success or (negative) error code otherwise.

45
include/bluetooth/conn.h
View file

@ -208,23 +208,23 @@ struct bt_conn_br_remote_info {
* valid data if :option:`CONFIG_BT_REMOTE_VERSION` is enabled. * valid data if :option:`CONFIG_BT_REMOTE_VERSION` is enabled.
*/ */
struct bt_conn_remote_info { struct bt_conn_remote_info {
/* Connection Type */ /** Connection Type */
u8_t type; u8_t type;
/* Remote Link Layer version */ /** Remote Link Layer version */
u8_t version; u8_t version;
/* Remote manufacturer identifier */ /** Remote manufacturer identifier */
u16_t manufacturer; u16_t manufacturer;
/* Per-manufacturer unique revision */ /** Per-manufacturer unique revision */
u16_t subversion; u16_t subversion;
union { union {
/* LE connection remote info */ /** LE connection remote info */
struct bt_conn_le_remote_info le; struct bt_conn_le_remote_info le;
/* BR/EDR connection remote info */ /** BR/EDR connection remote info */
struct bt_conn_br_remote_info br; struct bt_conn_br_remote_info br;
}; };
}; };
@ -323,7 +323,7 @@ int bt_conn_create_auto_stop(void);
* Every time the device loses the connection with peer, this connection * Every time the device loses the connection with peer, this connection
* will be re-established if connectable advertisement from peer is received. * will be re-established if connectable advertisement from peer is received.
* *
* Note: Auto connect is disabled during explicit scanning. * @note Auto connect is disabled during explicit scanning.
* *
* @param addr Remote Bluetooth address. * @param addr Remote Bluetooth address.
* @param param If non-NULL, auto connect is enabled with the given * @param param If non-NULL, auto connect is enabled with the given
@ -618,12 +618,11 @@ void bt_set_bondable(bool enable);
*/ */
void bt_set_oob_data_flag(bool enable); void bt_set_oob_data_flag(bool enable);
/** /** @brief Set OOB Temporary Key to be used for pairing
* @brief Set OOB Temporary Key to be used for pairing
* *
* This function allows to set OOB data for the LE legacy pairing procedure. The * This function allows to set OOB data for the LE legacy pairing procedure.
* function should only be called in response to the oob_data_request() callback * The function should only be called in response to the oob_data_request()
* provided that the legacy method is user pairing. * callback provided that the legacy method is user pairing.
* *
* @param conn Connection object * @param conn Connection object
* @param tk Pointer to 16 byte long TK array * @param tk Pointer to 16 byte long TK array
@ -632,12 +631,11 @@ void bt_set_oob_data_flag(bool enable);
*/ */
int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const u8_t *tk); int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const u8_t *tk);
/** /** @brief Set OOB data during LE Secure Connections (SC) pairing procedure
* @brief Set OOB data during LE Secure Connections (SC) pairing procedure
* *
* This function allows to set OOB data during the LE SC pairing procedure. The * This function allows to set OOB data during the LE SC pairing procedure.
* function should only be called in response to the oob_data_request() callback * The function should only be called in response to the oob_data_request()
* provided that LE SC method is used for pairing. * callback provided that LE SC method is used for pairing.
* *
* The user should submit OOB data according to the information received in the * The user should submit OOB data according to the information received in the
* callback. This may yield three different configurations: with only local OOB * callback. This may yield three different configurations: with only local OOB
@ -648,28 +646,27 @@ int bt_le_oob_set_legacy_tk(struct bt_conn *conn, const u8_t *tk);
* @param oobd_local Local OOB data or NULL if not present * @param oobd_local Local OOB data or NULL if not present
* @param oobd_remote Remote OOB data or NULL if not present * @param oobd_remote Remote OOB data or NULL if not present
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_oob_set_sc_data(struct bt_conn *conn, int bt_le_oob_set_sc_data(struct bt_conn *conn,
const struct bt_le_oob_sc_data *oobd_local, const struct bt_le_oob_sc_data *oobd_local,
const struct bt_le_oob_sc_data *oobd_remote); const struct bt_le_oob_sc_data *oobd_remote);
/** /** @brief Get OOB data used for LE Secure Connections (SC) pairing procedure
* @brief Get OOB data used for LE Secure Connections (SC) pairing procedure
* *
* This function allows to get OOB data during the LE SC pairing procedure that * This function allows to get OOB data during the LE SC pairing procedure that
* were set by the bt_le_oob_set_sc_data() API. * were set by the bt_le_oob_set_sc_data() API.
* *
* Note: The OOB data will only be available as long as the connection object * @note The OOB data will only be available as long as the connection object
* associated with it is valid. * associated with it is valid.
* *
* @param conn Connection object * @param conn Connection object
* @param oobd_local Local OOB data or NULL if not set * @param oobd_local Local OOB data or NULL if not set
* @param oobd_remote Remote OOB data or NULL if not set * @param oobd_remote Remote OOB data or NULL if not set
* *
* @return Zero on success or error code otherwise, positive in case * @return Zero on success or error code otherwise, positive in case of
* of protocol error or negative (POSIX) in case of stack internal error * protocol error or negative (POSIX) in case of stack internal error.
*/ */
int bt_le_oob_get_sc_data(struct bt_conn *conn, int bt_le_oob_get_sc_data(struct bt_conn *conn,
const struct bt_le_oob_sc_data **oobd_local, const struct bt_le_oob_sc_data **oobd_local,

4
include/bluetooth/gap.h
View file

@ -15,10 +15,10 @@
extern "C" { extern "C" {
#endif #endif
/* Company Identifiers (see Bluetooth Assigned Numbers) */ /** Company Identifiers (see Bluetooth Assigned Numbers) */
#define BT_COMP_ID_LF 0x05f1 /* The Linux Foundation */ #define BT_COMP_ID_LF 0x05f1 /* The Linux Foundation */
/* EIR/AD data type definitions */ /** EIR/AD data type definitions */
#define BT_DATA_FLAGS 0x01 /* AD flags */ #define BT_DATA_FLAGS 0x01 /* AD flags */
#define BT_DATA_UUID16_SOME 0x02 /* 16-bit UUID, more available */ #define BT_DATA_UUID16_SOME 0x02 /* 16-bit UUID, more available */
#define BT_DATA_UUID16_ALL 0x03 /* 16-bit UUID, all listed */ #define BT_DATA_UUID16_ALL 0x03 /* 16-bit UUID, all listed */

94
include/bluetooth/gatt.h
View file

@ -28,7 +28,7 @@
extern "C" { extern "C" {
#endif #endif
/* GATT attribute permission bit field values */ /** GATT attribute permission bit field values */
enum { enum {
/** No operations supported, e.g. for notify-only */ /** No operations supported, e.g. for notify-only */
BT_GATT_PERM_NONE = 0, BT_GATT_PERM_NONE = 0,
@ -79,11 +79,10 @@ enum {
* @param _att_err ATT error code * @param _att_err ATT error code
* *
* @return Appropriate error code for the attribute callbacks. * @return Appropriate error code for the attribute callbacks.
*
*/ */
#define BT_GATT_ERR(_att_err) (-(_att_err)) #define BT_GATT_ERR(_att_err) (-(_att_err))
/* GATT attribute write flags */ /** GATT attribute write flags */
enum { enum {
/** Attribute prepare write flag /** Attribute prepare write flag
* *
@ -187,7 +186,7 @@ struct bt_gatt_include {
u16_t end_handle; u16_t end_handle;
}; };
/* Characteristic Properties Bit field values */ /** Characteristic Properties Bit field values */
/** @def BT_GATT_CHRC_BROADCAST /** @def BT_GATT_CHRC_BROADCAST
* @brief Characteristic broadcast property. * @brief Characteristic broadcast property.
@ -251,7 +250,7 @@ struct bt_gatt_chrc {
u8_t properties; u8_t properties;
}; };
/* Characteristic Extended Properties Bit field values */ /** Characteristic Extended Properties Bit field values */
#define BT_GATT_CEP_RELIABLE_WRITE 0x0001 #define BT_GATT_CEP_RELIABLE_WRITE 0x0001
#define BT_GATT_CEP_WRITABLE_AUX 0x0002 #define BT_GATT_CEP_WRITABLE_AUX 0x0002
@ -261,7 +260,7 @@ struct bt_gatt_cep {
u16_t properties; u16_t properties;
}; };
/* Client Characteristic Configuration Values */ /** Client Characteristic Configuration Values */
/** @def BT_GATT_CCC_NOTIFY /** @def BT_GATT_CCC_NOTIFY
* @brief Client Characteristic Configuration Notification. * @brief Client Characteristic Configuration Notification.
@ -276,7 +275,7 @@ struct bt_gatt_cep {
*/ */
#define BT_GATT_CCC_INDICATE 0x0002 #define BT_GATT_CCC_INDICATE 0x0002
/* Client Characteristic Configuration Attribute Value */ /** Client Characteristic Configuration Attribute Value */
struct bt_gatt_ccc { struct bt_gatt_ccc {
/** Client Characteristic Configuration flags */ /** Client Characteristic Configuration flags */
u16_t flags; u16_t flags;
@ -341,8 +340,8 @@ enum {
* @param attr Attribute found. * @param attr Attribute found.
* @param user_data Data given. * @param user_data Data given.
* *
* @return BT_GATT_ITER_CONTINUE if should continue to the next attribute * @return BT_GATT_ITER_CONTINUE if should continue to the next attribute.
* or BT_GATT_ITER_STOP to stop. * @return BT_GATT_ITER_STOP to stop.
*/ */
typedef u8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr, typedef u8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
void *user_data); void *user_data);
@ -396,9 +395,9 @@ struct bt_gatt_attr *bt_gatt_attr_next(const struct bt_gatt_attr *attr);
* *
* @param attr A Characteristic Attribute * @param attr A Characteristic Attribute
* *
* @return the handle of the corresponding Characteristic Value. The * @return the handle of the corresponding Characteristic Value. The value will
* value will be zero (the invalid handle) if @p attr was not a * be zero (the invalid handle) if @p attr was not a characteristic
* characteristic attribute. * attribute.
*/ */
uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr); uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr);
@ -414,7 +413,7 @@ uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr);
* @param value Attribute value. * @param value Attribute value.
* @param value_len Length of the attribute value. * @param value_len Length of the attribute value.
* *
* @return int number of bytes read in case of success or negative values in * @return number of bytes read in case of success or negative values in
* case of error. * case of error.
*/ */
ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr, ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
@ -425,7 +424,7 @@ ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
* *
* Read service attribute value from local database storing the result into * Read service attribute value from local database storing the result into
* buffer after encoding it. * buffer after encoding it.
* NOTE: Only use this with attributes which user_data is a bt_uuid. * @note Only use this with attributes which user_data is a bt_uuid.
* *
* @param conn Connection object. * @param conn Connection object.
* @param attr Attribute to read. * @param attr Attribute to read.
@ -433,7 +432,7 @@ ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
* @param len Buffer length. * @param len Buffer length.
* @param offset Start offset. * @param offset Start offset.
* *
* @return int number of bytes read in case of success or negative values in * @return number of bytes read in case of success or negative values in
* case of error. * case of error.
*/ */
ssize_t bt_gatt_attr_read_service(struct bt_conn *conn, ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
@ -491,7 +490,7 @@ ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
* *
* Read include service attribute value from local database storing the result * Read include service attribute value from local database storing the result
* into buffer after encoding it. * into buffer after encoding it.
* NOTE: Only use this with attributes which user_data is a bt_gatt_include. * @note Only use this with attributes which user_data is a bt_gatt_include.
* *
* @param conn Connection object. * @param conn Connection object.
* @param attr Attribute to read. * @param attr Attribute to read.
@ -499,7 +498,7 @@ ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
* @param len Buffer length. * @param len Buffer length.
* @param offset Start offset. * @param offset Start offset.
* *
* @return int number of bytes read in case of success or negative values in * @return number of bytes read in case of success or negative values in
* case of error. * case of error.
*/ */
ssize_t bt_gatt_attr_read_included(struct bt_conn *conn, ssize_t bt_gatt_attr_read_included(struct bt_conn *conn,
@ -521,7 +520,7 @@ ssize_t bt_gatt_attr_read_included(struct bt_conn *conn,
* *
* Read characteristic attribute value from local database storing the result * Read characteristic attribute value from local database storing the result
* into buffer after encoding it. * into buffer after encoding it.
* NOTE: Only use this with attributes which user_data is a bt_gatt_chrc. * @note Only use this with attributes which user_data is a bt_gatt_chrc.
* *
* @param conn Connection object. * @param conn Connection object.
* @param attr Attribute to read. * @param attr Attribute to read.
@ -554,7 +553,8 @@ ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
bt_gatt_attr_read_chrc, NULL, \ bt_gatt_attr_read_chrc, NULL, \
((struct bt_gatt_chrc[]) { { .uuid = _uuid, \ ((struct bt_gatt_chrc[]) { { .uuid = _uuid, \
.value_handle = 0U, \ .value_handle = 0U, \
.properties = _props, } })), \ .properties = _props, \
} })), \
BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _value) BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _value)
#if IS_ENABLED(CONFIG_BT_SETTINGS_CCC_LAZY_LOADING) #if IS_ENABLED(CONFIG_BT_SETTINGS_CCC_LAZY_LOADING)
@ -564,6 +564,7 @@ ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
#endif #endif
/** @brief GATT CCC configuration entry. /** @brief GATT CCC configuration entry.
*
* @param id Local identity, BT_ID_DEFAULT in most cases. * @param id Local identity, BT_ID_DEFAULT in most cases.
* @param peer Remote peer address * @param peer Remote peer address
* @param value Configuration value. * @param value Configuration value.
@ -575,7 +576,7 @@ struct bt_gatt_ccc_cfg {
u16_t value; u16_t value;
}; };
/* Internal representation of CCC value */ /** Internal representation of CCC value */
struct _bt_gatt_ccc { struct _bt_gatt_ccc {
/** Configuration for each connection */ /** Configuration for each connection */
struct bt_gatt_ccc_cfg cfg[BT_GATT_CCC_MAX]; struct bt_gatt_ccc_cfg cfg[BT_GATT_CCC_MAX];
@ -603,6 +604,7 @@ struct _bt_gatt_ccc {
const struct bt_gatt_attr *attr, u16_t value); const struct bt_gatt_attr *attr, u16_t value);
/** CCC attribute match handler /** CCC attribute match handler
*
* Indicate if it is OK to send a notification or indication * Indicate if it is OK to send a notification or indication
* to the subscriber. * to the subscriber.
* *
@ -620,7 +622,8 @@ struct _bt_gatt_ccc {
* *
* Read CCC attribute value from local database storing the result into buffer * Read CCC attribute value from local database storing the result into buffer
* after encoding it. * after encoding it.
* NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc. *
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
* *
* @param conn Connection object. * @param conn Connection object.
* @param attr Attribute to read. * @param attr Attribute to read.
@ -638,7 +641,8 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
/** @brief Write Client Characteristic Configuration Attribute helper. /** @brief Write Client Characteristic Configuration Attribute helper.
* *
* Write value in the buffer into CCC attribute. * Write value in the buffer into CCC attribute.
* NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc. *
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
* *
* @param conn Connection object. * @param conn Connection object.
* @param attr Attribute to read. * @param attr Attribute to read.
@ -701,7 +705,8 @@ ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
* *
* Read CEP attribute value from local database storing the result into buffer * Read CEP attribute value from local database storing the result into buffer
* after encoding it. * after encoding it.
* NOTE: Only use this with attributes which user_data is a bt_gatt_cep. *
* @note Only use this with attributes which user_data is a bt_gatt_cep.
* *
* @param conn Connection object * @param conn Connection object
* @param attr Attribute to read * @param attr Attribute to read
@ -731,7 +736,8 @@ ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn,
* *
* Read CUD attribute value from local database storing the result into buffer * Read CUD attribute value from local database storing the result into buffer
* after encoding it. * after encoding it.
* NOTE: Only use this with attributes which user_data is a NULL-terminated C *
* @note Only use this with attributes which user_data is a NULL-terminated C
* string. * string.
* *
* @param conn Connection object * @param conn Connection object
@ -763,7 +769,8 @@ ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn,
* *
* Read CPF attribute value from local database storing the result into buffer * Read CPF attribute value from local database storing the result into buffer
* after encoding it. * 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 bt_gatt_pf.
* *
* @param conn Connection object * @param conn Connection object
* @param attr Attribute to read * @param attr Attribute to read
@ -944,7 +951,7 @@ struct bt_gatt_indicate_params {
* parameters, when using this method the attribute given is used as the * parameters, when using this method the attribute given is used as the
* start range when looking up for possible matches. * start range when looking up for possible matches.
* *
* Note: This procedure is asynchronous therefore the parameters need to * @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active. * remains valid while it is active.
* *
* @param conn Connection object. * @param conn Connection object.
@ -1007,7 +1014,7 @@ struct bt_gatt_exchange_params {
* This client procedure can be used to set the MTU to the maximum possible * This client procedure can be used to set the MTU to the maximum possible
* size the buffers can hold. * size the buffers can hold.
* *
* NOTE: Shall only be used once per connection. * @note Shall only be used once per connection.
* *
* @param conn Connection object. * @param conn Connection object.
* @param params Exchange MTU parameters. * @param params Exchange MTU parameters.
@ -1031,14 +1038,14 @@ struct bt_gatt_discover_params;
* BT_GATT_ITER_STOP. The attribute is read-only and cannot be cached without * BT_GATT_ITER_STOP. The attribute is read-only and cannot be cached without
* copying its contents. * copying its contents.
* *
* @return BT_GATT_ITER_CONTINUE if should continue attribute discovery * @return BT_GATT_ITER_CONTINUE if should continue attribute discovery.
* or BT_GATT_ITER_STOP to stop discovery procedure. * @return BT_GATT_ITER_STOP to stop discovery procedure.
*/ */
typedef u8_t (*bt_gatt_discover_func_t)(struct bt_conn *conn, typedef u8_t (*bt_gatt_discover_func_t)(struct bt_conn *conn,
const struct bt_gatt_attr *attr, const struct bt_gatt_attr *attr,
struct bt_gatt_discover_params *params); struct bt_gatt_discover_params *params);
/* GATT Discover types */ /** GATT Discover types */
enum { enum {
/** Discover Primary Services. */ /** Discover Primary Services. */
BT_GATT_DISCOVER_PRIMARY, BT_GATT_DISCOVER_PRIMARY,
@ -1055,7 +1062,7 @@ enum {
* *
* Discover Attributes which are not services or characteristics. * Discover Attributes which are not services or characteristics.
* *
* Note: The use of this type of discover is not recommended for * @note The use of this type of discover is not recommended for
* discovering in ranges across multiple services/characteristics * discovering in ranges across multiple services/characteristics
* as it may incur in extra round trips. * as it may incur in extra round trips.
*/ */
@ -1064,9 +1071,9 @@ enum {
* *
* Discover Attributes of any type. * Discover Attributes of any type.
* *
* Note: The use of this type of discover is not recommended for * @note The use of this type of discover is not recommended for
* discovering in ranges across multiple services/characteristics as * discovering in ranges across multiple services/characteristics
* it may incur in more round trips. * as it may incur in more round trips.
*/ */
BT_GATT_DISCOVER_ATTRIBUTE, BT_GATT_DISCOVER_ATTRIBUTE,
}; };
@ -1112,7 +1119,7 @@ struct bt_gatt_discover_params {
* For each attribute found the callback is called which can then decide * For each attribute found the callback is called which can then decide
* whether to continue discovering or stop. * whether to continue discovering or stop.
* *
* Note: This procedure is asynchronous therefore the parameters need to * @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active. * remains valid while it is active.
* *
* @param conn Connection object. * @param conn Connection object.
@ -1139,6 +1146,7 @@ typedef u8_t (*bt_gatt_read_func_t)(struct bt_conn *conn, u8_t err,
const void *data, u16_t length); const void *data, u16_t length);
/** @brief GATT Read parameters /** @brief GATT Read parameters
*
* @param func Read attribute callback * @param func Read attribute callback
* @param handle_count If equals to 1 single.handle and single.offset * @param handle_count If equals to 1 single.handle and single.offset
* are used. If >1 Read Multiple Characteristic * are used. If >1 Read Multiple Characteristic
@ -1181,7 +1189,7 @@ struct bt_gatt_read_params {
* caller will need to read the remaining data separately using the handle and * caller will need to read the remaining data separately using the handle and
* offset. * offset.
* *
* Note: This procedure is asynchronous therefore the parameters need to * @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active. * remains valid while it is active.
* *
* @param conn Connection object. * @param conn Connection object.
@ -1222,7 +1230,7 @@ struct bt_gatt_write_params {
* This procedure write the attribute value and return the result in the * This procedure write the attribute value and return the result in the
* callback. * callback.
* *
* Note: This procedure is asynchronous therefore the parameters need to * @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active. * remains valid while it is active.
* *
* @param conn Connection object. * @param conn Connection object.
@ -1240,10 +1248,10 @@ int bt_gatt_write(struct bt_conn *conn, struct bt_gatt_write_params *params);
* *
* The callback is run from System Workqueue context. * The callback is run from System Workqueue context.
* *
* Note: By using a callback it also disable the internal flow control * @note By using a callback it also disable the internal flow control
* which would prevent sending multiple commands without waiting for their * which would prevent sending multiple commands without waiting for
* transmissions to complete, so if that is required the caller shall not * their transmissions to complete, so if that is required the caller
* submit more data until the callback is called. * shall not submit more data until the callback is called.
* *
* @param conn Connection object. * @param conn Connection object.
* @param handle Attribute handle. * @param handle Attribute handle.
@ -1299,7 +1307,7 @@ typedef u8_t (*bt_gatt_notify_func_t)(struct bt_conn *conn,
struct bt_gatt_subscribe_params *params, struct bt_gatt_subscribe_params *params,
const void *data, u16_t length); const void *data, u16_t length);
/* Subscription flags */ /** Subscription flags */
enum { enum {
/** Persistence flag /** Persistence flag
* *
@ -1361,7 +1369,7 @@ struct bt_gatt_subscribe_params {
* this callback. Notification callback with NULL data will not be called if * this callback. Notification callback with NULL data will not be called if
* subscription was removed by this method. * subscription was removed by this method.
* *
* Note: This procedure is asynchronous therefore the parameters need to * @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active. * remains valid while it is active.
* *
* @param conn Connection object. * @param conn Connection object.

2
include/bluetooth/hci_err.h
View file

@ -14,7 +14,7 @@
extern "C" { extern "C" {
#endif #endif
/* HCI Error Codes, BT Core Spec v5.2 [Vol 1, Part F]. */ /** HCI Error Codes, BT Core Spec v5.2 [Vol 1, Part F]. */
#define BT_HCI_ERR_SUCCESS 0x00 #define BT_HCI_ERR_SUCCESS 0x00
#define BT_HCI_ERR_UNKNOWN_CMD 0x01 #define BT_HCI_ERR_UNKNOWN_CMD 0x01
#define BT_HCI_ERR_UNKNOWN_CONN_ID 0x02 #define BT_HCI_ERR_UNKNOWN_CONN_ID 0x02

30
include/bluetooth/l2cap.h
View file

@ -26,7 +26,7 @@
extern "C" { extern "C" {
#endif #endif
/* L2CAP header size, used for buffer size calculations */ /** L2CAP header size, used for buffer size calculations */
#define BT_L2CAP_HDR_SIZE 4 #define BT_L2CAP_HDR_SIZE 4
/** @def BT_L2CAP_BUF_SIZE /** @def BT_L2CAP_BUF_SIZE
@ -51,9 +51,10 @@ struct bt_l2cap_chan;
*/ */
typedef void (*bt_l2cap_chan_destroy_t)(struct bt_l2cap_chan *chan); typedef void (*bt_l2cap_chan_destroy_t)(struct bt_l2cap_chan *chan);
/** @brief Life-span states of L2CAP CoC channel. Used only by internal APIs /** @brief Life-span states of L2CAP CoC channel.
* dealing with setting channel to proper state depending on operational *
* context. * Used only by internal APIs dealing with setting channel to proper state
* depending on operational context.
*/ */
typedef enum bt_l2cap_chan_state { typedef enum bt_l2cap_chan_state {
/** Channel disconnected */ /** Channel disconnected */
@ -229,14 +230,16 @@ struct bt_l2cap_chan_ops {
* @param buf Buffer containing incoming data. * @param buf Buffer containing incoming data.
* *
* @return 0 in case of success or negative value in case of error. * @return 0 in case of success or negative value in case of error.
* If -EINPROGRESS is returned user has to confirm once the data has * @return -EINPROGRESS in case where user has to confirm once the data
* been processed by calling bt_l2cap_chan_recv_complete passing back * has been processed by calling
* the buffer received with its original user_data which contains the * @ref bt_l2cap_chan_recv_complete passing back
* number of segments/credits used by the packet. * the buffer received with its original user_data
* which contains the number of segments/credits
* used by the packet.
*/ */
int (*recv)(struct bt_l2cap_chan *chan, struct net_buf *buf); int (*recv)(struct bt_l2cap_chan *chan, struct net_buf *buf);
/* Channel sent callback /** Channel sent callback
* *
* If this callback is provided it will be called whenever a SDU has * If this callback is provided it will be called whenever a SDU has
* been completely sent. * been completely sent.
@ -245,7 +248,7 @@ struct bt_l2cap_chan_ops {
*/ */
void (*sent)(struct bt_l2cap_chan *chan); void (*sent)(struct bt_l2cap_chan *chan);
/* Channel status callback /** Channel status callback
* *
* If this callback is provided it will be called whenever the * If this callback is provided it will be called whenever the
* channel status changes. * channel status changes.
@ -289,10 +292,9 @@ struct bt_l2cap_server {
* @param chan Pointer to received the allocated channel * @param chan Pointer to received the allocated channel
* *
* @return 0 in case of success or negative value in case of error. * @return 0 in case of success or negative value in case of error.
* Possible return values: * @return -ENOMEM if no available space for new channel.
* -ENOMEM if no available space for new channel. * @return -EACCES if application did not authorize the connection.
* -EACCES if application did not authorize the connection. * @return -EPERM if encryption key size is too short.
* -EPERM if encryption key size is too short.
*/ */
int (*accept)(struct bt_conn *conn, struct bt_l2cap_chan **chan); int (*accept)(struct bt_conn *conn, struct bt_l2cap_chan **chan);