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

121
include/bluetooth/bluetooth.h
View file

@ -45,9 +45,8 @@ extern "C" {
*/
#define BT_ID_DEFAULT 0
/**
* @typedef bt_ready_cb_t
* @brief Callback for notifying that Bluetooth has been enabled.
/** @typedef bt_ready_cb_t
* @brief Callback for notifying that Bluetooth has been enabled.
*
* @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
* 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.
*
* @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
* 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.
*
* @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
* 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.
*
* @param id Existing identity identifier.
@ -204,12 +203,12 @@ int bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_t *irk);
*/
int bt_id_delete(u8_t id);
/* Advertising API */
/** Advertising API */
/** Description of different data types that can be encoded into
* advertising data. Used to form arrays that are passed to the
* bt_le_adv_start() function.
*/
* advertising data. Used to form arrays that are passed to the
* bt_le_adv_start() function.
*/
struct bt_data {
u8_t type;
u8_t data_len;
@ -321,11 +320,11 @@ struct bt_le_adv_param {
};
/** Helper to declare advertising parameters inline
*
* @param _options Advertising Options
* @param _int_min Minimum advertising interval
* @param _int_max Maximum advertising interval
*/
*
* @param _options Advertising Options
* @param _int_min Minimum advertising interval
* @param _int_max Maximum advertising interval
*/
#define BT_LE_ADV_PARAM(_options, _int_min, _int_max) \
((struct bt_le_adv_param[]) { { \
.id = BT_ID_DEFAULT, \
@ -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);
enum {
/* Filter duplicates. */
/** Filter duplicates. */
BT_LE_SCAN_FILTER_DUPLICATE = BIT(0),
/* Filter using whitelist. */
/** Filter using whitelist. */
BT_LE_SCAN_FILTER_WHITELIST = BIT(1),
/* Filter using extended filter policies. */
/** Filter using extended filter policies. */
BT_LE_SCAN_FILTER_EXTENDED = BIT(2),
};
enum {
/* Scan without requesting additional information from advertisers. */
/** Scan without requesting additional information from advertisers. */
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,
};
@ -480,13 +479,13 @@ struct bt_le_scan_cb {
};
/** Helper to declare scan parameters inline
*
* @param _type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or
* BT_LE_SCAN_TYPE_PASSIVE.
* @param _filter Filter options
* @param _interval Scan Interval (N * 0.625 ms)
* @param _window Scan Window (N * 0.625 ms)
*/
*
* @param _type Scan Type, BT_LE_SCAN_TYPE_ACTIVE or
* BT_LE_SCAN_TYPE_PASSIVE.
* @param _filter Filter options
* @param _interval Scan Interval (N * 0.625 ms)
* @param _window Scan Window (N * 0.625 ms)
*/
#define BT_LE_SCAN_PARAM(_type, _filter, _interval, _window) \
((struct bt_le_scan_param[]) { { \
.type = (_type), \
@ -503,8 +502,8 @@ struct bt_le_scan_cb {
/** Helper macro to enable passive scanning to discover new devices.
*
* This macro should be used if information required for device identification
* (e.g., UUID) are known to be placed in Advertising Data.
* This macro should be used if information required for device identification
* (e.g., UUID) are known to be placed in Advertising Data.
*/
#define BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_LE_SCAN_TYPE_PASSIVE, \
BT_LE_SCAN_FILTER_DUPLICATE, \
@ -516,7 +515,7 @@ struct bt_le_scan_cb {
* Start LE scanning with given parameters and provide results through
* 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
* prevent the active scanner from disclosing the identity information
* 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
* registration through @ref bt_le_scan_cb_register is preferred.
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error
* @return Zero on success or error code otherwise, positive in case of
* 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);
@ -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.
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
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.
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error.
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
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.
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error.
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
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
* connecting to devices using whitelist.
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error.
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
int bt_le_whitelist_clear(void);
@ -600,8 +599,8 @@ int bt_le_whitelist_clear(void);
*
* @param chan_map Channel map.
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
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[out] oob LE OOB information
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error.
* @return Zero on success or error code otherwise, positive in case of
* 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);
@ -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
* results won't be reported
*
* @return Zero on success or error code otherwise, positive in case
* of protocol error or negative (POSIX) in case of stack internal error
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
int bt_br_discovery_stop(void);
@ -746,13 +745,12 @@ struct bt_br_oob {
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
* for Out Of Band pairing or connection creation process.
* This function allows to get local controller information that are useful
* for Out Of Band pairing or connection creation process.
*
* @param oob Out Of Band information
* @param oob Out Of Band information
*/
int bt_br_oob_get_local(struct bt_br_oob *oob);
@ -831,22 +829,21 @@ 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);
}
/**
* @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[out] addr Address of buffer to store the Bluetooth address
* @param[in] str The string representation of a Bluetooth address.
* @param[out] addr Address of buffer to store the Bluetooth address
*
* @return Zero on success or (negative) error code otherwise.
*/
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] type The string representation of the LE Bluetooth address type.
* @param[out] addr Address of buffer to store the 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[out] addr Address of buffer to store the LE Bluetooth address
*
* @return Zero on success or (negative) error code otherwise.
*/
@ -861,7 +858,7 @@ int bt_addr_le_from_str(const char *str, const char *type, bt_addr_le_t *addr);
* @param enable Value allowing/disallowing controller to become discoverable.
*
* @return Negative if fail set to requested state or requested state has been
* already set. Zero if done successfully.
* already set. Zero if done successfully.
*/
int bt_br_set_discoverable(bool enable);
@ -874,7 +871,7 @@ int bt_br_set_discoverable(bool enable);
* @param enable Value allowing/disallowing controller to be connectable.
*
* @return Negative if fail set to requested state or requested state has been
* already set. Zero if done successfully.
* already set. Zero if done successfully.
*/
int bt_br_set_connectable(bool enable);

113
include/bluetooth/conn.h
View file

@ -39,12 +39,12 @@ struct bt_le_conn_param {
};
/** Helper to declare connection parameters inline
*
* @param int_min Minimum Connection Interval (N * 1.25 ms)
* @param int_max Maximum Connection Interval (N * 1.25 ms)
* @param lat Connection Latency
* @param to Supervision Timeout (N * 10 ms)
*/
*
* @param int_min Minimum Connection Interval (N * 1.25 ms)
* @param int_max Maximum Connection Interval (N * 1.25 ms)
* @param lat Connection Latency
* @param to Supervision Timeout (N * 10 ms)
*/
#define BT_LE_CONN_PARAM(int_min, int_max, lat, to) \
((struct bt_le_conn_param[]) { { \
.interval_min = (int_min), \
@ -54,10 +54,10 @@ struct bt_le_conn_param {
} })
/** Default LE connection parameters:
* Connection Interval: 30-50 ms
* Latency: 0
* Timeout: 4 s
*/
* Connection Interval: 30-50 ms
* Latency: 0
* Timeout: 4 s
*/
#define BT_LE_CONN_PARAM_DEFAULT BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, \
BT_GAP_INIT_CONN_INT_MAX, \
0, 400)
@ -119,7 +119,7 @@ const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn);
* @param conn Connection object.
*
* @return Index of the connection object.
* The range of the returned value is 0..CONFIG_BT_MAX_CONN-1
* The range of the returned value is 0..CONFIG_BT_MAX_CONN-1
*/
u8_t bt_conn_index(struct bt_conn *conn);
@ -208,23 +208,23 @@ struct bt_conn_br_remote_info {
* valid data if :option:`CONFIG_BT_REMOTE_VERSION` is enabled.
*/
struct bt_conn_remote_info {
/* Connection Type */
/** Connection Type */
u8_t type;
/* Remote Link Layer version */
/** Remote Link Layer version */
u8_t version;
/* Remote manufacturer identifier */
/** Remote manufacturer identifier */
u16_t manufacturer;
/* Per-manufacturer unique revision */
/** Per-manufacturer unique revision */
u16_t subversion;
union {
/* LE connection remote info */
/** LE connection remote info */
struct bt_conn_le_remote_info le;
/* BR/EDR connection remote info */
/** BR/EDR connection remote info */
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
* 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 param If non-NULL, auto connect is enabled with the given
@ -618,58 +618,55 @@ void bt_set_bondable(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
* function should only be called in response to the oob_data_request() callback
* provided that the legacy method is user pairing.
* This function allows to set OOB data for the LE legacy pairing procedure.
* The function should only be called in response to the oob_data_request()
* callback provided that the legacy method is user pairing.
*
* @param conn Connection object
* @param tk Pointer to 16 byte long TK array
* @param conn Connection object
* @param tk Pointer to 16 byte long TK array
*
* @return Zero on success or -EINVAL if NULL
* @return Zero on success or -EINVAL if NULL
*/
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
* function should only be called in response to the oob_data_request() callback
* provided that LE SC method is used for pairing.
* This function allows to set OOB data during the LE SC pairing procedure.
* The function should only be called in response to the oob_data_request()
* callback provided that LE SC method is used for pairing.
*
* The user should submit OOB data according to the information received in the
* callback. This may yield three different configurations: with only local OOB
* data present, with only remote OOB data present or with both local and
* remote OOB data present.
* The user should submit OOB data according to the information received in the
* callback. This may yield three different configurations: with only local OOB
* data present, with only remote OOB data present or with both local and
* remote OOB data present.
*
* @param conn Connection object
* @param oobd_local Local OOB data or NULL if not present
* @param oobd_remote Remote OOB data or NULL if not present
* @param conn Connection object
* @param oobd_local Local 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
* of protocol error or negative (POSIX) in case of stack internal error
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
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_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
* were set by the bt_le_oob_set_sc_data() API.
* 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.
*
* 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.
*
* @param conn Connection object
* @param oobd_local Local OOB data or NULL if not set
* @param oobd_remote Remote OOB data or NULL if not set
* @param conn Connection object
* @param oobd_local Local 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
* of protocol error or negative (POSIX) in case of stack internal error
* @return Zero on success or error code otherwise, positive in case of
* protocol error or negative (POSIX) in case of stack internal error.
*/
int bt_le_oob_get_sc_data(struct bt_conn *conn,
const struct bt_le_oob_sc_data **oobd_local,
@ -935,18 +932,18 @@ struct bt_conn_auth_cb {
/** @brief notify that pairing process was complete.
*
* This callback notifies the application that the pairing process
* has been completed.
* This callback notifies the application that the pairing process
* has been completed.
*
* @param conn Connection object.
* @param bonded pairing is bonded or not.
* @param conn Connection object.
* @param bonded pairing is bonded or not.
*/
void (*pairing_complete)(struct bt_conn *conn, bool bonded);
/** @brief notify that pairing process has failed.
*
* @param conn Connection object.
* @param reason Pairing failed reason
* @param conn Connection object.
* @param reason Pairing failed reason
*/
void (*pairing_failed)(struct bt_conn *conn,
enum bt_security_err reason);
@ -1034,8 +1031,8 @@ struct bt_br_conn_param {
} })
/** Default BR/EDR connection parameters:
* Role switch allowed
*/
* Role switch allowed
*/
#define BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true)

4
include/bluetooth/gap.h
View file

@ -15,10 +15,10 @@
extern "C" {
#endif
/* Company Identifiers (see Bluetooth Assigned Numbers) */
/** Company Identifiers (see Bluetooth Assigned Numbers) */
#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_UUID16_SOME 0x02 /* 16-bit UUID, more available */
#define BT_DATA_UUID16_ALL 0x03 /* 16-bit UUID, all listed */

250
include/bluetooth/gatt.h
View file

@ -28,7 +28,7 @@
extern "C" {
#endif
/* GATT attribute permission bit field values */
/** GATT attribute permission bit field values */
enum {
/** No operations supported, e.g. for notify-only */
BT_GATT_PERM_NONE = 0,
@ -73,17 +73,16 @@ enum {
BT_GATT_PERM_PREPARE_WRITE = BIT(6),
};
/** @def BT_GATT_ERR
* @brief Construct error return value for attribute read and write callbacks.
*
* @param _att_err ATT error code
*
* @return Appropriate error code for the attribute callbacks.
*
*/
/** @def BT_GATT_ERR
* @brief Construct error return value for attribute read and write callbacks.
*
* @param _att_err ATT error code
*
* @return Appropriate error code for the attribute callbacks.
*/
#define BT_GATT_ERR(_att_err) (-(_att_err))
/* GATT attribute write flags */
/** GATT attribute write flags */
enum {
/** Attribute prepare write flag
*
@ -187,7 +186,7 @@ struct bt_gatt_include {
u16_t end_handle;
};
/* Characteristic Properties Bit field values */
/** Characteristic Properties Bit field values */
/** @def BT_GATT_CHRC_BROADCAST
* @brief Characteristic broadcast property.
@ -251,7 +250,7 @@ struct bt_gatt_chrc {
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_WRITABLE_AUX 0x0002
@ -261,7 +260,7 @@ struct bt_gatt_cep {
u16_t properties;
};
/* Client Characteristic Configuration Values */
/** Client Characteristic Configuration Values */
/** @def BT_GATT_CCC_NOTIFY
* @brief Client Characteristic Configuration Notification.
@ -276,7 +275,7 @@ struct bt_gatt_cep {
*/
#define BT_GATT_CCC_INDICATE 0x0002
/* Client Characteristic Configuration Attribute Value */
/** Client Characteristic Configuration Attribute Value */
struct bt_gatt_ccc {
/** Client Characteristic Configuration flags */
u16_t flags;
@ -341,8 +340,8 @@ enum {
* @param attr Attribute found.
* @param user_data Data given.
*
* @return BT_GATT_ITER_CONTINUE if should continue to the next attribute
* or BT_GATT_ITER_STOP to stop.
* @return BT_GATT_ITER_CONTINUE if should continue to the next attribute.
* @return BT_GATT_ITER_STOP to stop.
*/
typedef u8_t (*bt_gatt_attr_func_t)(const struct bt_gatt_attr *attr,
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
*
* @return the handle of the corresponding Characteristic Value. The
* value will be zero (the invalid handle) if @p attr was not a
* characteristic attribute.
* @return the handle of the corresponding Characteristic Value. The value will
* be zero (the invalid handle) if @p attr was not a characteristic
* attribute.
*/
uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr);
@ -414,8 +413,8 @@ uint16_t bt_gatt_attr_value_handle(const struct bt_gatt_attr *attr);
* @param value Attribute value.
* @param value_len Length of the attribute value.
*
* @return int number of bytes read in case of success or negative values in
* case of error.
* @return number of bytes read in case of success or negative values in
* case of error.
*/
ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
void *buf, u16_t buf_len, u16_t offset,
@ -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
* 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 attr Attribute to read.
@ -433,8 +432,8 @@ ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr,
* @param len Buffer length.
* @param offset Start offset.
*
* @return int number of bytes read in case of success or negative values in
* case of error.
* @return number of bytes read in case of success or negative values in
* case of error.
*/
ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
const struct bt_gatt_attr *attr,
@ -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
* 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 attr Attribute to read.
@ -499,8 +498,8 @@ ssize_t bt_gatt_attr_read_service(struct bt_conn *conn,
* @param len Buffer length.
* @param offset Start offset.
*
* @return int number of bytes read in case of success or negative values in
* case of error.
* @return number of bytes read in case of success or negative values in
* case of error.
*/
ssize_t bt_gatt_attr_read_included(struct bt_conn *conn,
const struct bt_gatt_attr *attr,
@ -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
* 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 attr Attribute to read.
@ -530,7 +529,7 @@ ssize_t bt_gatt_attr_read_included(struct bt_conn *conn,
* @param offset Start offset.
*
* @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_chrc(struct bt_conn *conn,
const struct bt_gatt_attr *attr, void *buf,
@ -549,12 +548,13 @@ ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn,
* @param _write Characteristic Attribute write callback.
* @param _value Characteristic Attribute value.
*/
#define BT_GATT_CHARACTERISTIC(_uuid, _props, _perm, _read, _write, _value) \
BT_GATT_ATTRIBUTE(BT_UUID_GATT_CHRC, BT_GATT_PERM_READ, \
bt_gatt_attr_read_chrc, NULL, \
((struct bt_gatt_chrc[]) { { .uuid = _uuid, \
.value_handle = 0U, \
.properties = _props, } })), \
#define BT_GATT_CHARACTERISTIC(_uuid, _props, _perm, _read, _write, _value) \
BT_GATT_ATTRIBUTE(BT_UUID_GATT_CHRC, BT_GATT_PERM_READ, \
bt_gatt_attr_read_chrc, NULL, \
((struct bt_gatt_chrc[]) { { .uuid = _uuid, \
.value_handle = 0U, \
.properties = _props, \
} })), \
BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _value)
#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
/** @brief GATT CCC configuration entry.
*
* @param id Local identity, BT_ID_DEFAULT in most cases.
* @param peer Remote peer address
* @param value Configuration value.
@ -575,7 +576,7 @@ struct bt_gatt_ccc_cfg {
u16_t value;
};
/* Internal representation of CCC value */
/** Internal representation of CCC value */
struct _bt_gatt_ccc {
/** Configuration for each connection */
struct bt_gatt_ccc_cfg cfg[BT_GATT_CCC_MAX];
@ -603,8 +604,9 @@ struct _bt_gatt_ccc {
const struct bt_gatt_attr *attr, u16_t value);
/** CCC attribute match handler
* Indicate if it is OK to send a notification or indication
* to the subscriber.
*
* Indicate if it is OK to send a notification or indication
* to the subscriber.
*
* @param conn The connection that is being checked
* @param attr The attribute that's being checked
@ -620,7 +622,8 @@ 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.
*
* @note Only use this with attributes which user_data is a _bt_gatt_ccc.
*
* @param conn Connection object.
* @param attr Attribute to read.
@ -629,7 +632,7 @@ struct _bt_gatt_ccc {
* @param offset Start offset.
*
* @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_ccc(struct bt_conn *conn,
const struct bt_gatt_attr *attr, void *buf,
@ -638,7 +641,8 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
/** @brief Write Client Characteristic Configuration Attribute helper.
*
* 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 attr Attribute to read.
@ -648,7 +652,7 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
* @param flags Write flags.
*
* @return number of bytes written in case of success or negative values in
* case of error.
* case of error.
*/
ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
const struct bt_gatt_attr *attr, const void *buf,
@ -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
* 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 attr Attribute to read
@ -710,7 +715,7 @@ ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
* @param offset Start offset
*
* @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_cep(struct bt_conn *conn,
const struct bt_gatt_attr *attr, void *buf,
@ -731,8 +736,9 @@ ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn,
*
* Read CUD attribute value from local database storing the result into buffer
* after encoding it.
* NOTE: Only use this with attributes which user_data is a NULL-terminated C
* string.
*
* @note Only use this with attributes which user_data is a NULL-terminated C
* string.
*
* @param conn Connection object
* @param attr Attribute to read
@ -741,7 +747,7 @@ ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn,
* @param offset Start offset
*
* @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_cud(struct bt_conn *conn,
const struct bt_gatt_attr *attr, void *buf,
@ -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
* 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 attr Attribute to read
@ -772,7 +779,7 @@ ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn,
* @param offset Start offset
*
* @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_cpf(struct bt_conn *conn,
const struct bt_gatt_attr *attr, void *buf,
@ -944,8 +951,8 @@ struct bt_gatt_indicate_params {
* parameters, when using this method the attribute given is used as the
* start range when looking up for possible matches.
*
* Note: This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
* @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
*
* @param conn Connection object.
* @param params Indicate parameters.
@ -1007,7 +1014,7 @@ struct bt_gatt_exchange_params {
* This client procedure can be used to set the MTU to the maximum possible
* 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 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
* copying its contents.
*
* @return BT_GATT_ITER_CONTINUE if should continue attribute discovery
* or BT_GATT_ITER_STOP to stop discovery procedure.
* @return BT_GATT_ITER_CONTINUE if should continue attribute discovery.
* @return BT_GATT_ITER_STOP to stop discovery procedure.
*/
typedef u8_t (*bt_gatt_discover_func_t)(struct bt_conn *conn,
const struct bt_gatt_attr *attr,
struct bt_gatt_discover_params *params);
/* GATT Discover types */
/** GATT Discover types */
enum {
/** Discover Primary Services. */
BT_GATT_DISCOVER_PRIMARY,
@ -1055,18 +1062,18 @@ enum {
*
* Discover Attributes which are not services or characteristics.
*
* Note: The use of this type of discover is not recommended for
* discovering in ranges across multiple services/characteristics
* as it may incur in extra round trips.
* @note The use of this type of discover is not recommended for
* discovering in ranges across multiple services/characteristics
* as it may incur in extra round trips.
*/
BT_GATT_DISCOVER_DESCRIPTOR,
/** Discover Attributes.
*
* Discover Attributes of any type.
*
* Note: The use of this type of discover is not recommended for
* discovering in ranges across multiple services/characteristics as
* it may incur in more round trips.
* @note The use of this type of discover is not recommended for
* discovering in ranges across multiple services/characteristics
* as it may incur in more round trips.
*/
BT_GATT_DISCOVER_ATTRIBUTE,
};
@ -1112,8 +1119,8 @@ struct bt_gatt_discover_params {
* For each attribute found the callback is called which can then decide
* whether to continue discovering or stop.
*
* Note: This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
* @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
*
* @param conn Connection object.
* @param params Discover parameters.
@ -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);
/** @brief GATT Read parameters
*
* @param func Read attribute callback
* @param handle_count If equals to 1 single.handle and single.offset
* are used. If >1 Read Multiple Characteristic
@ -1181,8 +1189,8 @@ struct bt_gatt_read_params {
* caller will need to read the remaining data separately using the handle and
* offset.
*
* Note: This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
* @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
*
* @param conn Connection object.
* @param params Read parameters.
@ -1219,41 +1227,41 @@ struct bt_gatt_write_params {
/** @brief Write Attribute Value by handle
*
* This procedure write the attribute value and return the result in the
* callback.
* This procedure write the attribute value and return the result in the
* callback.
*
* Note: This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
* @note This procedure is asynchronous therefore the parameters need to
* remains valid while it is active.
*
* @param conn Connection object.
* @param params Write parameters.
* @param conn Connection object.
* @param params Write parameters.
*
* @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.
*/
int bt_gatt_write(struct bt_conn *conn, struct bt_gatt_write_params *params);
/** @brief Write Attribute Value by handle without response with callback.
*
* This function works in the same way as @ref bt_gatt_write_without_response.
* With the addition that after sending the write the callback function will be
* called.
* This function works in the same way as @ref bt_gatt_write_without_response.
* With the addition that after sending the write the callback function will be
* called.
*
* 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
* which would prevent sending multiple commands without waiting for their
* transmissions to complete, so if that is required the caller shall not
* submit more data until the callback is called.
* @note By using a callback it also disable the internal flow control
* which would prevent sending multiple commands without waiting for
* their transmissions to complete, so if that is required the caller
* shall not submit more data until the callback is called.
*
* @param conn Connection object.
* @param handle Attribute handle.
* @param data Data to be written.
* @param length Data length.
* @param sign Whether to sign data
* @param func Transmission complete callback.
* @param user_data User data to be passed back to callback.
* @param conn Connection object.
* @param handle Attribute handle.
* @param data Data to be written.
* @param length Data length.
* @param sign Whether to sign data
* @param func Transmission complete callback.
* @param user_data User data to be passed back to callback.
*
* @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.
*/
int bt_gatt_write_without_response_cb(struct bt_conn *conn, u16_t handle,
const void *data, u16_t length,
@ -1262,16 +1270,16 @@ int bt_gatt_write_without_response_cb(struct bt_conn *conn, u16_t handle,
/** @brief Write Attribute Value by handle without response
*
* This procedure write the attribute value without requiring an
* acknowledgment that the write was successfully performed
* This procedure write the attribute value without requiring an
* acknowledgment that the write was successfully performed
*
* @param conn Connection object.
* @param handle Attribute handle.
* @param data Data to be written.
* @param length Data length.
* @param sign Whether to sign data
* @param conn Connection object.
* @param handle Attribute handle.
* @param data Data to be written.
* @param length Data length.
* @param sign Whether to sign 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.
*/
static inline int bt_gatt_write_without_response(struct bt_conn *conn,
u16_t handle, const void *data,
@ -1299,37 +1307,37 @@ typedef u8_t (*bt_gatt_notify_func_t)(struct bt_conn *conn,
struct bt_gatt_subscribe_params *params,
const void *data, u16_t length);
/* Subscription flags */
/** Subscription flags */
enum {
/** Persistence flag
*
* If set, indicates that the subscription is not saved
* on the GATT server side. Therefore, upon disconnection,
* the subscription will be automatically removed
* from the client's subscriptions list and
* when the client reconnects, it will have to
* issue a new subscription.
* If set, indicates that the subscription is not saved
* on the GATT server side. Therefore, upon disconnection,
* the subscription will be automatically removed
* from the client's subscriptions list and
* when the client reconnects, it will have to
* issue a new subscription.
*/
BT_GATT_SUBSCRIBE_FLAG_VOLATILE,
/** No resubscribe flag
*
* By default when BT_GATT_SUBSCRIBE_FLAG_VOLATILE is unset, the
* subscription will be automatically renewed when the client
* reconnects, as a workaround for GATT servers that do not persist
* subscriptions.
* By default when BT_GATT_SUBSCRIBE_FLAG_VOLATILE is unset, the
* subscription will be automatically renewed when the client
* reconnects, as a workaround for GATT servers that do not persist
* subscriptions.
*
* This flag will disable the automatic resubscription. It is useful
* if the application layer knows that the GATT server remembers
* subscriptions from previous connections and wants to avoid renewing
* the subscriptions.
* This flag will disable the automatic resubscription. It is useful
* if the application layer knows that the GATT server remembers
* subscriptions from previous connections and wants to avoid renewing
* the subscriptions.
*/
BT_GATT_SUBSCRIBE_FLAG_NO_RESUB,
/** Write pending flag
*
* If set, indicates write operation is pending waiting remote end to
* respond.
* If set, indicates write operation is pending waiting remote end to
* respond.
*/
BT_GATT_SUBSCRIBE_FLAG_WRITE_PENDING,
@ -1361,7 +1369,7 @@ struct bt_gatt_subscribe_params {
* this callback. Notification callback with NULL data will not be called if
* 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.
*
* @param conn Connection object.
@ -1374,15 +1382,15 @@ int bt_gatt_subscribe(struct bt_conn *conn,
/** @brief Unsubscribe Attribute Value Notification
*
* This procedure unsubscribe to value notification using the Client
* Characteristic Configuration handle. Notification callback with NULL data
* will be called if subscription was removed by this call, until then the
* parameters cannot be reused.
* This procedure unsubscribe to value notification using the Client
* Characteristic Configuration handle. Notification callback with NULL data
* will be called if subscription was removed by this call, until then the
* parameters cannot be reused.
*
* @param conn Connection object.
* @param params Subscribe parameters.
* @param conn Connection object.
* @param params Subscribe parameters.
*
* @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.
*/
int bt_gatt_unsubscribe(struct bt_conn *conn,
struct bt_gatt_subscribe_params *params);

2
include/bluetooth/hci_err.h
View file

@ -14,7 +14,7 @@
extern "C" {
#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_UNKNOWN_CMD 0x01
#define BT_HCI_ERR_UNKNOWN_CONN_ID 0x02

40
include/bluetooth/l2cap.h
View file

@ -26,17 +26,17 @@
extern "C" {
#endif
/* L2CAP header size, used for buffer size calculations */
/** L2CAP header size, used for buffer size calculations */
#define BT_L2CAP_HDR_SIZE 4
/** @def BT_L2CAP_BUF_SIZE
*
* Helper to calculate needed outgoing buffer size, useful e.g. for
* creating buffer pools.
* Helper to calculate needed outgoing buffer size, useful e.g. for
* creating buffer pools.
*
* @param mtu Needed L2CAP MTU.
* @param mtu Needed L2CAP MTU.
*
* @return Needed buffer size to match the requested L2CAP MTU.
* @return Needed buffer size to match the requested L2CAP MTU.
*/
#define BT_L2CAP_BUF_SIZE(mtu) (BT_BUF_RESERVE + \
BT_HCI_ACL_HDR_SIZE + BT_L2CAP_HDR_SIZE + \
@ -51,9 +51,10 @@ struct bt_l2cap_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
* dealing with setting channel to proper state depending on operational
* context.
/** @brief Life-span states of L2CAP CoC channel.
*
* Used only by internal APIs dealing with setting channel to proper state
* depending on operational context.
*/
typedef enum bt_l2cap_chan_state {
/** Channel disconnected */
@ -150,7 +151,7 @@ struct bt_l2cap_le_chan {
* @param _ch Address of object of bt_l2cap_chan type
*
* @return Address of in memory bt_l2cap_le_chan object type containing
* the address of in question object.
* the address of in question object.
*/
#define BT_L2CAP_LE_CHAN(_ch) CONTAINER_OF(_ch, struct bt_l2cap_le_chan, chan)
@ -229,14 +230,16 @@ struct bt_l2cap_chan_ops {
* @param buf Buffer containing incoming data.
*
* @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
* been processed by calling bt_l2cap_chan_recv_complete passing back
* the buffer received with its original user_data which contains the
* number of segments/credits used by the packet.
* @return -EINPROGRESS in case where user has to confirm once the data
* has been processed by calling
* @ref bt_l2cap_chan_recv_complete passing back
* 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);
/* Channel sent callback
/** Channel sent callback
*
* If this callback is provided it will be called whenever a SDU has
* been completely sent.
@ -245,7 +248,7 @@ struct bt_l2cap_chan_ops {
*/
void (*sent)(struct bt_l2cap_chan *chan);
/* Channel status callback
/** Channel status callback
*
* If this callback is provided it will be called whenever the
* channel status changes.
@ -289,10 +292,9 @@ struct bt_l2cap_server {
* @param chan Pointer to received the allocated channel
*
* @return 0 in case of success or negative value in case of error.
* Possible return values:
* -ENOMEM if no available space for new channel.
* -EACCES if application did not authorize the connection.
* -EPERM if encryption key size is too short.
* @return -ENOMEM if no available space for new channel.
* @return -EACCES if application did not authorize the connection.
* @return -EPERM if encryption key size is too short.
*/
int (*accept)(struct bt_conn *conn, struct bt_l2cap_chan **chan);