This is an automated email from the ASF dual-hosted git repository.
janc pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/mynewt-nimble.git
The following commit(s) were added to refs/heads/master by this push:
new 601b1056 host/gatt: add and update doxygen comments for the header file
601b1056 is described below
commit 601b1056aa5f371964343f851610104880ff2e29
Author: Wojciech Pietraszewski <[email protected]>
AuthorDate: Wed Jul 26 16:41:37 2023 +0200
host/gatt: add and update doxygen comments for the header file
Adds missing macros and structures documentation. Corrects arguments names
in functions documentation.
---
nimble/host/include/host/ble_gatt.h | 184 +++++++++++++++++++++++++++++++++---
1 file changed, 170 insertions(+), 14 deletions(-)
diff --git a/nimble/host/include/host/ble_gatt.h
b/nimble/host/include/host/ble_gatt.h
index 312126f5..b3bea2bd 100644
--- a/nimble/host/include/host/ble_gatt.h
+++ b/nimble/host/include/host/ble_gatt.h
@@ -38,80 +38,220 @@ struct ble_hs_conn;
struct ble_att_error_rsp;
struct ble_hs_cfg;
+/**
+ * @defgroup ble_gatt_register_op_codes Generic Attribute Profile (GATT)
Registration Operation Codes
+ * @{
+ */
+
+/** GATT Service registration. */
#define BLE_GATT_REGISTER_OP_SVC 1
+
+/** GATT Characteristic registration. */
#define BLE_GATT_REGISTER_OP_CHR 2
+
+/** GATT Descriptor registration. */
#define BLE_GATT_REGISTER_OP_DSC 3
+/** @} */
+
+/**
+ * @defgroup ble_gatt_uuid Generic Attribute Profile (GATT) Service and
Descriptor UUIDs
+ * @{
+ */
+
+/** GATT service 16-bit UUID. */
#define BLE_GATT_SVC_UUID16 0x1801
+
+/** GATT Client Characteristic Configuration descriptor 16-bit UUID. */
#define BLE_GATT_DSC_CLT_CFG_UUID16 0x2902
+/** @} */
+
+/**
+ * @defgroup ble_gatt_chr_properties Generic Attribute Profile (GATT)
Characteristic Properties
+ * @{
+ */
+
+/** Characteristic property: Broadcast. */
#define BLE_GATT_CHR_PROP_BROADCAST 0x01
+
+/** Characteristic property: Read. */
#define BLE_GATT_CHR_PROP_READ 0x02
+
+/** Characteristic property: Write Without Response. */
#define BLE_GATT_CHR_PROP_WRITE_NO_RSP 0x04
+
+/** Characteristic property: Write. */
#define BLE_GATT_CHR_PROP_WRITE 0x08
+
+/** Characteristic property: Notify. */
#define BLE_GATT_CHR_PROP_NOTIFY 0x10
+
+/** Characteristic property: Indicate. */
#define BLE_GATT_CHR_PROP_INDICATE 0x20
+
+/** Characteristic property: Authenticated Signed Write. */
#define BLE_GATT_CHR_PROP_AUTH_SIGN_WRITE 0x40
+
+/** Characteristic property: Extended Properties. */
#define BLE_GATT_CHR_PROP_EXTENDED 0x80
+/** @} */
+
+/** @defgroup ble_gatt_access_op_codes Generic Attribute Profile (GATT) Access
Operation Codes
+ * @{
+ */
+
+/** GATT attribute access operation: Read characteristic. */
#define BLE_GATT_ACCESS_OP_READ_CHR 0
+
+/** GATT attribute access operation: Write characteristic. */
#define BLE_GATT_ACCESS_OP_WRITE_CHR 1
+
+/** GATT attribute access operation: Read descriptor. */
#define BLE_GATT_ACCESS_OP_READ_DSC 2
+
+/** GATT attribute access operation: Write descriptor. */
#define BLE_GATT_ACCESS_OP_WRITE_DSC 3
+/** @} */
+
+/**
+ * @defgroup ble_gatt_chr_flags Generic Attribute Profile (GATT)
Characteristic Flags
+ * @{
+ */
+
+/** GATT Characteristic Flag: Broadcast. */
#define BLE_GATT_CHR_F_BROADCAST 0x0001
+
+/** GATT Characteristic Flag: Read. */
#define BLE_GATT_CHR_F_READ 0x0002
+
+/** GATT Characteristic Flag: Write without Response. */
#define BLE_GATT_CHR_F_WRITE_NO_RSP 0x0004
+
+/** GATT Characteristic Flag: Write. */
#define BLE_GATT_CHR_F_WRITE 0x0008
+
+/** GATT Characteristic Flag: Notify. */
#define BLE_GATT_CHR_F_NOTIFY 0x0010
+
+/** GATT Characteristic Flag: Indicate. */
#define BLE_GATT_CHR_F_INDICATE 0x0020
+
+/** GATT Characteristic Flag: Authenticated Signed Writes. */
#define BLE_GATT_CHR_F_AUTH_SIGN_WRITE 0x0040
+
+/** GATT Characteristic Flag: Reliable Writes. */
#define BLE_GATT_CHR_F_RELIABLE_WRITE 0x0080
+
+/** GATT Characteristic Flag: Auxiliary Writes. */
#define BLE_GATT_CHR_F_AUX_WRITE 0x0100
+
+/** GATT Characteristic Flag: Read Encrypted. */
#define BLE_GATT_CHR_F_READ_ENC 0x0200
+
+/** GATT Characteristic Flag: Read Authenticated. */
#define BLE_GATT_CHR_F_READ_AUTHEN 0x0400
+
+/** GATT Characteristic Flag: Read Authorized. */
#define BLE_GATT_CHR_F_READ_AUTHOR 0x0800
+
+/** GATT Characteristic Flag: Write Encrypted. */
#define BLE_GATT_CHR_F_WRITE_ENC 0x1000
+
+/** GATT Characteristic Flag: Write Authenticated. */
#define BLE_GATT_CHR_F_WRITE_AUTHEN 0x2000
+
+/** GATT Characteristic Flag: Write Authorized. */
#define BLE_GATT_CHR_F_WRITE_AUTHOR 0x4000
+
+/** @} */
+
+/**
+ * @defgroup ble_gatt_service_types Generic Attribute Profile (GATT) Service
Types
+ * @{
+ */
+
+/** GATT Service Type: End of Services. */
#define BLE_GATT_SVC_TYPE_END 0
+
+/** GATT Service Type: Primary Service. */
#define BLE_GATT_SVC_TYPE_PRIMARY 1
+
+/** GATT Service Type: Secondary Service. */
#define BLE_GATT_SVC_TYPE_SECONDARY 2
+/** @} */
+
/*** @client. */
+/** Represents a GATT error. */
struct ble_gatt_error {
+ /** The GATT status code indicating the type of error. */
uint16_t status;
+
+ /** The attribute handle associated with the error. */
uint16_t att_handle;
};
+/** Represents a GATT Service. */
struct ble_gatt_svc {
+ /** The start handle of the GATT service. */
uint16_t start_handle;
+
+ /** The end handle of the GATT service. */
uint16_t end_handle;
+
+ /** The UUID of the GATT service. */
ble_uuid_any_t uuid;
};
+
+/** Represents a GATT attribute. */
struct ble_gatt_attr {
+ /** The handle of the GATT attribute. */
uint16_t handle;
+
+ /** The offset of the data within the attribute. */
uint16_t offset;
+
+ /** Pointer to the data buffer represented by an os_mbuf. */
struct os_mbuf *om;
};
+
+/** Represents a GATT characteristic. */
struct ble_gatt_chr {
+ /** The handle of the GATT characteristic definition. */
uint16_t def_handle;
+
+ /** The handle of the GATT characteristic value. */
uint16_t val_handle;
+
+ /** The properties of the GATT characteristic. */
uint8_t properties;
+
+ /** The UUID of the GATT characteristic. */
ble_uuid_any_t uuid;
};
+
+/** Represents a GATT descriptor. */
struct ble_gatt_dsc {
+ /** The handle of the GATT descriptor. */
uint16_t handle;
+
+ /** The UUID of the GATT descriptor. */
ble_uuid_any_t uuid;
};
+/** Function prototype for the GATT MTU exchange callback. */
typedef int ble_gatt_mtu_fn(uint16_t conn_handle,
const struct ble_gatt_error *error,
uint16_t mtu, void *arg);
+
+/** Function prototype for the GATT service discovery callback. */
typedef int ble_gatt_disc_svc_fn(uint16_t conn_handle,
const struct ble_gatt_error *error,
const struct ble_gatt_svc *service,
@@ -137,10 +277,12 @@ typedef int ble_gatt_reliable_attr_fn(uint16_t
conn_handle,
struct ble_gatt_attr *attrs,
uint8_t num_attrs, void *arg);
+/** Function prototype for the GATT characteristic callback. */
typedef int ble_gatt_chr_fn(uint16_t conn_handle,
const struct ble_gatt_error *error,
const struct ble_gatt_chr *chr, void *arg);
+/** Function prototype for the GATT descriptor callback. */
typedef int ble_gatt_dsc_fn(uint16_t conn_handle,
const struct ble_gatt_error *error,
uint16_t chr_val_handle,
@@ -180,7 +322,7 @@ int ble_gattc_disc_all_svcs(uint16_t conn_handle,
*
* @param conn_handle The connection over which to execute the
* procedure.
- * @param service_uuid128 The 128-bit UUID of the service to discover.
+ * @param uuid The 128-bit UUID of the service to discover.
* @param cb The function to call to report procedure status
* updates; null for no callback.
* @param cb_arg The optional argument to pass to the callback
@@ -240,7 +382,7 @@ int ble_gattc_disc_all_chrs(uint16_t conn_handle, uint16_t
start_handle,
* the service definition handle).
* @param end_handle The handle to end the search at (generally the
* last handle in the service).
- * @param chr_uuid128 The 128-bit UUID of the characteristic to
+ * @param uuid The 128-bit UUID of the characteristic to
* discover.
* @param cb The function to call to report procedure status
* updates; null for no callback.
@@ -258,9 +400,9 @@ int ble_gattc_disc_chrs_by_uuid(uint16_t conn_handle,
uint16_t start_handle,
*
* @param conn_handle The connection over which to execute the
* procedure.
- * @param chr_val_handle The handle of the characteristic value
+ * @param start_handle The handle of the characteristic value
* attribute.
- * @param chr_end_handle The last handle in the characteristic
+ * @param end_handle The last handle in the characteristic
* definition.
* @param cb The function to call to report procedure status
* updates; null for no callback.
@@ -298,6 +440,8 @@ int ble_gattc_read(uint16_t conn_handle, uint16_t
attr_handle,
* handle of the service definition).
* @param end_handle The last handle to search (generally the
* last handle in the service definition).
+ * @param uuid The 128-bit UUID of the characteristic to
+ * read.
* @param cb The function to call to report procedure status
* updates; null for no callback.
* @param cb_arg The optional argument to pass to the callback
@@ -315,6 +459,8 @@ int ble_gattc_read_by_uuid(uint16_t conn_handle, uint16_t
start_handle,
* @param conn_handle The connection over which to execute the
* procedure.
* @param handle The handle of the characteristic value to read.
+ * @param offset The offset within the characteristic value to
+ * start reading.
* @param cb The function to call to report procedure status
* updates; null for no callback.
* @param cb_arg The optional argument to pass to the callback
@@ -351,7 +497,7 @@ int ble_gattc_read_mult(uint16_t conn_handle, const
uint16_t *handles,
* procedure.
* @param attr_handle The handle of the characteristic value to write
* to.
- * @param txom The value to write to the characteristic.
+ * @param om The value to write to the characteristic.
*
* @return 0 on success; nonzero on failure.
*/
@@ -366,8 +512,8 @@ int ble_gattc_write_no_rsp(uint16_t conn_handle, uint16_t
attr_handle,
* procedure.
* @param attr_handle The handle of the characteristic value to write
* to.
- * @param value The value to write to the characteristic.
- * @param value_len The number of bytes to write.
+ * @param data The value to write to the characteristic.
+ * @param data_len The number of bytes to write.
*
* @return 0 on success; nonzero on failure.
*/
@@ -382,7 +528,7 @@ int ble_gattc_write_no_rsp_flat(uint16_t conn_handle,
uint16_t attr_handle,
* procedure.
* @param attr_handle The handle of the characteristic value to write
* to.
- * @param txom The value to write to the characteristic.
+ * @param om The value to write to the characteristic.
* @param cb The function to call to report procedure status
* updates; null for no callback.
* @param cb_arg The optional argument to pass to the callback
@@ -401,8 +547,8 @@ int ble_gattc_write(uint16_t conn_handle, uint16_t
attr_handle,
* procedure.
* @param attr_handle The handle of the characteristic value to write
* to.
- * @param value The value to write to the characteristic.
- * @param value_len The number of bytes to write.
+ * @param data The value to write to the characteristic.
+ * @param data_len The number of bytes to write.
* @param cb The function to call to report procedure status
* updates; null for no callback.
* @param cb_arg The optional argument to pass to the callback
@@ -422,7 +568,8 @@ int ble_gattc_write_flat(uint16_t conn_handle, uint16_t
attr_handle,
* procedure.
* @param attr_handle The handle of the characteristic value to write
* to.
- * @param txom The value to write to the characteristic.
+ * @param offset The offset at which to begin writing the value.
+ * @param om The value to write to the characteristic.
* @param cb The function to call to report procedure status
* updates; null for no callback.
* @param cb_arg The optional argument to pass to the callback
@@ -464,9 +611,9 @@ int ble_gattc_write_reliable(uint16_t conn_handle,
*
* @param conn_handle The connection over which to execute the
* procedure.
- * @param chr_val_handle The attribute handle to indicate in the
+ * @param att_handle The attribute handle to indicate in the
* outgoing notification.
- * @param txom The value to write to the characteristic.
+ * @param om The value to write to the characteristic.
*
* @return 0 on success; nonzero on failure.
*/
@@ -539,16 +686,21 @@ int ble_gatts_indicate(uint16_t conn_handle, uint16_t
chr_val_handle);
*/
int ble_gattc_indicate(uint16_t conn_handle, uint16_t chr_val_handle);
+/** Initialize the BLE GATT client. */
int ble_gattc_init(void);
/*** @server. */
struct ble_gatt_access_ctxt;
+
+/** Type definition for GATT access callback function. */
typedef int ble_gatt_access_fn(uint16_t conn_handle, uint16_t attr_handle,
struct ble_gatt_access_ctxt *ctxt, void *arg);
+/** Type definition for GATT characteristic flags. */
typedef uint16_t ble_gatt_chr_flags;
+/** Represents the definition of a GATT characteristic. */
struct ble_gatt_chr_def {
/**
* Pointer to characteristic UUID; use BLE_UUIDxx_DECLARE macros to declare
@@ -585,6 +737,7 @@ struct ble_gatt_chr_def {
uint16_t *val_handle;
};
+/** Represents the definition of a GATT service. */
struct ble_gatt_svc_def {
/**
* One of the following:
@@ -614,6 +767,7 @@ struct ble_gatt_svc_def {
const struct ble_gatt_chr_def *characteristics;
};
+/** Represents the definition of a GATT descriptor. */
struct ble_gatt_dsc_def {
/**
* Pointer to descriptor UUID; use BLE_UUIDxx_DECLARE macros to declare
@@ -759,6 +913,7 @@ struct ble_gatt_register_ctxt {
};
};
+/** Type definition for GATT registration callback function. */
typedef void ble_gatt_register_fn(struct ble_gatt_register_ctxt *ctxt,
void *arg);
@@ -855,7 +1010,7 @@ int ble_gatts_find_chr(const ble_uuid_t *svc_uuid, const
ble_uuid_t *chr_uuid,
* @param svc_uuid The UUID of the grandparent service.
* @param chr_uuid The UUID of the parent characteristic.
* @param dsc_uuid The UUID of the descriptor ro look up.
- * @param out_handle On success, populated with the handle
+ * @param out_dsc_handle On success, populated with the handle
* of the descriptor attribute. Pass null if
* you don't need this value.
*
@@ -867,6 +1022,7 @@ int ble_gatts_find_chr(const ble_uuid_t *svc_uuid, const
ble_uuid_t *chr_uuid,
int ble_gatts_find_dsc(const ble_uuid_t *svc_uuid, const ble_uuid_t *chr_uuid,
const ble_uuid_t *dsc_uuid, uint16_t *out_dsc_handle);
+/** Type definition for GATT service iteration callback function. */
typedef void (*ble_gatt_svc_foreach_fn)(const struct ble_gatt_svc_def *svc,
uint16_t handle,
uint16_t end_group_handle,
