From d366629761d98fa4d4d29e168a4b46d45b2166e3 Mon Sep 17 00:00:00 2001 From: Chen Jian Hua Date: Tue, 24 Dec 2024 15:19:59 +0800 Subject: [PATCH] Merge branch 'refactor/optimize_ble_gatt_api_doc' into 'master' refactor(bt/bluedroid): Optimize BLE GATT related APIs reference See merge request espressif/esp-idf!34650 (cherry picked from commit 19b5381c9920a30d1288779181a26df3394c2527) 7320c77d refactor(bt/bluedroid): Optimize BLE GATT related APIs reference 8a80617c refactor(bt/bluedroid): Optimize BLE GATT related APIs reference 0ac97e98 refactor(bt/bluedroid): Optimize BLE GATT related APIs reference 27b17c69 refactor(bt/bluedroid): Optimize BLE GATT related APIs reference ea8d7686 docs: Update gattc & gatts api header files f508772f Apply 3 suggestion(s) to 2 file(s) 03469b52 Apply 2 suggestion(s) to 1 file(s) aa2cf7a5 docs: fix minor issue 46dc6e96 docs(ble): Replaced "closed" with "terminated" for physical connection. Co-authored-by: Wei Yu Han --- .../bluedroid/api/include/api/esp_gattc_api.h | 1062 +++++++++-------- .../bluedroid/api/include/api/esp_gatts_api.h | 616 +++++----- 2 files changed, 905 insertions(+), 773 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h index a4fd3c9574..0f5b83d351 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h @@ -15,430 +15,463 @@ extern "C" { #endif -/// GATT Client callback function events +/** + * @brief GATT Client callback function events + */ typedef enum { - ESP_GATTC_REG_EVT = 0, /*!< When GATT client is registered, the event comes */ - ESP_GATTC_UNREG_EVT = 1, /*!< When GATT client is unregistered, the event comes */ - ESP_GATTC_OPEN_EVT = 2, /*!< When GATT virtual connection is set up, the event comes */ - ESP_GATTC_READ_CHAR_EVT = 3, /*!< When GATT characteristic is read, the event comes */ - ESP_GATTC_WRITE_CHAR_EVT = 4, /*!< When GATT characteristic write operation completes, the event comes */ - ESP_GATTC_CLOSE_EVT = 5, /*!< When GATT virtual connection is closed, the event comes */ - ESP_GATTC_SEARCH_CMPL_EVT = 6, /*!< When GATT service discovery is completed, the event comes */ - ESP_GATTC_SEARCH_RES_EVT = 7, /*!< When GATT service discovery result is got, the event comes */ - ESP_GATTC_READ_DESCR_EVT = 8, /*!< When GATT characteristic descriptor read completes, the event comes */ - ESP_GATTC_WRITE_DESCR_EVT = 9, /*!< When GATT characteristic descriptor write completes, the event comes */ - ESP_GATTC_NOTIFY_EVT = 10, /*!< When GATT notification or indication arrives, the event comes */ - ESP_GATTC_PREP_WRITE_EVT = 11, /*!< When GATT prepare-write operation completes, the event comes */ - ESP_GATTC_EXEC_EVT = 12, /*!< When write execution completes, the event comes */ - ESP_GATTC_ACL_EVT = 13, /*!< When ACL connection is up, the event comes */ - ESP_GATTC_CANCEL_OPEN_EVT = 14, /*!< When GATT client ongoing connection is cancelled, the event comes */ - ESP_GATTC_SRVC_CHG_EVT = 15, /*!< When "service changed" occurs, the event comes */ - ESP_GATTC_ENC_CMPL_CB_EVT = 17, /*!< When encryption procedure completes, the event comes */ - ESP_GATTC_CFG_MTU_EVT = 18, /*!< When configuration of MTU completes, the event comes */ - ESP_GATTC_ADV_DATA_EVT = 19, /*!< When advertising of data, the event comes */ - ESP_GATTC_MULT_ADV_ENB_EVT = 20, /*!< When multi-advertising is enabled, the event comes */ - ESP_GATTC_MULT_ADV_UPD_EVT = 21, /*!< When multi-advertising parameters are updated, the event comes */ - ESP_GATTC_MULT_ADV_DATA_EVT = 22, /*!< When multi-advertising data arrives, the event comes */ - ESP_GATTC_MULT_ADV_DIS_EVT = 23, /*!< When multi-advertising is disabled, the event comes */ - ESP_GATTC_CONGEST_EVT = 24, /*!< When GATT connection congestion comes, the event comes */ - ESP_GATTC_BTH_SCAN_ENB_EVT = 25, /*!< When batch scan is enabled, the event comes */ - ESP_GATTC_BTH_SCAN_CFG_EVT = 26, /*!< When batch scan storage is configured, the event comes */ - ESP_GATTC_BTH_SCAN_RD_EVT = 27, /*!< When Batch scan read event is reported, the event comes */ - ESP_GATTC_BTH_SCAN_THR_EVT = 28, /*!< When Batch scan threshold is set, the event comes */ - ESP_GATTC_BTH_SCAN_PARAM_EVT = 29, /*!< When Batch scan parameters are set, the event comes */ - ESP_GATTC_BTH_SCAN_DIS_EVT = 30, /*!< When Batch scan is disabled, the event comes */ - ESP_GATTC_SCAN_FLT_CFG_EVT = 31, /*!< When Scan filter configuration completes, the event comes */ - ESP_GATTC_SCAN_FLT_PARAM_EVT = 32, /*!< When Scan filter parameters are set, the event comes */ - ESP_GATTC_SCAN_FLT_STATUS_EVT = 33, /*!< When Scan filter status is reported, the event comes */ - ESP_GATTC_ADV_VSC_EVT = 34, /*!< When advertising vendor spec content event is reported, the event comes */ - ESP_GATTC_REG_FOR_NOTIFY_EVT = 38, /*!< When register for notification of a service completes, the event comes */ - ESP_GATTC_UNREG_FOR_NOTIFY_EVT = 39, /*!< When unregister for notification of a service completes, the event comes */ - ESP_GATTC_CONNECT_EVT = 40, /*!< When the ble physical connection is set up, the event comes */ - ESP_GATTC_DISCONNECT_EVT = 41, /*!< When the ble physical connection disconnected, the event comes */ - ESP_GATTC_READ_MULTIPLE_EVT = 42, /*!< When the ble characteristic or descriptor multiple complete, the event comes */ - ESP_GATTC_QUEUE_FULL_EVT = 43, /*!< When the gattc command queue full, the event comes */ - ESP_GATTC_SET_ASSOC_EVT = 44, /*!< When the ble gattc set the associated address complete, the event comes */ - ESP_GATTC_GET_ADDR_LIST_EVT = 45, /*!< When the ble get gattc address list in cache finish, the event comes */ - ESP_GATTC_DIS_SRVC_CMPL_EVT = 46, /*!< When the ble discover service complete, the event comes */ - ESP_GATTC_READ_MULTI_VAR_EVT = 47, /*!< When read multiple variable characteristic complete, the event comes */ + ESP_GATTC_REG_EVT = 0, /*!< This event is triggered when a GATT Client application is registered using `esp_ble_gattc_app_register`. */ + ESP_GATTC_UNREG_EVT = 1, /*!< This event is triggered when a GATT Client application is unregistered using `esp_ble_gattc_app_unregister`. */ + ESP_GATTC_OPEN_EVT = 2, /*!< This event is triggered when a GATT virtual connection is set up using `esp_ble_gattc_open`. */ + ESP_GATTC_READ_CHAR_EVT = 3, /*!< This event is triggered upon the completion of a GATT characteristic read operation using `esp_ble_gattc_read_char`. */ + ESP_GATTC_WRITE_CHAR_EVT = 4, /*!< This event is triggered upon the completion of a GATT characteristic write operation using `esp_ble_gattc_write_char`. */ + ESP_GATTC_CLOSE_EVT = 5, /*!< This event is triggered when a GATT virtual connection is closed via `esp_ble_gattc_close`, or when the physical connection is terminated. */ + ESP_GATTC_SEARCH_CMPL_EVT = 6, /*!< This event is triggered upon the completion of a service discovery using `esp_ble_gattc_search_service`. */ + ESP_GATTC_SEARCH_RES_EVT = 7, /*!< This event is triggered each time a service result is obtained using `esp_ble_gattc_search_service`. */ + ESP_GATTC_READ_DESCR_EVT = 8, /*!< This event is triggered upon the completion of a GATT characteristic descriptor read operation using `esp_ble_gattc_read_char_descr`. */ + ESP_GATTC_WRITE_DESCR_EVT = 9, /*!< This event is triggered upon the completion of a GATT characteristic descriptor write operation using `esp_ble_gattc_write_char_descr`. */ + ESP_GATTC_NOTIFY_EVT = 10, /*!< This event is triggered when a GATT notification or indication is received from the Server. */ + ESP_GATTC_PREP_WRITE_EVT = 11, /*!< This event is triggered upon the completion of a GATT prepare-write operation using `esp_ble_gattc_prepare_write`. */ + ESP_GATTC_EXEC_EVT = 12, /*!< This event is triggered upon the completion of a GATT write execution using `esp_ble_gattc_execute_write` .*/ + ESP_GATTC_ACL_EVT = 13, /*!< Deprecated. */ + ESP_GATTC_CANCEL_OPEN_EVT = 14, /*!< Deprecated. */ + ESP_GATTC_SRVC_CHG_EVT = 15, /*!< This event is triggered when a service changed indication is received from the Server, indicating that the attribute database on the Server has been modified (e.g., services have been added, removed). */ + ESP_GATTC_ENC_CMPL_CB_EVT = 17, /*!< Deprecated. */ + ESP_GATTC_CFG_MTU_EVT = 18, /*!< This event is triggered upon the completion of the MTU configuration with `esp_ble_gattc_send_mtu_req`. */ + ESP_GATTC_ADV_DATA_EVT = 19, /*!< Deprecated. */ + ESP_GATTC_MULT_ADV_ENB_EVT = 20, /*!< Deprecated. */ + ESP_GATTC_MULT_ADV_UPD_EVT = 21, /*!< Deprecated. */ + ESP_GATTC_MULT_ADV_DATA_EVT = 22, /*!< Deprecated. */ + ESP_GATTC_MULT_ADV_DIS_EVT = 23, /*!< Deprecated. */ + ESP_GATTC_CONGEST_EVT = 24, /*!< This event is triggered when the GATT connection is congested. */ + ESP_GATTC_BTH_SCAN_ENB_EVT = 25, /*!< Deprecated. */ + ESP_GATTC_BTH_SCAN_CFG_EVT = 26, /*!< Deprecated. */ + ESP_GATTC_BTH_SCAN_RD_EVT = 27, /*!< Deprecated. */ + ESP_GATTC_BTH_SCAN_THR_EVT = 28, /*!< Deprecated. */ + ESP_GATTC_BTH_SCAN_PARAM_EVT = 29, /*!< Deprecated. */ + ESP_GATTC_BTH_SCAN_DIS_EVT = 30, /*!< Deprecated. */ + ESP_GATTC_SCAN_FLT_CFG_EVT = 31, /*!< Deprecated. */ + ESP_GATTC_SCAN_FLT_PARAM_EVT = 32, /*!< Deprecated. */ + ESP_GATTC_SCAN_FLT_STATUS_EVT = 33, /*!< Deprecated. */ + ESP_GATTC_ADV_VSC_EVT = 34, /*!< Deprecated. */ + ESP_GATTC_REG_FOR_NOTIFY_EVT = 38, /*!< This event is triggered upon the completion of a service notification registration using `esp_ble_gattc_register_for_notify`. */ + ESP_GATTC_UNREG_FOR_NOTIFY_EVT = 39, /*!< This event is triggered upon the completion of a service notification unregistration using `esp_ble_gattc_unregister_for_notify`. */ + ESP_GATTC_CONNECT_EVT = 40, /*!< This event is triggered when the physical connection is set up. */ + ESP_GATTC_DISCONNECT_EVT = 41, /*!< This event is triggered when the physical connection is terminated. */ + ESP_GATTC_READ_MULTIPLE_EVT = 42, /*!< This event is triggered when the multiple characteristic or descriptor values are retrieved using `esp_ble_gattc_read_multiple`. */ + ESP_GATTC_QUEUE_FULL_EVT = 43, /*!< This event is triggered when the GATTC command queue is full. */ + ESP_GATTC_SET_ASSOC_EVT = 44, /*!< This event is triggered when the association between the source and the remote address is added or deleted using `esp_ble_gattc_cache_assoc`. */ + ESP_GATTC_GET_ADDR_LIST_EVT = 45, /*!< This event is triggered when retrieving the address list from the GATTC cache is completed using `esp_ble_gattc_cache_get_addr_list`. */ + ESP_GATTC_DIS_SRVC_CMPL_EVT = 46, /*!< This event is triggered when the GATT service discovery is completed. */ + ESP_GATTC_READ_MULTI_VAR_EVT = 47, /*!< This event is triggered when multiple variable length characteristic values are retrieved using `esp_ble_gattc_read_multiple`. */ } esp_gattc_cb_event_t; /** - * @brief Gatt client callback parameters union + * @brief GATT Client callback parameters */ typedef union { + /** - * @brief ESP_GATTC_REG_EVT + * @brief Callback parameter for the event `ESP_GATTC_REG_EVT` */ struct gattc_reg_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t app_id; /*!< Application id which input in register API */ - } reg; /*!< Gatt client callback param of ESP_GATTC_REG_EVT */ + uint16_t app_id; /*!< Application ID */ + } reg; /*!< Callback parameter for the event `ESP_GATTC_REG_EVT` */ /** - * @brief ESP_GATTC_OPEN_EVT + * @brief Callback parameter for the event `ESP_GATTC_OPEN_EVT`. */ struct gattc_open_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ + uint16_t conn_id; /*!< Connection ID */ + esp_bd_addr_t remote_bda; /*!< Remote Bluetooth device address */ uint16_t mtu; /*!< MTU size */ - } open; /*!< Gatt client callback param of ESP_GATTC_OPEN_EVT */ + } open; /*!< Callback parameter for the event `ESP_GATTC_OPEN_EVT` */ /** - * @brief ESP_GATTC_CLOSE_EVT + * @brief Callback parameter for the event `ESP_GATTC_CLOSE_EVT` */ struct gattc_close_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ + uint16_t conn_id; /*!< Connection ID */ esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ - esp_gatt_conn_reason_t reason; /*!< The reason of gatt connection close */ - } close; /*!< Gatt client callback param of ESP_GATTC_CLOSE_EVT */ + esp_gatt_conn_reason_t reason; /*!< The reason of GATT connection close */ + } close; /*!< Callback parameter for the event `ESP_GATTC_CLOSE_EVT` */ /** - * @brief ESP_GATTC_CFG_MTU_EVT + * @brief Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT` */ struct gattc_cfg_mtu_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ + uint16_t conn_id; /*!< Connection ID */ uint16_t mtu; /*!< MTU size */ - } cfg_mtu; /*!< Gatt client callback param of ESP_GATTC_CFG_MTU_EVT */ + } cfg_mtu; /*!< Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT` */ /** - * @brief ESP_GATTC_SEARCH_CMPL_EVT + * @brief Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT` */ struct gattc_search_cmpl_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ + uint16_t conn_id; /*!< Connection ID */ esp_service_source_t searched_service_source; /*!< The source of the service information */ - } search_cmpl; /*!< Gatt client callback param of ESP_GATTC_SEARCH_CMPL_EVT */ + } search_cmpl; /*!< Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT` */ /** - * @brief ESP_GATTC_SEARCH_RES_EVT + * @brief Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT` */ struct gattc_search_res_evt_param { - uint16_t conn_id; /*!< Connection id */ + uint16_t conn_id; /*!< Connection ID */ uint16_t start_handle; /*!< Service start handle */ uint16_t end_handle; /*!< Service end handle */ - esp_gatt_id_t srvc_id; /*!< Service id, include service uuid and other information */ - bool is_primary; /*!< True if this is the primary service */ - } search_res; /*!< Gatt client callback param of ESP_GATTC_SEARCH_RES_EVT */ + esp_gatt_id_t srvc_id; /*!< Service ID, including service UUID and other information */ + bool is_primary; /*!< True indicates a primary service, false otherwise */ + } search_res; /*!< Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT` */ /** - * @brief ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT, ESP_GATTC_READ_MULTIPLE_EVT, ESP_GATTC_READ_MULTI_VAR_EVT + * @brief Callback parameter for the events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`, + * `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT` */ struct gattc_read_char_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ + uint16_t conn_id; /*!< Connection ID */ uint16_t handle; /*!< Characteristic handle */ uint8_t *value; /*!< Characteristic value */ uint16_t value_len; /*!< Characteristic value length */ - } read; /*!< Gatt client callback param of ESP_GATTC_READ_CHAR_EVT */ + } read; /*!< Callback parameter for events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`, + `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT` */ /** - * @brief ESP_GATTC_WRITE_CHAR_EVT, ESP_GATTC_PREP_WRITE_EVT, ESP_GATTC_WRITE_DESCR_EVT + * @brief Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT`. */ struct gattc_write_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - uint16_t handle; /*!< The Characteristic or descriptor handle */ - uint16_t offset; /*!< The prepare write offset, this value is valid only when prepare write */ - } write; /*!< Gatt client callback param of ESP_GATTC_WRITE_DESCR_EVT */ + uint16_t conn_id; /*!< Connection ID */ + uint16_t handle; /*!< The characteristic or descriptor handle */ + uint16_t offset; /*!< The position offset to write. This value is valid only for prepare write operation. */ + } write; /*!< Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT` */ /** - * @brief ESP_GATTC_EXEC_EVT + * @brief Callback parameter for the event `ESP_GATTC_EXEC_EVT` */ struct gattc_exec_cmpl_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - } exec_cmpl; /*!< Gatt client callback param of ESP_GATTC_EXEC_EVT */ + uint16_t conn_id; /*!< Connection ID */ + } exec_cmpl; /*!< Callback parameter for the event `ESP_GATTC_EXEC_EVT` */ /** - * @brief ESP_GATTC_NOTIFY_EVT + * @brief Callback parameter for the event `ESP_GATTC_NOTIFY_EVT` */ struct gattc_notify_evt_param { - uint16_t conn_id; /*!< Connection id */ - esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ - uint16_t handle; /*!< The Characteristic or descriptor handle */ - uint16_t value_len; /*!< Notify attribute value */ + uint16_t conn_id; /*!< Connection ID */ + esp_bd_addr_t remote_bda; /*!< Remote Bluetooth device address. */ + uint16_t handle; /*!< The characteristic or descriptor handle */ + uint16_t value_len; /*!< Notify attribute value length in bytes */ uint8_t *value; /*!< Notify attribute value */ - bool is_notify; /*!< True means notify, false means indicate */ - } notify; /*!< Gatt client callback param of ESP_GATTC_NOTIFY_EVT */ + bool is_notify; /*!< True means notification; false means indication */ + } notify; /*!< Callback parameter for the event `ESP_GATTC_NOTIFY_EVT` */ /** - * @brief ESP_GATTC_SRVC_CHG_EVT + * @brief Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT` */ struct gattc_srvc_chg_evt_param { - esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ - } srvc_chg; /*!< Gatt client callback param of ESP_GATTC_SRVC_CHG_EVT */ + esp_bd_addr_t remote_bda; /*!< Remote Bluetooth device address */ + } srvc_chg; /*!< Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT` */ /** - * @brief ESP_GATTC_CONGEST_EVT + * @brief Callback parameter for the event `ESP_GATTC_CONGEST_EVT` */ struct gattc_congest_evt_param { - uint16_t conn_id; /*!< Connection id */ - bool congested; /*!< Congested or not */ - } congest; /*!< Gatt client callback param of ESP_GATTC_CONGEST_EVT */ + uint16_t conn_id; /*!< Connection ID */ + bool congested; /*!< True indicates that the connection is congested, false otherwise */ + } congest; /*!< Callback parameter for the event `ESP_GATTC_CONGEST_EVT` */ /** - * @brief ESP_GATTC_REG_FOR_NOTIFY_EVT + * @brief Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT` */ struct gattc_reg_for_notify_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t handle; /*!< The characteristic or descriptor handle */ - } reg_for_notify; /*!< Gatt client callback param of ESP_GATTC_REG_FOR_NOTIFY_EVT */ + } reg_for_notify; /*!< Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT` */ /** - * @brief ESP_GATTC_UNREG_FOR_NOTIFY_EVT + * @brief Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT` */ struct gattc_unreg_for_notify_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t handle; /*!< The characteristic or descriptor handle */ - } unreg_for_notify; /*!< Gatt client callback param of ESP_GATTC_UNREG_FOR_NOTIFY_EVT */ + } unreg_for_notify; /*!< Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT` */ /** - * @brief ESP_GATTC_CONNECT_EVT + * @brief Callback parameter for the event `ESP_GATTC_CONNECT_EVT` */ struct gattc_connect_evt_param { - uint16_t conn_id; /*!< Connection id */ - uint8_t link_role; /*!< Link role : master role = 0 ; slave role = 1*/ - esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ - esp_gatt_conn_params_t conn_params; /*!< current connection parameters */ - esp_ble_addr_type_t ble_addr_type; /*!< Remote BLE device address type */ - uint16_t conn_handle; /*!< HCI connection handle */ - } connect; /*!< Gatt client callback param of ESP_GATTC_CONNECT_EVT */ + uint16_t conn_id; /*!< Connection ID */ + uint8_t link_role; /*!< Link role : master role = 0; slave role = 1 */ + esp_bd_addr_t remote_bda; /*!< Remote device address */ + esp_gatt_conn_params_t conn_params; /*!< Current connection parameters */ + esp_ble_addr_type_t ble_addr_type; /*!< Remote device address type */ + uint16_t conn_handle; /*!< HCI connection handle */ + } connect; /*!< Callback parameter for the event `ESP_GATTC_CONNECT_EVT` */ /** - * @brief ESP_GATTC_DISCONNECT_EVT + * @brief Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT` */ struct gattc_disconnect_evt_param { - esp_gatt_conn_reason_t reason; /*!< disconnection reason */ - uint16_t conn_id; /*!< Connection id */ - esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ - } disconnect; /*!< Gatt client callback param of ESP_GATTC_DISCONNECT_EVT */ + esp_gatt_conn_reason_t reason; /*!< Disconnection reason */ + uint16_t conn_id; /*!< Connection ID */ + esp_bd_addr_t remote_bda; /*!< Remote device address */ + } disconnect; /*!< Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT` */ + /** - * @brief ESP_GATTC_SET_ASSOC_EVT + * @brief Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT` */ struct gattc_set_assoc_addr_cmp_evt_param { - esp_gatt_status_t status; /*!< Operation status */ - } set_assoc_cmp; /*!< Gatt client callback param of ESP_GATTC_SET_ASSOC_EVT */ + esp_gatt_status_t status; /*!< Operation status */ + } set_assoc_cmp; /*!< Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT` */ + /** - * @brief ESP_GATTC_GET_ADDR_LIST_EVT + * @brief Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT` */ struct gattc_get_addr_list_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint8_t num_addr; /*!< The number of address in the gattc cache address list */ - esp_bd_addr_t *addr_list; /*!< The pointer to the address list which has been get from the gattc cache */ - } get_addr_list; /*!< Gatt client callback param of ESP_GATTC_GET_ADDR_LIST_EVT */ + uint8_t num_addr; /*!< The number of addresses in the local GATTC cache address list */ + esp_bd_addr_t *addr_list; /*!< The pointer to the address list which has been retrieved from the local GATTC cache */ + } get_addr_list; /*!< Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT` */ /** - * @brief ESP_GATTC_QUEUE_FULL_EVT + * @brief Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT` */ struct gattc_queue_full_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - bool is_full; /*!< The gattc command queue is full or not */ - } queue_full; /*!< Gatt client callback param of ESP_GATTC_QUEUE_FULL_EVT */ + uint16_t conn_id; /*!< Connection ID */ + bool is_full; /*!< True indicates the GATTC command queue is full; false otherwise. */ + } queue_full; /*!< Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT` */ /** - * @brief ESP_GATTC_DIS_SRVC_CMPL_EVT + * @brief Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT` */ struct gattc_dis_srvc_cmpl_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - } dis_srvc_cmpl; /*!< Gatt client callback param of ESP_GATTC_DIS_SRVC_CMPL_EVT */ + uint16_t conn_id; /*!< Connection ID */ + } dis_srvc_cmpl; /*!< Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT` */ -} esp_ble_gattc_cb_param_t; /*!< GATT client callback parameter union type */ +} esp_ble_gattc_cb_param_t; /** * @brief GATT Client callback function type - * @param event : Event type - * @param gattc_if : GATT client access interface, normally - * different gattc_if correspond to different profile - * @param param : Point to callback parameter, currently is union type + * + * @param[in] event Event type + * @param[in] gattc_if GATT Client access interface + * @param[in] param The pointer to callback parameter */ typedef void (* esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param); /** - * @brief This function is called to register application callbacks - * with GATTC module. + * @brief Register GATT Client application callbacks * - * @param[in] callback : pointer to the application callback function. + * @param[in] callback The pointer to the application callback function * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback); /** - * @brief This function is called to get the current application callbacks - * with BTA GATTC module. + * @brief Get the current application callbacks * * @return - * - esp_gattC_cb_t : current callback - * + * - esp_gattc_cb_t: Current callback */ esp_gattc_cb_t esp_ble_gattc_get_callback(void); /** - * @brief This function is called to register application callbacks - * with GATTC module. + * @brief Register a GATT Client application * - * @param[in] app_id : Application Identify (UUID), for different application + * @param[in] app_id The UUID for different application + * + * @note + * 1. This function triggers `ESP_GATTC_REG_EVT`. + * 2. The maximum number of applications is limited to 4. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_ARG: The input `app_id` exceeds `ESP_APP_ID_MAX` (0x7fff) defined in esp_bt_defs.h + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_app_register(uint16_t app_id); - /** - * @brief This function is called to unregister an application - * from the GATTC module. + * @brief Unregister a GATT Client application * - * @param[in] gattc_if: Gatt client access interface. + * @param[in] gattc_if GATT Client access interface * - * @note Before calling this API, ensure that all activities - * related to the application, such as connections, scans, ADV, - * are properly closed. + * @note This function triggers `ESP_GATTC_UNREG_EVT`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if); /** - * @brief Open a direct connection or add a background auto connection. - * Note: Do not enable both BLE_42_FEATURE_SUPPORT and BLE_50_FEATURE_SUPPORT configuration options simultaneously. + * @brief Create an ACL connection + * + * @note + * 1. Do not enable `BT_BLE_42_FEATURES_SUPPORTED` and `BT_BLE_50_FEATURES_SUPPORTED` in the menuconfig simultaneously. + * 1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`. + * 2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. + * 3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only. + * * @param[in] gattc_if: GATT client access interface. * @param[in] esp_gatt_create_conn: Pointer to the structure containing connection parameters. * * @return - * - ESP_OK: Operation successful + * - ESP_OK: Success * - others: Operation failed * */ esp_err_t esp_ble_gattc_enh_open(esp_gatt_if_t gattc_if, esp_ble_gatt_creat_conn_params_t *esp_gatt_create_conn); /** - * @brief Open a direct connection or add a background auto connection + * @brief Create an ACL connection when `BT_BLE_42_FEATURES_SUPPORTED` is enabled in the menuconfig * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] remote_bda: remote device bluetooth device address. - * @param[in] remote_addr_type: remote device bluetooth device the address type. - * @param[in] is_direct: direct connection or background auto connection(by now, background auto connection is not supported). + * @param[in] gattc_if GATT Client access interface + * @param[in] remote_bda Remote device address + * @param[in] remote_addr_type Remote device address type + * @param[in] is_direct `True` indicates a direct connection, while `False` indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter. + * + * @note + * 1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`. + * 2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. + * 3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ #if (BLE_42_FEATURE_SUPPORT == TRUE) esp_err_t esp_ble_gattc_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct); #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) +/** + * @brief Create an ACL connection when `BT_BLE_50_FEATURES_SUPPORTED` is enabled in the menuconfig + * + * @param[in] gattc_if GATT Client access interface + * @param[in] remote_bda Remote device address + * @param[in] remote_addr_type Remote device address type + * @param[in] is_direct `True` indicates a direct connection, while `False` indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter. + * + * @note + * 1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`. + * 2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. + * 3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only. + * + * @return + * - ESP_OK: Success + * - ESP_FAIL: Failure + */ #if (BLE_50_FEATURE_SUPPORT == TRUE) esp_err_t esp_ble_gattc_aux_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct); #endif // #if (BLE_50_FEATURE_SUPPORT == TRUE) /** - * @brief Close the virtual connection to the GATT server. gattc may have multiple virtual GATT server connections when multiple app_id registered, - * this API only close one virtual GATT server connection. if there exist other virtual GATT server connections, - * it does not disconnect the physical connection. - * if you want to disconnect the physical connection directly, you can use esp_ble_gap_disconnect(esp_bd_addr_t remote_device). + * @brief Close the virtual GATT Client connection * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID to be closed. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID to be closed + * + * @note + * 1. This function triggers `ESP_GATTC_CLOSE_EVT`. + * 2. There may be multiple virtual GATT server connections when multiple `app_id` got registered. + * 3. This API closes one virtual GATT server connection only, if there exist other virtual GATT server connections. It does not close the physical connection. + * 4. The API `esp_ble_gap_disconnect` can be used to disconnect the physical connection directly. + * 5. If there is only one virtual GATT connection left, this API will terminate the ACL connection in addition and triggers `ESP_GATTC_DISCONNECT_EVT`. Then there is no need to call `esp_ble_gap_disconnect` anymore. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ -esp_err_t esp_ble_gattc_close (esp_gatt_if_t gattc_if, uint16_t conn_id); - +esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id); /** - * @brief Configure the MTU size in the GATT channel. This can be done - * only once per connection. Before using, use esp_ble_gatt_set_local_mtu() - * to configure the local MTU size. + * @brief Configure the MTU size in the GATT channel * * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * + * @note + * 1. This function triggers `ESP_GATTC_CFG_MTU_EVT`. + * 2. You could call `esp_ble_gatt_set_local_mtu` to set the desired MTU size locally before this API. If not set, the GATT channel uses the default MTU size (23 bytes). * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gattc_send_mtu_req (esp_gatt_if_t gattc_if, uint16_t conn_id); - /** - * @brief This function is called to get service from local cache. - * This function report service search result by a callback - * event, and followed by a service search complete event. - * Note: 128-bit base UUID will automatically be converted to a 16-bit UUID in the search results. Other types of UUID remain unchanged. + * @brief Search services from the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID. - * @param[in] filter_uuid: a UUID of the service application is interested in. - * If Null, discover for all services. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] filter_uuid A UUID of the intended service. If NULL is passed, this API will return all services. + * + * @note + * 1. This function triggers `ESP_GATTC_SEARCH_RES_EVT` each time a service is retrieved. + * 2. This function triggers `ESP_GATTC_SEARCH_CMPL_EVT` when the search is completed. + * 3. The 128-bit base UUID will be converted to a 16-bit UUID automatically in the search results. Other types of UUID remain unchanged. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *filter_uuid); /** - * @brief Find all the service with the given service uuid in the gattc cache, if the svc_uuid is NULL, find all the service. - * Note: It just get service from local cache, won't get from remote devices. If want to get it from remote device, need - * to used the esp_ble_gattc_cache_refresh, then call esp_ble_gattc_get_service again. + * @brief Get the service with the given service UUID in the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] svc_uuid: the pointer to the service uuid. - * @param[out] result: The pointer to the service which has been found in the gattc cache. - * @param[inout] count: input the number of service want to find, - * it will output the number of service has been found in the gattc cache with the given service uuid. - * @param[in] offset: Offset of the service position to get. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] svc_uuid The pointer to the service UUID. If NULL is passed, the API will retrieve all services. + * @param[out] result The pointer to the service which has been found in the local GATTC cache + * @param[inout] count The number of services to retrieve. It will be updated with the actual number of services found. + * @param[in] offset The position offset to retrieve + * + * @note + * 1. This API does not trigger any event. + * 2. `esp_ble_gattc_cache_refresh` can be used to discover services again. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_gatt_status_t esp_ble_gattc_get_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *svc_uuid, esp_gattc_service_elem_t *result, uint16_t *count, uint16_t offset); /** - * @brief Find all the characteristic with the given service in the gattc cache - * Note: It just get characteristic from local cache, won't get from remote devices. + * @brief Get all characteristics with the given handle range in the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] start_handle: the attribute start handle. - * @param[in] end_handle: the attribute end handle - * @param[out] result: The pointer to the characteristic in the service. - * @param[inout] count: input the number of characteristic want to find, - * it will output the number of characteristic has been found in the gattc cache with the given service. - * @param[in] offset: Offset of the characteristic position to get. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] start_handle The attribute start handle + * @param[in] end_handle The attribute end handle + * @param[out] result The pointer to the characteristic in the service + * @param[inout] count The number of characteristics to retrieve. It will be updated with the actual number of characteristics found. + * @param[in] offset The position offset to retrieve + * + * @note + * 1. This API does not trigger any event. + * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle` + * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -448,21 +481,24 @@ esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, uint16_t *count, uint16_t offset); /** - * @brief Find all the descriptor with the given characteristic in the gattc cache - * Note: It just get descriptor from local cache, won't get from remote devices. + * @brief Get all descriptors with the given characteristic in the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] char_handle: the given characteristic handle - * @param[out] result: The pointer to the descriptor in the characteristic. - * @param[inout] count: input the number of descriptor want to find, - * it will output the number of descriptor has been found in the gattc cache with the given characteristic. - * @param[in] offset: Offset of the descriptor position to get. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID which identifies the server + * @param[in] char_handle The given characteristic handle + * @param[out] result The pointer to the descriptor in the characteristic + * @param[inout] count The number of descriptors to retrieve. It will be updated with the actual number of descriptors found. + * @param[in] offset The position offset to retrieve + * + * @note + * 1. This API does not trigger any event. + * 2. `char_handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle` + * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -470,24 +506,26 @@ esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if, esp_gattc_descr_elem_t *result, uint16_t *count, uint16_t offset); - /** - * @brief Find the characteristic with the given characteristic uuid in the gattc cache - * Note: It just get characteristic from local cache, won't get from remote devices. + * @brief Get the characteristic with the given characteristic UUID in the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] start_handle: the attribute start handle - * @param[in] end_handle: the attribute end handle - * @param[in] char_uuid: the characteristic uuid - * @param[out] result: The pointer to the characteristic in the service. - * @param[inout] count: input the number of characteristic want to find, - * it will output the number of characteristic has been found in the gattc cache with the given service. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] start_handle The attribute start handle + * @param[in] end_handle The attribute end handle + * @param[in] char_uuid The characteristic UUID + * @param[out] result The pointer to the characteristic in the service + * @param[inout] count The number of characteristics to retrieve. It will be updated with the actual number of characteristics found. + * + * @note + * 1. This API does not trigger any event. + * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle` + * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -498,23 +536,25 @@ esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if, uint16_t *count); /** - * @brief Find the descriptor with the given characteristic uuid in the gattc cache - * Note: It just get descriptor from local cache, won't get from remote devices. + * @brief Get the descriptor with the given characteristic UUID in the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] start_handle: the attribute start handle - * @param[in] end_handle: the attribute end handle - * @param[in] char_uuid: the characteristic uuid. - * @param[in] descr_uuid: the descriptor uuid. - * @param[out] result: The pointer to the descriptor in the given characteristic. - * @param[inout] count: input the number of descriptor want to find, - * it will output the number of descriptor has been found in the gattc cache with the given characteristic. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] start_handle The attribute start handle + * @param[in] end_handle The attribute end handle + * @param[in] char_uuid The characteristic UUID + * @param[in] descr_uuid The descriptor UUID. + * @param[out] result The pointer to the descriptor in the given characteristic. + * @param[inout] count The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found. + * + * @note + * 1. This API does not trigger any event. + * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -526,21 +566,24 @@ esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, uint16_t *count); /** - * @brief Find the descriptor with the given characteristic handle in the gattc cache - * Note: It just get descriptor from local cache, won't get from remote devices. + * @brief Get the descriptor with the given characteristic handle in the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] char_handle: the characteristic handle. - * @param[in] descr_uuid: the descriptor uuid. - * @param[out] result: The pointer to the descriptor in the given characteristic. - * @param[inout] count: input the number of descriptor want to find, - * it will output the number of descriptor has been found in the gattc cache with the given characteristic. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID which identifies the server + * @param[in] char_handle The characteristic handle + * @param[in] descr_uuid The descriptor UUID + * @param[out] result The pointer to the descriptor in the given characteristic + * @param[inout] count The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found. + * + * @note + * 1. This API does not trigger any event. + * 2. `char_handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle` + * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -550,22 +593,24 @@ esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if, uint16_t *count); /** - * @brief Find the include service with the given service handle in the gattc cache - * Note: It just get include service from local cache, won't get from remote devices. + * @brief Get the included services with the given service handle in the local GATTC cache. * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] start_handle: the attribute start handle - * @param[in] end_handle: the attribute end handle - * @param[in] incl_uuid: the include service uuid - * @param[out] result: The pointer to the include service in the given service. - * @param[inout] count: input the number of include service want to find, - * it will output the number of include service has been found in the gattc cache with the given service. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID which identifies the server + * @param[in] start_handle The attribute start handle + * @param[in] end_handle The attribute end handle + * @param[in] incl_uuid The included service UUID + * @param[out] result The pointer to the included service with the given service handle. + * @param[inout] count The number of included services to retrieve. It will be updated with the actual number of included services found. + * + * @note + * 1. This API does not trigger any event. + * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -575,23 +620,27 @@ esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if, esp_gattc_incl_svc_elem_t *result, uint16_t *count); - /** - * @brief Find the attribute count with the given service or characteristic in the gattc cache + * @brief Get the attribute count with the given service or characteristic in the local GATTC cache * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id: connection ID which identify the server. - * @param[in] type: the attribute type. - * @param[in] start_handle: the attribute start handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore - * @param[in] end_handle: the attribute end handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore - * @param[in] char_handle: the characteristic handle, this parameter valid when the type is ESP_GATT_DB_DESCRIPTOR. If the type - * isn't ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore. - * @param[out] count: output the number of attribute has been found in the gattc cache with the given attribute type. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] type The attribute type + * @param[in] start_handle The attribute start handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored. + * @param[in] end_handle The attribute end handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored. + * @param[in] char_handle The characteristic handle. This parameter is valid only if the type is `ESP_GATT_DB_DESCRIPTOR`. + * @param[out] count The number of attributes found in the local GATTC cache with the given attribute type + * + * + * @note + * 1. This API does not trigger any event. + * 2. `start_handle` must be greater than 0, and smaller than `end_handle` if the `type` is not `ESP_GATT_DB_DESCRIPTOR`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle` + * - ESP_GATT_INVALID_PDU: NULL pointer to `count` + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -602,38 +651,47 @@ esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, uint16_t *count); /** - * @brief This function is called to get the GATT database. - * Note: It just get attribute data base from local cache, won't get from remote devices. + * @brief Get the GATT database elements * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] start_handle: the attribute start handle - * @param[in] end_handle: the attribute end handle - * @param[in] conn_id: connection ID which identify the server. - * @param[in] db: output parameter which will contain the GATT database copy. - * Caller is responsible for freeing it. - * @param[in] count: number of elements in database. + * @param[in] gattc_if GATT Client access interface + * @param[in] start_handle The attribute start handle + * @param[in] end_handle The attribute end handle + * @param[in] conn_id Connection ID + * @param[out] db The pointer to GATT database elements + * @param[inout] count The number of elements in the database to retrieve. It will be updated with the actual number of elements found. + * + * @note + * 1. This API does not trigger any event. + * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. * * @return - * - ESP_OK: success - * - other: failed + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle` + * - ESP_GATT_INVALID_PDU: NULL pointer to `db` or NULL pointer to `count` or the count value is 0 + * - ESP_FAIL: Failure due to other reasons * */ esp_gatt_status_t esp_ble_gattc_get_db(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle, esp_gattc_db_elem_t *db, uint16_t *count); /** - * @brief This function is called to read a service's characteristics of - * the given characteristic handle + * @brief Read the characteristics value of the given characteristic handle * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] handle : characteristic handle to read. - * @param[in] auth_req : authenticate request type + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] handle Characteristic handle to read + * @param[in] auth_req Authenticate request type + * + * @note + * 1. This function triggers `ESP_GATTC_READ_CHAR_EVT`. + * 2. This function should be called only after the connection has been established. + * 3. `handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_GATT_INVALID_HANDLE: Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_read_char (esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -641,20 +699,25 @@ esp_err_t esp_ble_gattc_read_char (esp_gatt_if_t gattc_if, esp_gatt_auth_req_t auth_req); /** - * @brief This function is called to read a service's characteristics of - * the given characteristic UUID + * @brief Read the characteristics value of the given characteristic UUID. * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] start_handle : the attribute start handle. - * @param[in] end_handle : the attribute end handle - * @param[in] uuid : The UUID of attribute which will be read. - * @param[in] auth_req : authenticate request type + * @param[in] gattc_if GATT Client access interface. + * @param[in] conn_id Connection ID + * @param[in] start_handle The attribute start handle + * @param[in] end_handle The attribute end handle + * @param[in] uuid The pointer to UUID of attribute to read + * @param[in] auth_req Authenticate request type + * + * @note + * 1. This function triggers `ESP_GATTC_READ_CHAR_EVT`. + * 2. This function should be called only after the connection has been established. + * 3. `start_handle` must be greater than 0, and smaller than `end_handle`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_ILLEGAL_PARAMETER: NULL pointer to `uuid` + * - ESP_ERR_INVALID_STATE: The connection has not been established + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_read_by_type (esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -664,75 +727,92 @@ esp_err_t esp_ble_gattc_read_by_type (esp_gatt_if_t gattc_if, esp_gatt_auth_req_t auth_req); /** - * @brief This function is called to read multiple characteristic or - * characteristic descriptors. + * @brief Read multiple characteristic or descriptor values * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] read_multi : pointer to the read multiple parameter. - * @param[in] auth_req : authenticate request type + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID which specifies the server + * @param[in] read_multi Pointer to `esp_gattc_multi_t` + * @param[in] auth_req Authenticate request type + * + * @note + * 1. This function triggers `ESP_GATTC_READ_MULTIPLE_EVT`. + * 2. This function should be called only after the connection has been established. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_read_multiple(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gattc_multi_t *read_multi, esp_gatt_auth_req_t auth_req); /** - * @brief This function is called to read multiple variable length characteristic or - * characteristic descriptors. + * @brief Read multiple variable length characteristic values. * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] read_multi : pointer to the read multiple parameter. - * @param[in] auth_req : authenticate request type + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] read_multi The pointer to the `esp_gattc_multi_t` + * @param[in] auth_req Authenticate request type + * + * @note + * 1. This function triggers `ESP_GATTC_READ_MULTI_VAR_EVT`. + * 2. This function should be called only after the connection has been established. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_read_multiple_variable(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_gattc_multi_t *read_multi, esp_gatt_auth_req_t auth_req); /** - * @brief This function is called to read a characteristics descriptor. + * @brief Read a characteristics descriptor * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] handle : descriptor handle to read. - * @param[in] auth_req : authenticate request type + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] handle Descriptor handle to read + * @param[in] auth_req Authenticate request type + * + * @note + * 1. This function triggers `ESP_GATTC_READ_DESCR_EVT`. + * 2. This function should be called only after the connection has been established. + * 3. `handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_GATT_INVALID_HANDLE：Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_read_char_descr (esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t handle, esp_gatt_auth_req_t auth_req); - /** - * @brief This function is called to write characteristic value. + * @brief Write the characteristic value of a given characteristic handle * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] handle : characteristic handle to write. - * @param[in] value_len: length of the value to be written. - * @param[in] value : the value to be written. - * @param[in] write_type : the type of attribute write operation. - * @param[in] auth_req : authentication request. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] handle The characteristic handle to write + * @param[in] value_len The length of the value to write in bytes + * @param[in] value The value to write + * @param[in] write_type The type of Attribute write operation + * @param[in] auth_req Authentication request type + * + * @note + * 1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`. + * 2. This function should be called only after the connection has been established. + * 3. `handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_GATT_INVALID_HANDLE：Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_write_char( esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -742,22 +822,27 @@ esp_err_t esp_ble_gattc_write_char( esp_gatt_if_t gattc_if, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req); - /** - * @brief This function is called to write characteristic descriptor value. + * @brief Write Characteristic descriptor value of a given descriptor handle * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID - * @param[in] handle : descriptor handle to write. - * @param[in] value_len: length of the value to be written. - * @param[in] value : the value to be written. - * @param[in] write_type : the type of attribute write operation. - * @param[in] auth_req : authentication request. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] handle The descriptor handle to write. + * @param[in] value_len The length of the value to write in bytes. + * @param[in] value The value to write + * @param[in] write_type The type of Attribute write operation + * @param[in] auth_req Authentication request type + * + * @note + * 1. This function triggers `ESP_GATTC_WRITE_DESCR_EVT`. + * 2. This function should be called only after the connection has been established. + * 3. `handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_GATT_INVALID_HANDLE：Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_write_char_descr (esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -767,22 +852,29 @@ esp_err_t esp_ble_gattc_write_char_descr (esp_gatt_if_t gattc_if, esp_gatt_write_type_t write_type, esp_gatt_auth_req_t auth_req); - /** - * @brief This function is called to prepare write a characteristic value. + * @brief Prepare to write a characteristic value which is longer than the MTU size to a specified characteristic handle * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] handle : characteristic handle to prepare write. - * @param[in] offset : offset of the write value. - * @param[in] value_len: length of the value to be written. - * @param[in] value : the value to be written. - * @param[in] auth_req : authentication request. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] handle Characteristic handle to prepare to write + * @param[in] offset The position offset to write + * @param[in] value_len The length of the value to write in bytes + * @param[in] value The value to write + * @param[in] auth_req Authentication request type + * + * @note + * 1. This function should be called only after the connection has been established. + * 2. After using this API, use `esp_ble_gattc_execute_write` to write. + * 3. This function triggers `ESP_GATTC_PREP_WRITE_EVT`. + * 4. If `value_len` is less than or equal to MTU size, it is recommended to `esp_ble_gattc_write_char` to write directly. + * 5. `handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_GATT_INVALID_HANDLE：Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -792,22 +884,27 @@ esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, uint8_t *value, esp_gatt_auth_req_t auth_req); - /** - * @brief This function is called to prepare write a characteristic descriptor value. + * @brief Prepare to write a characteristic descriptor value at a given handle * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] handle : characteristic descriptor handle to prepare write. - * @param[in] offset : offset of the write value. - * @param[in] value_len: length of the value to be written. - * @param[in] value : the value to be written. - * @param[in] auth_req : authentication request. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] handle Characteristic descriptor handle to prepare to write + * @param[in] offset The position offset to write + * @param[in] value_len The length of the value to write in bytes + * @param[in] value The value to write + * @param[in] auth_req Authentication request type + * + * @note + * 1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`. + * 2. This function should be called only after the connection has been established. + * 3. `handle` must be greater than 0. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_GATT_INVALID_HANDLE：Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, uint16_t conn_id, @@ -817,112 +914,123 @@ esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, uint8_t *value, esp_gatt_auth_req_t auth_req); - /** - * @brief This function is called to execute write a prepare write sequence. + * @brief Execute a prepared writing sequence * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] conn_id : connection ID. - * @param[in] is_execute : execute or cancel. + * @param[in] gattc_if GATT Client access interface + * @param[in] conn_id Connection ID + * @param[in] is_execute True if it is to execute the writing sequence; false if it is to cancel the writing sequence. + * + * @note This function triggers `ESP_GATTC_EXEC_EVT`. * * @return - * - ESP_OK: success - * - other: failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gattc_execute_write (esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute); - /** - * @brief This function is called to register for notification of a service. + * @brief Register to receive notification/indication of a characteristic. * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] server_bda : target GATT server. - * @param[in] handle : GATT characteristic handle. + * @param[in] gattc_if GATT Client access interface + * @param[in] server_bda Target GATT server device address + * @param[in] handle Target GATT characteristic handle + * + * @note + * 1. This function triggers `ESP_GATTC_REG_FOR_NOTIFY_EVT`. + * 2. You should call `esp_ble_gattc_write_char_descr()` after this API to write Client Characteristic Configuration (CCC) descriptor to the value of 1 (Enable Notification) or 2 (Enable Indication). + * 3. `handle` must be greater than 0. * * @return - * - ESP_OK: registration succeeds - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE：Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_register_for_notify (esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle); - /** - * @brief This function is called to de-register for notification of a service. + * @brief Unregister the notification of a service. * - * @param[in] gattc_if: Gatt client access interface. - * @param[in] server_bda : target GATT server. - * @param[in] handle : GATT characteristic handle. + * @param[in] gattc_if GATT Client access interface + * @param[in] server_bda Target GATT server device address + * @param[in] handle Target GATT characteristic handle * + * @note + * 1. This function triggers `ESP_GATTC_UNREG_FOR_NOTIFY_EVT`. + * 2. You should call `esp_ble_gattc_write_char_descr()` after this API to write Client Characteristic Configuration (CCC) descriptor value to 0. + * 3. `handle` must be greater than 0 * @return - * - ESP_OK: unregister succeeds - * - other: failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE：Invalid `handle` + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gattc_unregister_for_notify (esp_gatt_if_t gattc_if, esp_bd_addr_t server_bda, uint16_t handle); - /** -* @brief Refresh the server cache store in the gattc stack of the remote device. If -* the device is connected, this API will restart the discovery of service information of the remote device -* -* @param[in] remote_bda: remote device BD address. -* -* @return -* - ESP_OK: success -* - other: failed -* -*/ + * @brief Refresh the cache of the remote device + * + * @param[in] remote_bda Remote device address + * + * @note + * 1. If the device is connected, this API will restart the discovery of service information of the remote device. + * 2. This function triggers `ESP_GATTC_DIS_SRVC_CMPL_EVT` only after the ACL connection is established. Otherwise, no events will be triggered. + * + * @return + * - ESP_OK: Success + * - ESP_FAIL: Failure + */ esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda); /** -* @brief Add or delete the associated address with the source address. -* Note: The role of this API is mainly when the client side has stored a server-side database, -* when it needs to connect another device, but the device's attribute database is the same -* as the server database stored on the client-side, calling this API can use the database -* that the device has stored used as the peer server database to reduce the attribute -* database search and discovery process and speed up the connection time. -* The associated address mains that device want to used the database has stored in the local cache. -* The source address mains that device want to share the database to the associated address device. -* -* @param[in] gattc_if: Gatt client access interface. -* @param[in] src_addr: the source address which provide the attribute table. -* @param[in] assoc_addr: the associated device address which went to share the attribute table with the source address. -* @param[in] is_assoc: true add the associated device address, false remove the associated device address. -* @return -* - ESP_OK: success -* - other: failed -* -*/ + * @brief Add or remove the association between the address in the local GATTC cache with the source address of the remote device + * + * @param[in] gattc_if GATT Client access interface + * @param[in] src_addr The source address intended to be associated to the `assoc_addr` which has been stored in the local GATTC cache + * @param[in] assoc_addr The associated device address intended to share the attribute table with the source address + * @param[in] is_assoc True if adding the association; false if removing the association. + * + * @note + * 1. This API is primarily used when the client has a stored server-side database (`assoc_addr`) and needs to connect to + * another device (`src_addr`) with the same attribute database. By invoking this API, the stored database is utilized + * as the peer server database, eliminating the need for attribute database search and discovery. This reduces + * processing time and accelerates the connection process. + * 2. The attribute table of a device with `assoc_addr` must be stored in the local GATTC cache first. + * Then, the attribute table of the device with `src_addr` must be the same as the one with `assoc_addr`. + * 3. This function triggers `ESP_GATTC_SET_ASSOC_EVT`. + * + * @return + * - ESP_OK: Success + * - ESP_FAIL: Failure + */ esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr, esp_bd_addr_t assoc_addr, bool is_assoc); + /** -* @brief Get the address list which has store the attribute table in the gattc cache. There will -* callback ESP_GATTC_GET_ADDR_LIST_EVT event when get address list complete. -* -* @param[in] gattc_if: Gatt client access interface. -* @return -* - ESP_OK: success -* - other: failed -* -*/ + * @brief Get the address list stored in the local GATTC cache + * + * @param[in] gattc_if GATT Client access interface + * + * @note This function triggers `ESP_GATTC_GET_ADDR_LIST_EVT`. + * + * @return + * - ESP_OK: Success + * - ESP_FAIL: Failure + */ esp_err_t esp_ble_gattc_cache_get_addr_list(esp_gatt_if_t gattc_if); /** -* @brief Clean the service cache of this device in the gattc stack, -* -* @param[in] remote_bda: remote device BD address. -* -* @return -* - ESP_OK: success -* - other: failed -* -*/ + * @brief Clean the service cache of the target device in the local GATTC cache + * + * @param[in] remote_bda Remote device address + * + * @return + * - ESP_OK: Success + * - ESP_FAIL: Failure + */ esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda); #ifdef __cplusplus diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h index 72ff694e4b..420cc80359 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -17,580 +17,604 @@ extern "C" { /// GATT Server callback function events typedef enum { - ESP_GATTS_REG_EVT = 0, /*!< When register application id, the event comes */ - ESP_GATTS_READ_EVT = 1, /*!< When gatt client request read operation, the event comes */ - ESP_GATTS_WRITE_EVT = 2, /*!< When gatt client request write operation, the event comes */ - ESP_GATTS_EXEC_WRITE_EVT = 3, /*!< When gatt client request execute write, the event comes */ - ESP_GATTS_MTU_EVT = 4, /*!< When set mtu complete, the event comes */ - ESP_GATTS_CONF_EVT = 5, /*!< When receive confirm, the event comes */ - ESP_GATTS_UNREG_EVT = 6, /*!< When unregister application id, the event comes */ - ESP_GATTS_CREATE_EVT = 7, /*!< When create service complete, the event comes */ - ESP_GATTS_ADD_INCL_SRVC_EVT = 8, /*!< When add included service complete, the event comes */ - ESP_GATTS_ADD_CHAR_EVT = 9, /*!< When add characteristic complete, the event comes */ - ESP_GATTS_ADD_CHAR_DESCR_EVT = 10, /*!< When add descriptor complete, the event comes */ - ESP_GATTS_DELETE_EVT = 11, /*!< When delete service complete, the event comes */ - ESP_GATTS_START_EVT = 12, /*!< When start service complete, the event comes */ - ESP_GATTS_STOP_EVT = 13, /*!< When stop service complete, the event comes */ - ESP_GATTS_CONNECT_EVT = 14, /*!< When gatt client connect, the event comes */ - ESP_GATTS_DISCONNECT_EVT = 15, /*!< When gatt client disconnect, the event comes */ - ESP_GATTS_OPEN_EVT = 16, /*!< When connect to peer, the event comes */ - ESP_GATTS_CANCEL_OPEN_EVT = 17, /*!< When disconnect from peer, the event comes */ - ESP_GATTS_CLOSE_EVT = 18, /*!< When gatt server close, the event comes */ - ESP_GATTS_LISTEN_EVT = 19, /*!< When gatt listen to be connected the event comes */ - ESP_GATTS_CONGEST_EVT = 20, /*!< When congest happen, the event comes */ + ESP_GATTS_REG_EVT = 0, /*!< This event is triggered when a GATT Server application is registered using `esp_ble_gatts_app_register`. */ + ESP_GATTS_READ_EVT = 1, /*!< This event is triggered when the read request from the Client is received. */ + ESP_GATTS_WRITE_EVT = 2, /*!< This event is triggered when the write request from the Client is received. */ + ESP_GATTS_EXEC_WRITE_EVT = 3, /*!< This event is triggered when the write execution request from the Client is received. */ + ESP_GATTS_MTU_EVT = 4, /*!< This event is triggered when the MTU configuration request from the Client is received. */ + ESP_GATTS_CONF_EVT = 5, /*!< This event is triggered when the confirmation from the Client is received. */ + ESP_GATTS_UNREG_EVT = 6, /*!< This event is triggered when a GATT Server application is unregistered using `esp_ble_gatts_app_unregister`. */ + ESP_GATTS_CREATE_EVT = 7, /*!< This event is triggered when a GATT Server service is created using `esp_ble_gatts_create_service`. */ + ESP_GATTS_ADD_INCL_SRVC_EVT = 8, /*!< This event is triggered when an included service is added using `esp_ble_gatts_add_included_service`. */ + ESP_GATTS_ADD_CHAR_EVT = 9, /*!< This event is triggered when a characteristic is added to the service using `esp_ble_gatts_add_char`. */ + ESP_GATTS_ADD_CHAR_DESCR_EVT = 10, /*!< This event is triggered when a characteristic descriptor is added to the service using `esp_ble_gatts_add_char_descr`. */ + ESP_GATTS_DELETE_EVT = 11, /*!< This event is triggered when the service is deleted using `esp_ble_gatts_delete_service`. */ + ESP_GATTS_START_EVT = 12, /*!< This event is triggered when the service is started using `esp_ble_gatts_start_service`. */ + ESP_GATTS_STOP_EVT = 13, /*!< This event is triggered when the service is stopped using `esp_ble_gatts_stop_service`. */ + ESP_GATTS_CONNECT_EVT = 14, /*!< This event is triggered when a physical connection is set up. */ + ESP_GATTS_DISCONNECT_EVT = 15, /*!< This event is triggered when a physical connection is terminated. */ + ESP_GATTS_OPEN_EVT = 16, /*!< This event is triggered when a virtual connection is created using `esp_ble_gatts_open`. */ + ESP_GATTS_CANCEL_OPEN_EVT = 17, /*!< Deprecated. */ + ESP_GATTS_CLOSE_EVT = 18, /*!< This event is triggered when a virtual connection is closed using `esp_ble_gatts_close`. */ + ESP_GATTS_LISTEN_EVT = 19, /*!< Deprecated. */ + ESP_GATTS_CONGEST_EVT = 20, /*!< This event is triggered when the GATT connection is congested. */ /* following is extra event */ - ESP_GATTS_RESPONSE_EVT = 21, /*!< When gatt send response complete, the event comes */ - ESP_GATTS_CREAT_ATTR_TAB_EVT = 22, /*!< When gatt create table complete, the event comes */ - ESP_GATTS_SET_ATTR_VAL_EVT = 23, /*!< When gatt set attr value complete, the event comes */ - ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24, /*!< When gatt send service change indication complete, the event comes */ + ESP_GATTS_RESPONSE_EVT = 21, /*!< This event is triggered when a response is sent to the request using `esp_ble_gatts_send_response`. */ + ESP_GATTS_CREAT_ATTR_TAB_EVT = 22, /*!< This event is triggered when a service attribute table is created using `esp_ble_gatts_create_attr_tab`. */ + ESP_GATTS_SET_ATTR_VAL_EVT = 23, /*!< This event is triggered when an attribute value is set using `esp_ble_gatts_set_attr_value`. */ + ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24, /*!< This event is triggered when a service change indication is sent using `esp_ble_gatts_send_service_change_indication`. */ } esp_gatts_cb_event_t; /** - * @brief Gatt server callback parameters union + * @brief GATT Server callback parameters */ typedef union { /** - * @brief ESP_GATTS_REG_EVT + * @brief Callback parameter for the event `ESP_GATTS_REG_EVT` */ struct gatts_reg_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t app_id; /*!< Application id which input in register API */ - } reg; /*!< Gatt server callback param of ESP_GATTS_REG_EVT */ + uint16_t app_id; /*!< Application ID */ + } reg; /*!< Callback parameter for the event `ESP_GATTS_REG_EVT` */ /** - * @brief ESP_GATTS_READ_EVT + * @brief Callback parameter for the event `ESP_GATTS_READ_EVT` */ struct gatts_read_evt_param { - uint16_t conn_id; /*!< Connection id */ - uint32_t trans_id; /*!< Transfer id */ - esp_bd_addr_t bda; /*!< The bluetooth device address which been read */ + uint16_t conn_id; /*!< Connection ID */ + uint32_t trans_id; /*!< Transfer ID */ + esp_bd_addr_t bda; /*!< The device address to read */ uint16_t handle; /*!< The attribute handle */ - uint16_t offset; /*!< Offset of the value, if the value is too long */ - bool is_long; /*!< The value is too long or not */ - bool need_rsp; /*!< The read operation need to do response */ - } read; /*!< Gatt server callback param of ESP_GATTS_READ_EVT */ + uint16_t offset; /*!< The position offset to read. If the length of value is less than or equal to the MTU size, this value is 0. */ + bool is_long; /*!< True indicates that the length of value is greater than the MTU size; false otherwise. */ + bool need_rsp; /*!< True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise. */ + } read; /*!< Callback parameter for the event `ESP_GATTS_READ_EVT` */ /** - * @brief ESP_GATTS_WRITE_EVT + * @brief Callback parameter for the event `ESP_GATTS_WRITE_EVT` */ struct gatts_write_evt_param { - uint16_t conn_id; /*!< Connection id */ - uint32_t trans_id; /*!< Transfer id */ - esp_bd_addr_t bda; /*!< The bluetooth device address which been written */ + uint16_t conn_id; /*!< Connection ID */ + uint32_t trans_id; /*!< Transfer ID */ + esp_bd_addr_t bda; /*!< The device address to write */ uint16_t handle; /*!< The attribute handle */ - uint16_t offset; /*!< Offset of the value, if the value is too long */ - bool need_rsp; /*!< The write operation need to do response */ - bool is_prep; /*!< This write operation is prepare write */ - uint16_t len; /*!< The write attribute value length */ + uint16_t offset; /*!< The position offset to write. If the length of value is less than or equal to the MTU size, this value is 0.*/ + bool need_rsp; /*!< True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise. */ + bool is_prep; /*!< True indicates the write operation is a prepared write operation */ + uint16_t len; /*!< The length of the write attribute value in bytes */ uint8_t *value; /*!< The write attribute value */ - } write; /*!< Gatt server callback param of ESP_GATTS_WRITE_EVT */ + } write; /*!< Callback parameter for the event `ESP_GATTS_WRITE_EVT` */ /** - * @brief ESP_GATTS_EXEC_WRITE_EVT + * @brief Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT` */ struct gatts_exec_write_evt_param { - uint16_t conn_id; /*!< Connection id */ - uint32_t trans_id; /*!< Transfer id */ - esp_bd_addr_t bda; /*!< The bluetooth device address which been written */ -#define ESP_GATT_PREP_WRITE_CANCEL 0x00 /*!< Prepare write flag to indicate cancel prepare write */ -#define ESP_GATT_PREP_WRITE_EXEC 0x01 /*!< Prepare write flag to indicate execute prepare write */ - uint8_t exec_write_flag; /*!< Execute write flag */ - } exec_write; /*!< Gatt server callback param of ESP_GATTS_EXEC_WRITE_EVT */ + uint16_t conn_id; /*!< Connection ID */ + uint32_t trans_id; /*!< Transfer ID */ + esp_bd_addr_t bda; /*!< The bluetooth device address to write */ + #define ESP_GATT_PREP_WRITE_CANCEL 0x00 /*!< Flag to indicate the cancellation of a prepare write operation */ + #define ESP_GATT_PREP_WRITE_EXEC 0x01 /*!< Flag to indicate the execution of a prepare write operation */ + uint8_t exec_write_flag; /*!< Execute write flag: `ESP_GATT_PREP_WRITE_CANCEL` or `ESP_GATT_PREP_WRITE_EXEC` */ + } exec_write; /*!< Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT` */ /** - * @brief ESP_GATTS_MTU_EVT + * @brief Callback parameter for the event `ESP_GATTS_MTU_EVT` */ struct gatts_mtu_evt_param { - uint16_t conn_id; /*!< Connection id */ + uint16_t conn_id; /*!< Connection ID */ uint16_t mtu; /*!< MTU size */ - } mtu; /*!< Gatt server callback param of ESP_GATTS_MTU_EVT */ + } mtu; /*!< Callback parameter for the event `ESP_GATTS_MTU_EVT` */ /** - * @brief ESP_GATTS_CONF_EVT + * @brief Callback parameter for the event `ESP_GATTS_CONF_EVT` */ struct gatts_conf_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - uint16_t handle; /*!< attribute handle */ - uint16_t len; /*!< The indication or notification value length, len is valid when send notification or indication failed */ - uint8_t *value; /*!< The indication or notification value , value is valid when send notification or indication failed */ - } conf; /*!< Gatt server callback param of ESP_GATTS_CONF_EVT (confirm) */ + uint16_t conn_id; /*!< Connection ID */ + uint16_t handle; /*!< Attribute handle */ + uint16_t len; /*!< The length of indication or notification value in bytes. The length is invalid if the notification or indication failed. */ + uint8_t *value; /*!< The indication or notification value. The value is invalid if the notification or indication failed. */ + } conf; /*!< Callback parameter for the event `ESP_GATTS_CONF_EVT` */ /** - * @brief ESP_GATTS_UNREG_EVT - */ - - /** - * @brief ESP_GATTS_CREATE_EVT + * @brief Callback parameter for the event `ESP_GATTS_CREATE_EVT` */ struct gatts_create_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t service_handle; /*!< Service attribute handle */ - esp_gatt_srvc_id_t service_id; /*!< Service id, include service uuid and other information */ - } create; /*!< Gatt server callback param of ESP_GATTS_CREATE_EVT */ + esp_gatt_srvc_id_t service_id; /*!< Service ID, including service UUID and other information */ + } create; /*!< Callback parameter for the event `ESP_GATTS_CREATE_EVT` */ /** - * @brief ESP_GATTS_ADD_INCL_SRVC_EVT + * @brief Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT` */ struct gatts_add_incl_srvc_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t attr_handle; /*!< Included service attribute handle */ uint16_t service_handle; /*!< Service attribute handle */ - } add_incl_srvc; /*!< Gatt server callback param of ESP_GATTS_ADD_INCL_SRVC_EVT */ + } add_incl_srvc; /*!< Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT` */ /** - * @brief ESP_GATTS_ADD_CHAR_EVT + * @brief Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT` */ struct gatts_add_char_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t attr_handle; /*!< Characteristic attribute handle */ uint16_t service_handle; /*!< Service attribute handle */ - esp_bt_uuid_t char_uuid; /*!< Characteristic uuid */ - } add_char; /*!< Gatt server callback param of ESP_GATTS_ADD_CHAR_EVT */ + esp_bt_uuid_t char_uuid; /*!< Characteristic UUID */ + } add_char; /*!< Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT` */ /** - * @brief ESP_GATTS_ADD_CHAR_DESCR_EVT + * @brief Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT` */ struct gatts_add_char_descr_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t attr_handle; /*!< Descriptor attribute handle */ uint16_t service_handle; /*!< Service attribute handle */ - esp_bt_uuid_t descr_uuid; /*!< Characteristic descriptor uuid */ - } add_char_descr; /*!< Gatt server callback param of ESP_GATTS_ADD_CHAR_DESCR_EVT */ + esp_bt_uuid_t descr_uuid; /*!< Characteristic descriptor UUID */ + } add_char_descr; /*!< Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT` */ /** - * @brief ESP_GATTS_DELETE_EVT + * @brief Callback parameter for the event `ESP_GATTS_DELETE_EVT` */ struct gatts_delete_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t service_handle; /*!< Service attribute handle */ - } del; /*!< Gatt server callback param of ESP_GATTS_DELETE_EVT */ + } del; /*!< Callback parameter for the event `ESP_GATTS_DELETE_EVT` */ /** - * @brief ESP_GATTS_START_EVT + * @brief Callback parameter for the event `ESP_GATTS_START_EVT` */ struct gatts_start_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t service_handle; /*!< Service attribute handle */ - } start; /*!< Gatt server callback param of ESP_GATTS_START_EVT */ + } start; /*!< Callback parameter for the event `ESP_GATTS_START_EVT` */ /** - * @brief ESP_GATTS_STOP_EVT + * @brief Callback parameter for the event `ESP_GATTS_STOP_EVT` */ struct gatts_stop_evt_param { esp_gatt_status_t status; /*!< Operation status */ uint16_t service_handle; /*!< Service attribute handle */ - } stop; /*!< Gatt server callback param of ESP_GATTS_STOP_EVT */ + } stop; /*!< Callback parameter for the event `ESP_GATTS_STOP_EVT` */ /** - * @brief ESP_GATTS_CONNECT_EVT + * @brief Callback parameter for the event `ESP_GATTS_CONNECT_EVT` */ struct gatts_connect_evt_param { - uint16_t conn_id; /*!< Connection id */ - uint8_t link_role; /*!< Link role : master role = 0 ; slave role = 1*/ - esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ - esp_gatt_conn_params_t conn_params; /*!< current Connection parameters */ - esp_ble_addr_type_t ble_addr_type; /*!< Remote BLE device address type */ - uint16_t conn_handle; /*!< HCI connection handle */ - } connect; /*!< Gatt server callback param of ESP_GATTS_CONNECT_EVT */ + uint16_t conn_id; /*!< Connection ID */ + uint8_t link_role; /*!< Link role: master role = 0; slave role = 1 */ + esp_bd_addr_t remote_bda; /*!< Remote device address */ + esp_gatt_conn_params_t conn_params; /*!< Current connection parameters */ + esp_ble_addr_type_t ble_addr_type; /*!< Remote device address type */ + uint16_t conn_handle; /*!< HCI connection handle */ + } connect; /*!< Callback parameter for the event `ESP_GATTS_CONNECT_EVT` */ /** - * @brief ESP_GATTS_DISCONNECT_EVT + * @brief Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT` */ struct gatts_disconnect_evt_param { - uint16_t conn_id; /*!< Connection id */ - esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ - esp_gatt_conn_reason_t reason; /*!< Indicate the reason of disconnection */ - } disconnect; /*!< Gatt server callback param of ESP_GATTS_DISCONNECT_EVT */ + uint16_t conn_id; /*!< Connection ID */ + esp_bd_addr_t remote_bda; /*!< Remote device address */ + esp_gatt_conn_reason_t reason; /*!< The reason of disconnection */ + } disconnect; /*!< Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT` */ /** - * @brief ESP_GATTS_OPEN_EVT + * @brief Callback parameter for the event `ESP_GATTS_OPEN_EVT` */ struct gatts_open_evt_param { esp_gatt_status_t status; /*!< Operation status */ - } open; /*!< Gatt server callback param of ESP_GATTS_OPEN_EVT */ + } open; /*!< Callback parameter for the event `ESP_GATTS_OPEN_EVT` */ /** - * @brief ESP_GATTS_CANCEL_OPEN_EVT + * @brief Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT` */ struct gatts_cancel_open_evt_param { esp_gatt_status_t status; /*!< Operation status */ - } cancel_open; /*!< Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT */ + } cancel_open; /*!< Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT` */ /** - * @brief ESP_GATTS_CLOSE_EVT + * @brief Callback parameter for the event `ESP_GATTS_CLOSE_EVT` */ struct gatts_close_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - } close; /*!< Gatt server callback param of ESP_GATTS_CLOSE_EVT */ + uint16_t conn_id; /*!< Connection ID */ + } close; /*!< Callback parameter for the event `ESP_GATTS_CLOSE_EVT` */ /** - * @brief ESP_GATTS_LISTEN_EVT - */ - /** - * @brief ESP_GATTS_CONGEST_EVT + * @brief Callback parameter for the event `ESP_GATTS_CONGEST_EVT` */ struct gatts_congest_evt_param { - uint16_t conn_id; /*!< Connection id */ - bool congested; /*!< Congested or not */ - } congest; /*!< Gatt server callback param of ESP_GATTS_CONGEST_EVT */ + uint16_t conn_id; /*!< Connection ID */ + bool congested; /*!< True indicates the connection is congested; false otherwise. */ + } congest; /*!< Callback parameter for the event `ESP_GATTS_CONGEST_EVT` */ /** - * @brief ESP_GATTS_RESPONSE_EVT + * @brief Callback parameter for the event `ESP_GATTS_RESPONSE_EVT` */ struct gatts_rsp_evt_param { esp_gatt_status_t status; /*!< Operation status */ - uint16_t conn_id; /*!< Connection id */ - uint16_t handle; /*!< Attribute handle which send response */ - } rsp; /*!< Gatt server callback param of ESP_GATTS_RESPONSE_EVT */ + uint16_t conn_id; /*!< Connection ID */ + uint16_t handle; /*!< Attribute handle which sends the response */ + } rsp; /*!< Callback parameter for the event `ESP_GATTS_RESPONSE_EVT` */ /** - * @brief ESP_GATTS_CREAT_ATTR_TAB_EVT + * @brief Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT` */ struct gatts_add_attr_tab_evt_param{ esp_gatt_status_t status; /*!< Operation status */ - esp_bt_uuid_t svc_uuid; /*!< Service uuid type */ - uint8_t svc_inst_id; /*!< Service id */ - uint16_t num_handle; /*!< The number of the attribute handle to be added to the gatts database */ - uint16_t *handles; /*!< The number to the handles */ - } add_attr_tab; /*!< Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT */ + esp_bt_uuid_t svc_uuid; /*!< Service UUID type */ + uint8_t svc_inst_id; /*!< Service ID */ + uint16_t num_handle; /*!< The number of the attribute handles which have been added to the GATT Service table */ + uint16_t *handles; /*!< The handles which have been added to the table */ + } add_attr_tab; /*!< Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT` */ /** - * @brief ESP_GATTS_SET_ATTR_VAL_EVT + * @brief Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT` */ struct gatts_set_attr_val_evt_param{ uint16_t srvc_handle; /*!< The service handle */ - uint16_t attr_handle; /*!< The attribute handle */ - esp_gatt_status_t status; /*!< Operation status*/ - } set_attr_val; /*!< Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT */ + uint16_t attr_handle; /*!< The attribute handle */ + esp_gatt_status_t status; /*!< Operation status */ + } set_attr_val; /*!< Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT` */ /** - * @brief ESP_GATTS_SEND_SERVICE_CHANGE_EVT + * @brief Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT` */ struct gatts_send_service_change_evt_param{ - esp_gatt_status_t status; /*!< Operation status*/ - } service_change; /*!< Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT */ + esp_gatt_status_t status; /*!< Operation status */ + } service_change; /*!< Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT` */ } esp_ble_gatts_cb_param_t; /** * @brief GATT Server callback function type - * @param event : Event type - * @param gatts_if : GATT server access interface, normally - * different gatts_if correspond to different profile - * @param param : Point to callback parameter, currently is union type + * + * @param[in] event Event type + * @param[in] gatts_if GATT Server access interface. Typically, different `gatts_if` values correspond to different profiles. + * @param[in] param The pointer to the callback parameter, which is of a union type. */ typedef void (* esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param); /** - * @brief This function is called to register application callbacks - * with BTA GATTS module. + * @brief Register GATT Server application callbacks + * + * @param[in] callback The pointer to the application callback function * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_register_callback(esp_gatts_cb_t callback); /** - * @brief This function is called to get the current application callbacks - * with BTA GATTS module. + * @brief Get the current GATT Server application callback * * @return - * - esp_gatts_cb_t : current callback - * + * - esp_gatts_cb_t: Current callback */ esp_gatts_cb_t esp_ble_gatts_get_callback(void); /** - * @brief This function is called to register application identifier + * @brief Register GATT Server application + * + * @param[in] app_id: The UUID for different application + * + * @note + * 1. This function triggers `ESP_GATTS_REG_EVT`. + * 2. The maximum number of applications is limited to 6. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_ARG: The input `app_id` exceeds `ESP_APP_ID_MAX` (0x7fff) defined in esp_bt_defs.h. + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gatts_app_register(uint16_t app_id); - - /** - * @brief unregister with GATT Server. + * @brief Unregister an GATT Server application + * + * @param[in] gatts_if GATT Server access interface. + * + * @note + * 1. This function triggers `ESP_GATTS_UNREG_EVT`. + * 2. The maximum number of applications is limited to 6. * - * @param[in] gatts_if: GATT server access interface * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if); - /** - * @brief Create a service. When service creation is done, a callback - * event ESP_GATTS_CREATE_EVT is called to report status - * and service ID to the profile. The service ID obtained in - * the callback function needs to be used when adding included - * service and characteristics/descriptors into the service. + * @brief Create a GATT Server service * - * @param[in] gatts_if: GATT server access interface - * @param[in] service_id: service ID. - * @param[in] num_handle: number of handle requested for this service. + * @param[in] gatts_if GATT Server access interface + * @param[in] service_id The pointer to the Service ID + * @param[in] num_handle The number of handles requested for this service. + * + * @note + * 1. This function triggers `ESP_GATTS_CREATE_EVT`. + * 2. `num_handle` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if, esp_gatt_srvc_id_t *service_id, uint16_t num_handle); /** - * @brief Create a service attribute tab. - * @param[in] gatts_attr_db: the pointer to the service attr tab - * @param[in] gatts_if: GATT server access interface - * @param[in] max_nb_attr: the number of attribute to be added to the service database. - * @param[in] srvc_inst_id: the instance id of the service + * @brief Create a service attribute table + * + * @param[in] gatts_attr_db The pointer to the service attribute table + * @param[in] gatts_if GATT Server access interface + * @param[in] max_nb_attr The number of attributes to be added to the service database + * @param[in] srvc_inst_id The instance ID of the service + * + * @note + * 1. This function triggers `ESP_GATTS_CREAT_ATTR_TAB_EVT`. + * 2. `max_nb_attr` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_ARG: Invalid `max_nb_attr` + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db, esp_gatt_if_t gatts_if, uint16_t max_nb_attr, uint8_t srvc_inst_id); /** - * @brief This function is called to add an included service. This function have to be called between - * 'esp_ble_gatts_create_service' and 'esp_ble_gatts_add_char'. After included - * service is included, a callback event ESP_GATTS_ADD_INCL_SRVC_EVT - * is reported the included service ID. + * @brief Add an included service * - * @param[in] service_handle: service handle to which this included service is to - * be added. - * @param[in] included_service_handle: the service ID to be included. + * @param[in] service_handle Target service handle to add + * @param[in] included_service_handle The handle of included service to be added + * + * @note + * 1. This function triggers `ESP_GATTS_ADD_INCL_SRVC_EVT`. + * 2. This function has to be called between `esp_ble_gatts_create_service` and `esp_ble_gatts_add_char`. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle); - - /** - * @brief This function is called to add a characteristic into a service. + * @brief Add a characteristic into a service. * - * @param[in] service_handle: service handle to which this included service is to - * be added. - * @param[in] char_uuid : Characteristic UUID. - * @param[in] perm : Characteristic value declaration attribute permission. - * @param[in] property : Characteristic Properties - * @param[in] char_val : Characteristic value - * @param[in] control : attribute response control byte + * @param[in] service_handle Target service handle to add the characteristic + * @param[in] char_uuid The pointer to the characteristic UUID + * @param[in] perm Characteristic value declaration attribute permission + * @param[in] property Characteristic Properties + * @param[in] char_val The pointer to the characteristic value + * @param[in] control The pointer to the attribute response control byte + * + * @note + * 1. This function triggers `ESP_GATTS_ADD_CHAR_EVT`. + * 2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`. + * 3. For stack respond attribute (`ESP_GATT_AUTO_RSP`), `char_val` should not be NULL and `char_val->attr_max_len` must be greater than 0. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_ARG: Invalid arguments + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gatts_add_char(uint16_t service_handle, esp_bt_uuid_t *char_uuid, esp_gatt_perm_t perm, esp_gatt_char_prop_t property, esp_attr_value_t *char_val, esp_attr_control_t *control); - /** - * @brief This function is called to add characteristic descriptor. When - * it's done, a callback event ESP_GATTS_ADD_DESCR_EVT is called - * to report the status and an ID number for this descriptor. + * @brief Add a characteristic descriptor + * + * @param[in] service_handle Target service handle to add the characteristic descriptor + * @param[in] descr_uuid The pointer to the descriptor UUID + * @param[in] perm Descriptor access permission + * @param[in] char_descr_val The pointer to the characteristic descriptor value + * @param[in] control The pointer to the attribute response control byte + * + * @note + * 1. This function triggers `ESP_GATTS_ADD_CHAR_DESCR_EVT`. + * 2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`. + * 3. For stack respond attribute (`ESP_GATT_AUTO_RSP`), `char_val` should not be NULL and `char_val->attr_max_len` must be greater than 0. * - * @param[in] service_handle: service handle to which this characteristic descriptor is to - * be added. - * @param[in] perm: descriptor access permission. - * @param[in] descr_uuid: descriptor UUID. - * @param[in] char_descr_val : Characteristic descriptor value - * @param[in] control : attribute response control byte * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_ARG: Invalid arguments + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gatts_add_char_descr (uint16_t service_handle, esp_bt_uuid_t *descr_uuid, esp_gatt_perm_t perm, esp_attr_value_t *char_descr_val, esp_attr_control_t *control); - - /** - * @brief This function is called to delete a service. When this is done, - * a callback event ESP_GATTS_DELETE_EVT is report with the status. + * @brief Delete a service * - * @param[in] service_handle: service_handle to be deleted. + * @param[in] service_handle Target service handle to delete + * + * @note This function triggers `ESP_GATTS_DELETE_EVT`. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle); - - /** - * @brief This function is called to start a service. + * @brief Start a service * - * @param[in] service_handle: the service handle to be started. + * @param[in] service_handle Target service handle to start + * + * @note This function triggers `ESP_GATTS_START_EVT`. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_start_service(uint16_t service_handle); - - /** - * @brief This function is called to stop a service. + * @brief Stop a service. * - * @param[in] service_handle - service to be topped. + * @param[in] service_handle Target service handle to stop + * + * @note This function triggers `ESP_GATTS_STOP_EVT`. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle); - - /** - * @brief Send indicate or notify to GATT client. - * Set param need_confirm as false will send notification, otherwise indication. - * Note: the size of indicate or notify data need less than MTU size,see "esp_ble_gattc_send_mtu_req". + * @brief Send indication or notification to a GATT Client * - * @param[in] gatts_if: GATT server access interface - * @param[in] conn_id - connection id to indicate. - * @param[in] attr_handle - attribute handle to indicate. - * @param[in] value_len - indicate value length. - * @param[in] value: value to indicate. - * @param[in] need_confirm - Whether a confirmation is required. - * false sends a GATT notification, true sends a GATT indication. + * @param[in] gatts_if GATT Server access interface + * @param[in] conn_id Connection ID + * @param[in] attr_handle Attribute handle to indicate + * @param[in] value_len Indication value length in bytes + * @param[in] value Value to indicate + * @param[in] need_confirm True if a confirmation is required, which is a GATT indication; false if the confirmation is not required, which is a GATT notification. + * + * @note + * 1. This function triggers `ESP_GATTS_CONF_EVT`. + * 2. The size of indication or notification data must be less than or equal to MTU size, see `esp_ble_gattc_send_mtu_req`. + * 3. This function should be called only after the connection has been established. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t attr_handle, uint16_t value_len, uint8_t *value, bool need_confirm); - /** - * @brief This function is called to send a response to a request. + * @brief Send a response to a request * - * @param[in] gatts_if: GATT server access interface - * @param[in] conn_id - connection identifier. - * @param[in] trans_id - transfer id - * @param[in] status - response status - * @param[in] rsp - response data. + * @param[in] gatts_if GATT Server access interface + * @param[in] conn_id Connection ID + * @param[in] trans_id Transfer ID + * @param[in] status Response status + * @param[in] rsp The pointer to the response data + * + * @note + * 1. This function triggers `ESP_GATTS_RESPONSE_EVT`. + * 2. This function should be called only after the connection has been established. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_ERR_INVALID_STATE: The connection has not been established. + * - ESP_FAIL: Failure due to other reasons */ esp_err_t esp_ble_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t trans_id, esp_gatt_status_t status, esp_gatt_rsp_t *rsp); - /** - * @brief This function is called to set the attribute value by the application + * @brief Set the attribute value * - * @param[in] attr_handle: the attribute handle which to be set - * @param[in] length: the value length - * @param[in] value: the pointer to the attribute value + * @param[in] attr_handle Target attribute handle to set the value + * @param[in] length The value length in bytes + * @param[in] value The pointer to the attribute value + * + * @note This function triggers `ESP_GATTS_SET_ATTR_VAL_EVT`. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value); /** - * @brief Retrieve attribute value + * @brief Retrieve attribute value * - * @param[in] attr_handle: Attribute handle. - * @param[out] length: pointer to the attribute value length - * @param[out] value: Pointer to attribute value payload, the value cannot be modified by user + * @param[in] attr_handle Attribute handle + * @param[out] length The pointer to the attribute value length in bytes + * @param[out] value The pointer to attribute value payload. This value cannot be modified by user. + * + * @note + * 1. This function does not trigger any event. + * 2. `attr_handle` must be greater than 0. * * @return - * - ESP_GATT_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_GATT_INVALID_HANDLE: Invalid `attr_handle` + * - ESP_FAIL: Failure due to other reasons */ esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const uint8_t **value); - /** - * @brief Open a direct open connection or add a background auto connection + * @brief Create an ACL connection when `BT_BLE_42_FEATURES_SUPPORTED` is enabled in the menuconfig * - * @param[in] gatts_if: GATT server access interface - * @param[in] remote_bda: remote device bluetooth device address. - * @param[in] is_direct: direct connection or background auto connection + * @param[in] gatts_if GATT Server access interface + * @param[in] remote_bda Remote device address + * @param[in] is_direct `True` indicates a direct connection, while `False` indicates a background auto connection. Currently, background auto connection is not supported, so please always set this parameter to True. + * + * @note + * 1. The function always triggers `ESP_GATTS_CONNECT_EVT` and `ESP_GATTS_OPEN_EVT`. + * 2. When the device acts as GATT Server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. + * 3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Server. If the ACL connection already exists, it will create a virtual connection only. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, bool is_direct); /** - * @brief Close a connection a remote device. + * @brief Close a connection with a remote device * - * @param[in] gatts_if: GATT server access interface - * @param[in] conn_id: connection ID to be closed. + * @param[in] gatts_if GATT Server access interface + * @param[in] conn_id Connection ID to be closed + * + * @note + * 1. This function triggers `ESP_GATTS_CLOSE_EVT`. + * 2. There may be multiple virtual GATT server connections when multiple `app_id` got registered. + * 3. This API closes one virtual GATT server connection only, if there exist other virtual GATT server connections. It does not close the physical connection. + * 4. The API `esp_ble_gap_disconnect` can be used to disconnect the physical connection directly. + * 5. If there is only one virtual GATT connection left, this API will terminate the ACL connection in addition, and trigger `ESP_GATTS_DISCONNECT_EVT`. Then there is no need to call `esp_ble_gap_disconnect` anymore. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id); /** - * @brief Send service change indication + * @brief Send service change indication * - * @param[in] gatts_if: GATT server access interface - * @param[in] remote_bda: remote device bluetooth device address. + * @param[in] gatts_if GATT Server access interface + * @param[in] remote_bda Remote device address. * If remote_bda is NULL then it will send service change * indication to all the connected devices and if not then - * to a specific device + * to a specific device. + * + * @note This function triggers `ESP_GATTS_SEND_SERVICE_CHANGE_EVT`. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda); /** - * @brief Print local database (GATT service table) + * @brief Display the Server's local attribute database. + * + * This API prints the local attribute database of the BLE server, including details + * of all services, characteristics, and descriptors. + * + * @note + * 1. This function does not trigger any event. + * 2. It is primarily intended for debugging purposes to verify the server's current configuration. * * @return - * - ESP_OK : success - * - other : failed - * + * - ESP_OK: Success + * - ESP_FAIL: Failure */ esp_err_t esp_ble_gatts_show_local_database(void);