espressif/esp-nimble
1
0
Fork 0
mirror of https://github.com/espressif/esp-nimble.git synced 2026-08-03 16:47:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

host/gatt: add and update doxygen comments for the header file

Browse Source 
Adds missing macros and structures documentation. Corrects arguments names in functions documentation.
This commit is contained in:
Wojciech Pietraszewski
2023-08-03 15:35:31 +02:00
committed by Szymon Janc
parent e718a2fb22
commit 601b1056aa
1 changed files with 170 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nimble/host/include/host/ble_gatt.h
+170 -14
View File
@@ -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,