1 /* 2 * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef __ESP_GATTC_API_H__ 8 #define __ESP_GATTC_API_H__ 9 10 #include "esp_bt_defs.h" 11 #include "esp_gatt_defs.h" 12 #include "esp_err.h" 13 14 #ifdef __cplusplus 15 extern "C" { 16 #endif 17 18 /** 19 * @brief GATT Client callback function events 20 */ 21 typedef enum { 22 ESP_GATTC_REG_EVT = 0, /*!< This event is triggered when a GATT Client application is registered using `esp_ble_gattc_app_register`. */ 23 ESP_GATTC_UNREG_EVT = 1, /*!< This event is triggered when a GATT Client application is unregistered using `esp_ble_gattc_app_unregister`. */ 24 ESP_GATTC_OPEN_EVT = 2, /*!< This event is triggered when a GATT virtual connection is set up using `esp_ble_gattc_open`. */ 25 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`. */ 26 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`. */ 27 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. */ 28 ESP_GATTC_SEARCH_CMPL_EVT = 6, /*!< This event is triggered upon the completion of a service discovery using `esp_ble_gattc_search_service`. */ 29 ESP_GATTC_SEARCH_RES_EVT = 7, /*!< This event is triggered each time a service result is obtained using `esp_ble_gattc_search_service`. */ 30 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`. */ 31 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`. */ 32 ESP_GATTC_NOTIFY_EVT = 10, /*!< This event is triggered when a GATT notification or indication is received from the Server. */ 33 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`. */ 34 ESP_GATTC_EXEC_EVT = 12, /*!< This event is triggered upon the completion of a GATT write execution using `esp_ble_gattc_execute_write` .*/ 35 ESP_GATTC_ACL_EVT = 13, /*!< Deprecated. */ 36 ESP_GATTC_CANCEL_OPEN_EVT = 14, /*!< Deprecated. */ 37 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). */ 38 ESP_GATTC_ENC_CMPL_CB_EVT = 17, /*!< Deprecated. */ 39 ESP_GATTC_CFG_MTU_EVT = 18, /*!< This event is triggered upon the completion of the MTU configuration with `esp_ble_gattc_send_mtu_req`. */ 40 ESP_GATTC_ADV_DATA_EVT = 19, /*!< Deprecated. */ 41 ESP_GATTC_MULT_ADV_ENB_EVT = 20, /*!< Deprecated. */ 42 ESP_GATTC_MULT_ADV_UPD_EVT = 21, /*!< Deprecated. */ 43 ESP_GATTC_MULT_ADV_DATA_EVT = 22, /*!< Deprecated. */ 44 ESP_GATTC_MULT_ADV_DIS_EVT = 23, /*!< Deprecated. */ 45 ESP_GATTC_CONGEST_EVT = 24, /*!< This event is triggered when the GATT connection is congested. */ 46 ESP_GATTC_BTH_SCAN_ENB_EVT = 25, /*!< Deprecated. */ 47 ESP_GATTC_BTH_SCAN_CFG_EVT = 26, /*!< Deprecated. */ 48 ESP_GATTC_BTH_SCAN_RD_EVT = 27, /*!< Deprecated. */ 49 ESP_GATTC_BTH_SCAN_THR_EVT = 28, /*!< Deprecated. */ 50 ESP_GATTC_BTH_SCAN_PARAM_EVT = 29, /*!< Deprecated. */ 51 ESP_GATTC_BTH_SCAN_DIS_EVT = 30, /*!< Deprecated. */ 52 ESP_GATTC_SCAN_FLT_CFG_EVT = 31, /*!< Deprecated. */ 53 ESP_GATTC_SCAN_FLT_PARAM_EVT = 32, /*!< Deprecated. */ 54 ESP_GATTC_SCAN_FLT_STATUS_EVT = 33, /*!< Deprecated. */ 55 ESP_GATTC_ADV_VSC_EVT = 34, /*!< Deprecated. */ 56 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`. */ 57 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`. */ 58 ESP_GATTC_CONNECT_EVT = 40, /*!< This event is triggered when the physical connection is set up. */ 59 ESP_GATTC_DISCONNECT_EVT = 41, /*!< This event is triggered when the physical connection is terminated. */ 60 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`. */ 61 ESP_GATTC_QUEUE_FULL_EVT = 43, /*!< This event is triggered when the GATTC command queue is full. */ 62 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`. */ 63 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`. */ 64 ESP_GATTC_DIS_SRVC_CMPL_EVT = 46, /*!< This event is triggered when the GATT service discovery is completed. */ 65 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`. */ 66 } esp_gattc_cb_event_t; 67 68 69 /** 70 * @brief GATT Client callback parameters 71 */ 72 typedef union { 73 74 /** 75 * @brief Callback parameter for the event `ESP_GATTC_REG_EVT` 76 */ 77 struct gattc_reg_evt_param { 78 esp_gatt_status_t status; /*!< Operation status */ 79 uint16_t app_id; /*!< Application ID */ 80 } reg; /*!< Callback parameter for the event `ESP_GATTC_REG_EVT` */ 81 82 /** 83 * @brief Callback parameter for the event `ESP_GATTC_OPEN_EVT`. 84 */ 85 struct gattc_open_evt_param { 86 esp_gatt_status_t status; /*!< Operation status */ 87 uint16_t conn_id; /*!< Connection ID */ 88 esp_bd_addr_t remote_bda; /*!< Remote Bluetooth device address */ 89 uint16_t mtu; /*!< MTU size */ 90 } open; /*!< Callback parameter for the event `ESP_GATTC_OPEN_EVT` */ 91 92 /** 93 * @brief Callback parameter for the event `ESP_GATTC_CLOSE_EVT` 94 */ 95 struct gattc_close_evt_param { 96 esp_gatt_status_t status; /*!< Operation status */ 97 uint16_t conn_id; /*!< Connection ID */ 98 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 99 esp_gatt_conn_reason_t reason; /*!< The reason of GATT connection close */ 100 } close; /*!< Callback parameter for the event `ESP_GATTC_CLOSE_EVT` */ 101 102 /** 103 * @brief Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT` 104 */ 105 struct gattc_cfg_mtu_evt_param { 106 esp_gatt_status_t status; /*!< Operation status */ 107 uint16_t conn_id; /*!< Connection ID */ 108 uint16_t mtu; /*!< MTU size */ 109 } cfg_mtu; /*!< Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT` */ 110 111 /** 112 * @brief Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT` 113 */ 114 struct gattc_search_cmpl_evt_param { 115 esp_gatt_status_t status; /*!< Operation status */ 116 uint16_t conn_id; /*!< Connection ID */ 117 esp_service_source_t searched_service_source; /*!< The source of the service information */ 118 } search_cmpl; /*!< Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT` */ 119 120 /** 121 * @brief Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT` 122 */ 123 struct gattc_search_res_evt_param { 124 uint16_t conn_id; /*!< Connection ID */ 125 uint16_t start_handle; /*!< Service start handle */ 126 uint16_t end_handle; /*!< Service end handle */ 127 esp_gatt_id_t srvc_id; /*!< Service ID, including service UUID and other information */ 128 bool is_primary; /*!< True indicates a primary service, false otherwise */ 129 } search_res; /*!< Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT` */ 130 131 /** 132 * @brief Callback parameter for the events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`, 133 * `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT` 134 */ 135 struct gattc_read_char_evt_param { 136 137 esp_gatt_status_t status; /*!< Operation status */ 138 uint16_t conn_id; /*!< Connection ID */ 139 uint16_t handle; /*!< Characteristic handle */ 140 uint8_t *value; /*!< Characteristic value */ 141 uint16_t value_len; /*!< Characteristic value length */ 142 } read; /*!< Callback parameter for events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`, 143 `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT` */ 144 145 /** 146 * @brief Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT`. 147 */ 148 struct gattc_write_evt_param { 149 esp_gatt_status_t status; /*!< Operation status */ 150 uint16_t conn_id; /*!< Connection ID */ 151 uint16_t handle; /*!< The characteristic or descriptor handle */ 152 uint16_t offset; /*!< The position offset to write. This value is valid only for prepare write operation. */ 153 } write; /*!< Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT` */ 154 155 /** 156 * @brief Callback parameter for the event `ESP_GATTC_EXEC_EVT` 157 */ 158 struct gattc_exec_cmpl_evt_param { 159 esp_gatt_status_t status; /*!< Operation status */ 160 uint16_t conn_id; /*!< Connection ID */ 161 } exec_cmpl; /*!< Callback parameter for the event `ESP_GATTC_EXEC_EVT` */ 162 163 /** 164 * @brief Callback parameter for the event `ESP_GATTC_NOTIFY_EVT` 165 */ 166 struct gattc_notify_evt_param { 167 uint16_t conn_id; /*!< Connection ID */ 168 esp_bd_addr_t remote_bda; /*!< Remote Bluetooth device address. */ 169 uint16_t handle; /*!< The characteristic or descriptor handle */ 170 uint16_t value_len; /*!< Notify attribute value length in bytes */ 171 uint8_t *value; /*!< Notify attribute value */ 172 bool is_notify; /*!< True means notification; false means indication */ 173 } notify; /*!< Callback parameter for the event `ESP_GATTC_NOTIFY_EVT` */ 174 175 /** 176 * @brief Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT` 177 */ 178 struct gattc_srvc_chg_evt_param { 179 esp_bd_addr_t remote_bda; /*!< Remote Bluetooth device address */ 180 } srvc_chg; /*!< Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT` */ 181 182 /** 183 * @brief Callback parameter for the event `ESP_GATTC_CONGEST_EVT` 184 */ 185 struct gattc_congest_evt_param { 186 uint16_t conn_id; /*!< Connection ID */ 187 bool congested; /*!< True indicates that the connection is congested, false otherwise */ 188 } congest; /*!< Callback parameter for the event `ESP_GATTC_CONGEST_EVT` */ 189 /** 190 * @brief Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT` 191 */ 192 struct gattc_reg_for_notify_evt_param { 193 esp_gatt_status_t status; /*!< Operation status */ 194 uint16_t handle; /*!< The characteristic or descriptor handle */ 195 } reg_for_notify; /*!< Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT` */ 196 197 /** 198 * @brief Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT` 199 */ 200 struct gattc_unreg_for_notify_evt_param { 201 esp_gatt_status_t status; /*!< Operation status */ 202 uint16_t handle; /*!< The characteristic or descriptor handle */ 203 } unreg_for_notify; /*!< Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT` */ 204 205 /** 206 * @brief Callback parameter for the event `ESP_GATTC_CONNECT_EVT` 207 */ 208 struct gattc_connect_evt_param { 209 uint16_t conn_id; /*!< Connection ID */ 210 uint8_t link_role; /*!< Link role : master role = 0; slave role = 1 */ 211 esp_bd_addr_t remote_bda; /*!< Remote device address */ 212 esp_gatt_conn_params_t conn_params; /*!< Current connection parameters */ 213 esp_ble_addr_type_t ble_addr_type; /*!< Remote device address type */ 214 uint16_t conn_handle; /*!< HCI connection handle */ 215 } connect; /*!< Callback parameter for the event `ESP_GATTC_CONNECT_EVT` */ 216 217 /** 218 * @brief Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT` 219 */ 220 struct gattc_disconnect_evt_param { 221 esp_gatt_conn_reason_t reason; /*!< Disconnection reason */ 222 uint16_t conn_id; /*!< Connection ID */ 223 esp_bd_addr_t remote_bda; /*!< Remote device address */ 224 } disconnect; /*!< Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT` */ 225 226 /** 227 * @brief Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT` 228 */ 229 struct gattc_set_assoc_addr_cmp_evt_param { 230 esp_gatt_status_t status; /*!< Operation status */ 231 } set_assoc_cmp; /*!< Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT` */ 232 233 /** 234 * @brief Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT` 235 */ 236 struct gattc_get_addr_list_evt_param { 237 esp_gatt_status_t status; /*!< Operation status */ 238 uint8_t num_addr; /*!< The number of addresses in the local GATTC cache address list */ 239 esp_bd_addr_t *addr_list; /*!< The pointer to the address list which has been retrieved from the local GATTC cache */ 240 } get_addr_list; /*!< Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT` */ 241 242 /** 243 * @brief Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT` 244 */ 245 struct gattc_queue_full_evt_param { 246 esp_gatt_status_t status; /*!< Operation status */ 247 uint16_t conn_id; /*!< Connection ID */ 248 bool is_full; /*!< True indicates the GATTC command queue is full; false otherwise. */ 249 } queue_full; /*!< Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT` */ 250 251 /** 252 * @brief Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT` 253 */ 254 struct gattc_dis_srvc_cmpl_evt_param { 255 esp_gatt_status_t status; /*!< Operation status */ 256 uint16_t conn_id; /*!< Connection ID */ 257 } dis_srvc_cmpl; /*!< Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT` */ 258 259 } esp_ble_gattc_cb_param_t; 260 261 /** 262 * @brief GATT Client callback function type 263 * 264 * @param[in] event Event type 265 * @param[in] gattc_if GATT Client access interface 266 * @param[in] param The pointer to callback parameter 267 */ 268 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); 269 270 /** 271 * @brief Register GATT Client application callbacks 272 * 273 * @param[in] callback The pointer to the application callback function 274 * 275 * @return 276 * - ESP_OK: Success 277 * - ESP_FAIL: Failure 278 */ 279 esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback); 280 281 /** 282 * @brief Get the current application callbacks 283 * 284 * @return 285 * - esp_gattc_cb_t: Current callback 286 */ 287 esp_gattc_cb_t esp_ble_gattc_get_callback(void); 288 289 /** 290 * @brief Register a GATT Client application 291 * 292 * @param[in] app_id The UUID for different application 293 * 294 * @note 295 * 1. This function triggers `ESP_GATTC_REG_EVT`. 296 * 2. The maximum number of applications is limited to 4. 297 * 298 * @return 299 * - ESP_OK: Success 300 * - ESP_ERR_INVALID_ARG: The input `app_id` exceeds `ESP_APP_ID_MAX` (0x7fff) defined in esp_bt_defs.h 301 * - ESP_FAIL: Failure due to other reasons 302 */ 303 esp_err_t esp_ble_gattc_app_register(uint16_t app_id); 304 305 /** 306 * @brief Unregister a GATT Client application 307 * 308 * @param[in] gattc_if GATT Client access interface 309 * 310 * @note This function triggers `ESP_GATTC_UNREG_EVT`. 311 * 312 * @return 313 * - ESP_OK: Success 314 * - ESP_FAIL: Failure 315 */ 316 esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if); 317 318 /** 319 * @brief Create an ACL connection 320 * 321 * @note 322 * 1. Do not enable `BT_BLE_42_FEATURES_SUPPORTED` and `BT_BLE_50_FEATURES_SUPPORTED` in the menuconfig simultaneously. 323 * 1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`. 324 * 2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. 325 * 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. 326 327 * 328 * @param[in] gattc_if: GATT client access interface. 329 * @param[in] esp_gatt_create_conn: Pointer to the structure containing connection parameters. 330 * 331 * @return 332 * - ESP_OK: Success 333 * - others: Operation failed 334 * 335 */ 336 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); 337 338 /** 339 * @brief Create an ACL connection when `BT_BLE_42_FEATURES_SUPPORTED` is enabled in the menuconfig 340 * 341 * @param[in] gattc_if GATT Client access interface 342 * @param[in] remote_bda Remote device address 343 * @param[in] remote_addr_type Remote device address type 344 * @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. 345 * 346 * @note 347 * 1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`. 348 * 2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. 349 * 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. 350 * 351 * @return 352 * - ESP_OK: Success 353 * - ESP_FAIL: Failure 354 */ 355 #if (BLE_42_FEATURE_SUPPORT == TRUE) 356 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); 357 #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) 358 359 /** 360 * @brief Create an ACL connection when `BT_BLE_50_FEATURES_SUPPORTED` is enabled in the menuconfig 361 * 362 * @param[in] gattc_if GATT Client access interface 363 * @param[in] remote_bda Remote device address 364 * @param[in] remote_addr_type Remote device address type 365 * @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. 366 * 367 * @note 368 * 1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`. 369 * 2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. 370 * 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. 371 * 372 * @return 373 * - ESP_OK: Success 374 * - ESP_FAIL: Failure 375 */ 376 #if (BLE_50_FEATURE_SUPPORT == TRUE) 377 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); 378 #endif // #if (BLE_50_FEATURE_SUPPORT == TRUE) 379 380 /** 381 * @brief Close the virtual GATT Client connection 382 * 383 * @param[in] gattc_if GATT Client access interface 384 * @param[in] conn_id Connection ID to be closed 385 * 386 * @note 387 * 1. This function triggers `ESP_GATTC_CLOSE_EVT`. 388 * 2. There may be multiple virtual GATT server connections when multiple `app_id` got registered. 389 * 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. 390 * 4. The API `esp_ble_gap_disconnect` can be used to disconnect the physical connection directly. 391 * 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. 392 * 393 * @return 394 * - ESP_OK: Success 395 * - ESP_FAIL: Failure 396 */ 397 esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id); 398 399 /** 400 * @brief Configure the MTU size in the GATT channel 401 * 402 * 403 * @param[in] gattc_if GATT Client access interface 404 * @param[in] conn_id Connection ID 405 * 406 * @note 407 * 1. This function triggers `ESP_GATTC_CFG_MTU_EVT`. 408 * 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). 409 * 410 * @return 411 * - ESP_OK: Success 412 * - ESP_FAIL: Failure 413 */ 414 esp_err_t esp_ble_gattc_send_mtu_req (esp_gatt_if_t gattc_if, uint16_t conn_id); 415 416 /** 417 * @brief Search services from the local GATTC cache 418 * 419 * @param[in] gattc_if GATT Client access interface 420 * @param[in] conn_id Connection ID 421 * @param[in] filter_uuid A UUID of the intended service. If NULL is passed, this API will return all services. 422 * 423 * @note 424 * 1. This function triggers `ESP_GATTC_SEARCH_RES_EVT` each time a service is retrieved. 425 * 2. This function triggers `ESP_GATTC_SEARCH_CMPL_EVT` when the search is completed. 426 * 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. 427 * 428 * @return 429 * - ESP_OK: Success 430 * - ESP_FAIL: Failure 431 */ 432 esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *filter_uuid); 433 434 /** 435 * @brief Get the service with the given service UUID in the local GATTC cache 436 * 437 * @param[in] gattc_if GATT Client access interface 438 * @param[in] conn_id Connection ID 439 * @param[in] svc_uuid The pointer to the service UUID. If NULL is passed, the API will retrieve all services. 440 * @param[out] result The pointer to the service which has been found in the local GATTC cache 441 * @param[inout] count The number of services to retrieve. It will be updated with the actual number of services found. 442 * @param[in] offset The position offset to retrieve 443 * 444 * @note 445 * 1. This API does not trigger any event. 446 * 2. `esp_ble_gattc_cache_refresh` can be used to discover services again. 447 * 448 * @return 449 * - ESP_OK: Success 450 * - ESP_FAIL: Failure 451 */ 452 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, 453 esp_gattc_service_elem_t *result, uint16_t *count, uint16_t offset); 454 455 /** 456 * @brief Get all characteristics with the given handle range in the local GATTC cache 457 * 458 * @param[in] gattc_if GATT Client access interface 459 * @param[in] conn_id Connection ID 460 * @param[in] start_handle The attribute start handle 461 * @param[in] end_handle The attribute end handle 462 * @param[out] result The pointer to the characteristic in the service 463 * @param[inout] count The number of characteristics to retrieve. It will be updated with the actual number of characteristics found. 464 * @param[in] offset The position offset to retrieve 465 * 466 * @note 467 * 1. This API does not trigger any event. 468 * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. 469 * 470 * @return 471 * - ESP_OK: Success 472 * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle` 473 * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 474 * - ESP_FAIL: Failure due to other reasons 475 */ 476 esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, 477 uint16_t conn_id, 478 uint16_t start_handle, 479 uint16_t end_handle, 480 esp_gattc_char_elem_t *result, 481 uint16_t *count, uint16_t offset); 482 483 /** 484 * @brief Get all descriptors with the given characteristic in the local GATTC cache 485 * 486 * @param[in] gattc_if GATT Client access interface 487 * @param[in] conn_id Connection ID which identifies the server 488 * @param[in] char_handle The given characteristic handle 489 * @param[out] result The pointer to the descriptor in the characteristic 490 * @param[inout] count The number of descriptors to retrieve. It will be updated with the actual number of descriptors found. 491 * @param[in] offset The position offset to retrieve 492 * 493 * @note 494 * 1. This API does not trigger any event. 495 * 2. `char_handle` must be greater than 0. 496 * 497 * @return 498 * - ESP_OK: Success 499 * - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle` 500 * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 501 * - ESP_FAIL: Failure due to other reasons 502 */ 503 esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if, 504 uint16_t conn_id, 505 uint16_t char_handle, 506 esp_gattc_descr_elem_t *result, 507 uint16_t *count, uint16_t offset); 508 509 /** 510 * @brief Get the characteristic with the given characteristic UUID in the local GATTC cache 511 * 512 * @param[in] gattc_if GATT Client access interface 513 * @param[in] conn_id Connection ID 514 * @param[in] start_handle The attribute start handle 515 * @param[in] end_handle The attribute end handle 516 * @param[in] char_uuid The characteristic UUID 517 * @param[out] result The pointer to the characteristic in the service 518 * @param[inout] count The number of characteristics to retrieve. It will be updated with the actual number of characteristics found. 519 * 520 * @note 521 * 1. This API does not trigger any event. 522 * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. 523 * 524 * @return 525 * - ESP_OK: Success 526 * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle` 527 * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 528 * - ESP_FAIL: Failure due to other reasons 529 */ 530 esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if, 531 uint16_t conn_id, 532 uint16_t start_handle, 533 uint16_t end_handle, 534 esp_bt_uuid_t char_uuid, 535 esp_gattc_char_elem_t *result, 536 uint16_t *count); 537 538 /** 539 * @brief Get the descriptor with the given characteristic UUID in the local GATTC cache 540 * 541 * @param[in] gattc_if GATT Client access interface 542 * @param[in] conn_id Connection ID 543 * @param[in] start_handle The attribute start handle 544 * @param[in] end_handle The attribute end handle 545 * @param[in] char_uuid The characteristic UUID 546 * @param[in] descr_uuid The descriptor UUID. 547 * @param[out] result The pointer to the descriptor in the given characteristic. 548 * @param[inout] count The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found. 549 * 550 * @note 551 * 1. This API does not trigger any event. 552 * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. 553 * 554 * @return 555 * - ESP_OK: Success 556 * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 557 * - ESP_FAIL: Failure due to other reasons 558 */ 559 esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, 560 uint16_t conn_id, 561 uint16_t start_handle, 562 uint16_t end_handle, 563 esp_bt_uuid_t char_uuid, 564 esp_bt_uuid_t descr_uuid, 565 esp_gattc_descr_elem_t *result, 566 uint16_t *count); 567 568 /** 569 * @brief Get the descriptor with the given characteristic handle in the local GATTC cache 570 * 571 * @param[in] gattc_if GATT Client access interface 572 * @param[in] conn_id Connection ID which identifies the server 573 * @param[in] char_handle The characteristic handle 574 * @param[in] descr_uuid The descriptor UUID 575 * @param[out] result The pointer to the descriptor in the given characteristic 576 * @param[inout] count The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found. 577 * 578 * @note 579 * 1. This API does not trigger any event. 580 * 2. `char_handle` must be greater than 0. 581 * 582 * @return 583 * - ESP_OK: Success 584 * - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle` 585 * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 586 * - ESP_FAIL: Failure due to other reasons 587 */ 588 esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if, 589 uint16_t conn_id, 590 uint16_t char_handle, 591 esp_bt_uuid_t descr_uuid, 592 esp_gattc_descr_elem_t *result, 593 uint16_t *count); 594 595 /** 596 * @brief Get the included services with the given service handle in the local GATTC cache. 597 * 598 * @param[in] gattc_if GATT Client access interface 599 * @param[in] conn_id Connection ID which identifies the server 600 * @param[in] start_handle The attribute start handle 601 * @param[in] end_handle The attribute end handle 602 * @param[in] incl_uuid The included service UUID 603 * @param[out] result The pointer to the included service with the given service handle. 604 * @param[inout] count The number of included services to retrieve. It will be updated with the actual number of included services found. 605 * 606 * @note 607 * 1. This API does not trigger any event. 608 * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. 609 * 610 * @return 611 * - ESP_OK: Success 612 * - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0 613 * - ESP_FAIL: Failure due to other reasons 614 */ 615 esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if, 616 uint16_t conn_id, 617 uint16_t start_handle, 618 uint16_t end_handle, 619 esp_bt_uuid_t *incl_uuid, 620 esp_gattc_incl_svc_elem_t *result, 621 uint16_t *count); 622 623 /** 624 * @brief Get the attribute count with the given service or characteristic in the local GATTC cache 625 * 626 * @param[in] gattc_if GATT Client access interface 627 * @param[in] conn_id Connection ID 628 * @param[in] type The attribute type 629 * @param[in] start_handle The attribute start handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored. 630 * @param[in] end_handle The attribute end handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored. 631 * @param[in] char_handle The characteristic handle. This parameter is valid only if the type is `ESP_GATT_DB_DESCRIPTOR`. 632 * @param[out] count The number of attributes found in the local GATTC cache with the given attribute type 633 * 634 * 635 * @note 636 * 1. This API does not trigger any event. 637 * 2. `start_handle` must be greater than 0, and smaller than `end_handle` if the `type` is not `ESP_GATT_DB_DESCRIPTOR`. 638 * 639 * @return 640 * - ESP_OK: Success 641 * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle` 642 * - ESP_GATT_INVALID_PDU: NULL pointer to `count` 643 * - ESP_FAIL: Failure due to other reasons 644 */ 645 esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, 646 uint16_t conn_id, 647 esp_gatt_db_attr_type_t type, 648 uint16_t start_handle, 649 uint16_t end_handle, 650 uint16_t char_handle, 651 uint16_t *count); 652 653 /** 654 * @brief Get the GATT database elements 655 * 656 * @param[in] gattc_if GATT Client access interface 657 * @param[in] start_handle The attribute start handle 658 * @param[in] end_handle The attribute end handle 659 * @param[in] conn_id Connection ID 660 * @param[out] db The pointer to GATT database elements 661 * @param[inout] count The number of elements in the database to retrieve. It will be updated with the actual number of elements found. 662 * 663 * @note 664 * 1. This API does not trigger any event. 665 * 2. `start_handle` must be greater than 0, and smaller than `end_handle`. 666 * 667 * @return 668 * - ESP_OK: Success 669 * - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle` 670 * - ESP_GATT_INVALID_PDU: NULL pointer to `db` or NULL pointer to `count` or the count value is 0 671 * - ESP_FAIL: Failure due to other reasons 672 * 673 */ 674 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, 675 esp_gattc_db_elem_t *db, uint16_t *count); 676 677 /** 678 * @brief Read the characteristics value of the given characteristic handle 679 * 680 * @param[in] gattc_if GATT Client access interface 681 * @param[in] conn_id Connection ID 682 * @param[in] handle Characteristic handle to read 683 * @param[in] auth_req Authenticate request type 684 * 685 * @note 686 * 1. This function triggers `ESP_GATTC_READ_CHAR_EVT`. 687 * 2. This function should be called only after the connection has been established. 688 * 3. `handle` must be greater than 0. 689 * 690 * @return 691 * - ESP_OK: Success 692 * - ESP_ERR_INVALID_STATE: The connection has not been established. 693 * - ESP_GATT_INVALID_HANDLE: Invalid `handle` 694 * - ESP_FAIL: Failure due to other reasons 695 */ 696 esp_err_t esp_ble_gattc_read_char (esp_gatt_if_t gattc_if, 697 uint16_t conn_id, 698 uint16_t handle, 699 esp_gatt_auth_req_t auth_req); 700 701 /** 702 * @brief Read the characteristics value of the given characteristic UUID. 703 * 704 * @param[in] gattc_if GATT Client access interface. 705 * @param[in] conn_id Connection ID 706 * @param[in] start_handle The attribute start handle 707 * @param[in] end_handle The attribute end handle 708 * @param[in] uuid The pointer to UUID of attribute to read 709 * @param[in] auth_req Authenticate request type 710 * 711 * @note 712 * 1. This function triggers `ESP_GATTC_READ_CHAR_EVT`. 713 * 2. This function should be called only after the connection has been established. 714 * 3. `start_handle` must be greater than 0, and smaller than `end_handle`. 715 * 716 * @return 717 * - ESP_OK: Success 718 * - ESP_GATT_ILLEGAL_PARAMETER: NULL pointer to `uuid` 719 * - ESP_ERR_INVALID_STATE: The connection has not been established 720 * - ESP_FAIL: Failure due to other reasons 721 */ 722 esp_err_t esp_ble_gattc_read_by_type (esp_gatt_if_t gattc_if, 723 uint16_t conn_id, 724 uint16_t start_handle, 725 uint16_t end_handle, 726 esp_bt_uuid_t *uuid, 727 esp_gatt_auth_req_t auth_req); 728 729 /** 730 * @brief Read multiple characteristic or descriptor values 731 * 732 * @param[in] gattc_if GATT Client access interface 733 * @param[in] conn_id Connection ID which specifies the server 734 * @param[in] read_multi Pointer to `esp_gattc_multi_t` 735 * @param[in] auth_req Authenticate request type 736 * 737 * @note 738 * 1. This function triggers `ESP_GATTC_READ_MULTIPLE_EVT`. 739 * 2. This function should be called only after the connection has been established. 740 * 741 * @return 742 * - ESP_OK: Success 743 * - ESP_ERR_INVALID_STATE: The connection has not been established 744 * - ESP_FAIL: Failure due to other reasons 745 */ 746 esp_err_t esp_ble_gattc_read_multiple(esp_gatt_if_t gattc_if, 747 uint16_t conn_id, esp_gattc_multi_t *read_multi, 748 esp_gatt_auth_req_t auth_req); 749 750 /** 751 * @brief Read multiple variable length characteristic values. 752 * 753 * @param[in] gattc_if GATT Client access interface 754 * @param[in] conn_id Connection ID 755 * @param[in] read_multi The pointer to the `esp_gattc_multi_t` 756 * @param[in] auth_req Authenticate request type 757 * 758 * @note 759 * 1. This function triggers `ESP_GATTC_READ_MULTI_VAR_EVT`. 760 * 2. This function should be called only after the connection has been established. 761 * 762 * @return 763 * - ESP_OK: Success 764 * - ESP_ERR_INVALID_STATE: The connection has not been established. 765 * - ESP_FAIL: Failure due to other reasons 766 */ 767 esp_err_t esp_ble_gattc_read_multiple_variable(esp_gatt_if_t gattc_if, 768 uint16_t conn_id, esp_gattc_multi_t *read_multi, 769 esp_gatt_auth_req_t auth_req); 770 771 /** 772 * @brief Read a characteristics descriptor 773 * 774 * @param[in] gattc_if GATT Client access interface 775 * @param[in] conn_id Connection ID 776 * @param[in] handle Descriptor handle to read 777 * @param[in] auth_req Authenticate request type 778 * 779 * @note 780 * 1. This function triggers `ESP_GATTC_READ_DESCR_EVT`. 781 * 2. This function should be called only after the connection has been established. 782 * 3. `handle` must be greater than 0. 783 * 784 * @return 785 * - ESP_OK: Success 786 * - ESP_ERR_INVALID_STATE: The connection has not been established. 787 * - ESP_GATT_INVALID_HANDLE：Invalid `handle` 788 * - ESP_FAIL: Failure due to other reasons 789 */ 790 esp_err_t esp_ble_gattc_read_char_descr (esp_gatt_if_t gattc_if, 791 uint16_t conn_id, 792 uint16_t handle, 793 esp_gatt_auth_req_t auth_req); 794 795 /** 796 * @brief Write the characteristic value of a given characteristic handle 797 * 798 * @param[in] gattc_if GATT Client access interface 799 * @param[in] conn_id Connection ID 800 * @param[in] handle The characteristic handle to write 801 * @param[in] value_len The length of the value to write in bytes 802 * @param[in] value The value to write 803 * @param[in] write_type The type of Attribute write operation 804 * @param[in] auth_req Authentication request type 805 * 806 * @note 807 * 1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`. 808 * 2. This function should be called only after the connection has been established. 809 * 3. `handle` must be greater than 0. 810 * 811 * @return 812 * - ESP_OK: Success 813 * - ESP_ERR_INVALID_STATE: The connection has not been established. 814 * - ESP_GATT_INVALID_HANDLE：Invalid `handle` 815 * - ESP_FAIL: Failure due to other reasons 816 */ 817 esp_err_t esp_ble_gattc_write_char( esp_gatt_if_t gattc_if, 818 uint16_t conn_id, 819 uint16_t handle, 820 uint16_t value_len, 821 uint8_t *value, 822 esp_gatt_write_type_t write_type, 823 esp_gatt_auth_req_t auth_req); 824 825 /** 826 * @brief Write Characteristic descriptor value of a given descriptor handle 827 * 828 * @param[in] gattc_if GATT Client access interface 829 * @param[in] conn_id Connection ID 830 * @param[in] handle The descriptor handle to write. 831 * @param[in] value_len The length of the value to write in bytes. 832 * @param[in] value The value to write 833 * @param[in] write_type The type of Attribute write operation 834 * @param[in] auth_req Authentication request type 835 * 836 * @note 837 * 1. This function triggers `ESP_GATTC_WRITE_DESCR_EVT`. 838 * 2. This function should be called only after the connection has been established. 839 * 3. `handle` must be greater than 0. 840 * 841 * @return 842 * - ESP_OK: Success 843 * - ESP_ERR_INVALID_STATE: The connection has not been established. 844 * - ESP_GATT_INVALID_HANDLE：Invalid `handle` 845 * - ESP_FAIL: Failure due to other reasons 846 */ 847 esp_err_t esp_ble_gattc_write_char_descr (esp_gatt_if_t gattc_if, 848 uint16_t conn_id, 849 uint16_t handle, 850 uint16_t value_len, 851 uint8_t *value, 852 esp_gatt_write_type_t write_type, 853 esp_gatt_auth_req_t auth_req); 854 855 /** 856 * @brief Prepare to write a characteristic value which is longer than the MTU size to a specified characteristic handle 857 * 858 * @param[in] gattc_if GATT Client access interface 859 * @param[in] conn_id Connection ID 860 * @param[in] handle Characteristic handle to prepare to write 861 * @param[in] offset The position offset to write 862 * @param[in] value_len The length of the value to write in bytes 863 * @param[in] value The value to write 864 * @param[in] auth_req Authentication request type 865 * 866 * @note 867 * 1. This function should be called only after the connection has been established. 868 * 2. After using this API, use `esp_ble_gattc_execute_write` to write. 869 * 3. This function triggers `ESP_GATTC_PREP_WRITE_EVT`. 870 * 4. If `value_len` is less than or equal to MTU size, it is recommended to `esp_ble_gattc_write_char` to write directly. 871 * 5. `handle` must be greater than 0. 872 * 873 * @return 874 * - ESP_OK: Success 875 * - ESP_ERR_INVALID_STATE: The connection has not been established. 876 * - ESP_GATT_INVALID_HANDLE：Invalid `handle` 877 * - ESP_FAIL: Failure due to other reasons 878 */ 879 esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, 880 uint16_t conn_id, 881 uint16_t handle, 882 uint16_t offset, 883 uint16_t value_len, 884 uint8_t *value, 885 esp_gatt_auth_req_t auth_req); 886 887 /** 888 * @brief Prepare to write a characteristic descriptor value at a given handle 889 * 890 * @param[in] gattc_if GATT Client access interface 891 * @param[in] conn_id Connection ID 892 * @param[in] handle Characteristic descriptor handle to prepare to write 893 * @param[in] offset The position offset to write 894 * @param[in] value_len The length of the value to write in bytes 895 * @param[in] value The value to write 896 * @param[in] auth_req Authentication request type 897 * 898 * @note 899 * 1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`. 900 * 2. This function should be called only after the connection has been established. 901 * 3. `handle` must be greater than 0. 902 * 903 * @return 904 * - ESP_OK: Success 905 * - ESP_ERR_INVALID_STATE: The connection has not been established. 906 * - ESP_GATT_INVALID_HANDLE：Invalid `handle` 907 * - ESP_FAIL: Failure due to other reasons 908 */ 909 esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, 910 uint16_t conn_id, 911 uint16_t handle, 912 uint16_t offset, 913 uint16_t value_len, 914 uint8_t *value, 915 esp_gatt_auth_req_t auth_req); 916 917 /** 918 * @brief Execute a prepared writing sequence 919 * 920 * @param[in] gattc_if GATT Client access interface 921 * @param[in] conn_id Connection ID 922 * @param[in] is_execute True if it is to execute the writing sequence; false if it is to cancel the writing sequence. 923 * 924 * @note This function triggers `ESP_GATTC_EXEC_EVT`. 925 * 926 * @return 927 * - ESP_OK: Success 928 * - ESP_FAIL: Failure 929 */ 930 esp_err_t esp_ble_gattc_execute_write (esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute); 931 932 /** 933 * @brief Register to receive notification/indication of a characteristic. 934 * 935 * @param[in] gattc_if GATT Client access interface 936 * @param[in] server_bda Target GATT server device address 937 * @param[in] handle Target GATT characteristic handle 938 * 939 * @note 940 * 1. This function triggers `ESP_GATTC_REG_FOR_NOTIFY_EVT`. 941 * 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). 942 * 3. `handle` must be greater than 0. 943 * 944 * @return 945 * - ESP_OK: Success 946 * - ESP_GATT_INVALID_HANDLE：Invalid `handle` 947 * - ESP_FAIL: Failure due to other reasons 948 */ 949 esp_err_t esp_ble_gattc_register_for_notify (esp_gatt_if_t gattc_if, 950 esp_bd_addr_t server_bda, 951 uint16_t handle); 952 953 /** 954 * @brief Unregister the notification of a service. 955 * 956 * @param[in] gattc_if GATT Client access interface 957 * @param[in] server_bda Target GATT server device address 958 * @param[in] handle Target GATT characteristic handle 959 * 960 * @note 961 * 1. This function triggers `ESP_GATTC_UNREG_FOR_NOTIFY_EVT`. 962 * 2. You should call `esp_ble_gattc_write_char_descr()` after this API to write Client Characteristic Configuration (CCC) descriptor value to 0. 963 * 3. `handle` must be greater than 0 964 * @return 965 * - ESP_OK: Success 966 * - ESP_GATT_INVALID_HANDLE：Invalid `handle` 967 * - ESP_FAIL: Failure due to other reasons 968 */ 969 esp_err_t esp_ble_gattc_unregister_for_notify (esp_gatt_if_t gattc_if, 970 esp_bd_addr_t server_bda, 971 uint16_t handle); 972 973 /** 974 * @brief Refresh the cache of the remote device 975 * 976 * @param[in] remote_bda Remote device address 977 * 978 * @note 979 * 1. If the device is connected, this API will restart the discovery of service information of the remote device. 980 * 2. This function triggers `ESP_GATTC_DIS_SRVC_CMPL_EVT` only after the ACL connection is established. Otherwise, no events will be triggered. 981 * 982 * @return 983 * - ESP_OK: Success 984 * - ESP_FAIL: Failure 985 */ 986 esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda); 987 988 /** 989 * @brief Add or remove the association between the address in the local GATTC cache with the source address of the remote device 990 * 991 * @param[in] gattc_if GATT Client access interface 992 * @param[in] src_addr The source address intended to be associated to the `assoc_addr` which has been stored in the local GATTC cache 993 * @param[in] assoc_addr The associated device address intended to share the attribute table with the source address 994 * @param[in] is_assoc True if adding the association; false if removing the association. 995 * 996 * @note 997 * 1. This API is primarily used when the client has a stored server-side database (`assoc_addr`) and needs to connect to 998 * another device (`src_addr`) with the same attribute database. By invoking this API, the stored database is utilized 999 * as the peer server database, eliminating the need for attribute database search and discovery. This reduces 1000 * processing time and accelerates the connection process. 1001 * 2. The attribute table of a device with `assoc_addr` must be stored in the local GATTC cache first. 1002 * Then, the attribute table of the device with `src_addr` must be the same as the one with `assoc_addr`. 1003 * 3. This function triggers `ESP_GATTC_SET_ASSOC_EVT`. 1004 * 1005 * @return 1006 * - ESP_OK: Success 1007 * - ESP_FAIL: Failure 1008 */ 1009 esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr, 1010 esp_bd_addr_t assoc_addr, bool is_assoc); 1011 1012 /** 1013 * @brief Get the address list stored in the local GATTC cache 1014 * 1015 * @param[in] gattc_if GATT Client access interface 1016 * 1017 * @note This function triggers `ESP_GATTC_GET_ADDR_LIST_EVT`. 1018 * 1019 * @return 1020 * - ESP_OK: Success 1021 * - ESP_FAIL: Failure 1022 */ 1023 esp_err_t esp_ble_gattc_cache_get_addr_list(esp_gatt_if_t gattc_if); 1024 1025 /** 1026 * @brief Clean the service cache of the target device in the local GATTC cache 1027 * 1028 * @param[in] remote_bda Remote device address 1029 * 1030 * @return 1031 * - ESP_OK: Success 1032 * - ESP_FAIL: Failure 1033 */ 1034 esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda); 1035 1036 #ifdef __cplusplus 1037 } 1038 #endif 1039 1040 #endif /* __ESP_GATTC_API_H__ */ 1041
