1 /* 2 * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef __ESP_GATTS_API_H__ 8 #define __ESP_GATTS_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 /// GATT Server callback function events 19 typedef enum { 20 ESP_GATTS_REG_EVT = 0, /*!< This event is triggered when a GATT Server application is registered using `esp_ble_gatts_app_register`. */ 21 ESP_GATTS_READ_EVT = 1, /*!< This event is triggered when the read request from the Client is received. */ 22 ESP_GATTS_WRITE_EVT = 2, /*!< This event is triggered when the write request from the Client is received. */ 23 ESP_GATTS_EXEC_WRITE_EVT = 3, /*!< This event is triggered when the write execution request from the Client is received. */ 24 ESP_GATTS_MTU_EVT = 4, /*!< This event is triggered when the MTU configuration request from the Client is received. */ 25 ESP_GATTS_CONF_EVT = 5, /*!< This event is triggered when the confirmation from the Client is received. */ 26 ESP_GATTS_UNREG_EVT = 6, /*!< This event is triggered when a GATT Server application is unregistered using `esp_ble_gatts_app_unregister`. */ 27 ESP_GATTS_CREATE_EVT = 7, /*!< This event is triggered when a GATT Server service is created using `esp_ble_gatts_create_service`. */ 28 ESP_GATTS_ADD_INCL_SRVC_EVT = 8, /*!< This event is triggered when an included service is added using `esp_ble_gatts_add_included_service`. */ 29 ESP_GATTS_ADD_CHAR_EVT = 9, /*!< This event is triggered when a characteristic is added to the service using `esp_ble_gatts_add_char`. */ 30 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`. */ 31 ESP_GATTS_DELETE_EVT = 11, /*!< This event is triggered when the service is deleted using `esp_ble_gatts_delete_service`. */ 32 ESP_GATTS_START_EVT = 12, /*!< This event is triggered when the service is started using `esp_ble_gatts_start_service`. */ 33 ESP_GATTS_STOP_EVT = 13, /*!< This event is triggered when the service is stopped using `esp_ble_gatts_stop_service`. */ 34 ESP_GATTS_CONNECT_EVT = 14, /*!< This event is triggered when a physical connection is set up. */ 35 ESP_GATTS_DISCONNECT_EVT = 15, /*!< This event is triggered when a physical connection is terminated. */ 36 ESP_GATTS_OPEN_EVT = 16, /*!< This event is triggered when a virtual connection is created using `esp_ble_gatts_open`. */ 37 ESP_GATTS_CANCEL_OPEN_EVT = 17, /*!< Deprecated. */ 38 ESP_GATTS_CLOSE_EVT = 18, /*!< This event is triggered when a virtual connection is closed using `esp_ble_gatts_close`. */ 39 ESP_GATTS_LISTEN_EVT = 19, /*!< Deprecated. */ 40 ESP_GATTS_CONGEST_EVT = 20, /*!< This event is triggered when the GATT connection is congested. */ 41 /* following is extra event */ 42 ESP_GATTS_RESPONSE_EVT = 21, /*!< This event is triggered when a response is sent to the request using `esp_ble_gatts_send_response`. */ 43 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`. */ 44 ESP_GATTS_SET_ATTR_VAL_EVT = 23, /*!< This event is triggered when an attribute value is set using `esp_ble_gatts_set_attr_value`. */ 45 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`. */ 46 } esp_gatts_cb_event_t; 47 48 /** 49 * @brief GATT Server callback parameters 50 */ 51 typedef union { 52 /** 53 * @brief Callback parameter for the event `ESP_GATTS_REG_EVT` 54 */ 55 struct gatts_reg_evt_param { 56 esp_gatt_status_t status; /*!< Operation status */ 57 uint16_t app_id; /*!< Application ID */ 58 } reg; /*!< Callback parameter for the event `ESP_GATTS_REG_EVT` */ 59 60 /** 61 * @brief Callback parameter for the event `ESP_GATTS_READ_EVT` 62 */ 63 struct gatts_read_evt_param { 64 uint16_t conn_id; /*!< Connection ID */ 65 uint32_t trans_id; /*!< Transfer ID */ 66 esp_bd_addr_t bda; /*!< The device address to read */ 67 uint16_t handle; /*!< The attribute handle */ 68 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. */ 69 bool is_long; /*!< True indicates that the length of value is greater than the MTU size; false otherwise. */ 70 bool need_rsp; /*!< True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise. */ 71 } read; /*!< Callback parameter for the event `ESP_GATTS_READ_EVT` */ 72 73 74 /** 75 * @brief Callback parameter for the event `ESP_GATTS_WRITE_EVT` 76 */ 77 struct gatts_write_evt_param { 78 uint16_t conn_id; /*!< Connection ID */ 79 uint32_t trans_id; /*!< Transfer ID */ 80 esp_bd_addr_t bda; /*!< The device address to write */ 81 uint16_t handle; /*!< The attribute handle */ 82 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.*/ 83 bool need_rsp; /*!< True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise. */ 84 bool is_prep; /*!< True indicates the write operation is a prepared write operation */ 85 uint16_t len; /*!< The length of the write attribute value in bytes */ 86 uint8_t *value; /*!< The write attribute value */ 87 } write; /*!< Callback parameter for the event `ESP_GATTS_WRITE_EVT` */ 88 89 /** 90 * @brief Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT` 91 */ 92 struct gatts_exec_write_evt_param { 93 uint16_t conn_id; /*!< Connection ID */ 94 uint32_t trans_id; /*!< Transfer ID */ 95 esp_bd_addr_t bda; /*!< The bluetooth device address to write */ 96 #define ESP_GATT_PREP_WRITE_CANCEL 0x00 /*!< Flag to indicate the cancellation of a prepare write operation */ 97 #define ESP_GATT_PREP_WRITE_EXEC 0x01 /*!< Flag to indicate the execution of a prepare write operation */ 98 uint8_t exec_write_flag; /*!< Execute write flag: `ESP_GATT_PREP_WRITE_CANCEL` or `ESP_GATT_PREP_WRITE_EXEC` */ 99 } exec_write; /*!< Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT` */ 100 101 /** 102 * @brief Callback parameter for the event `ESP_GATTS_MTU_EVT` 103 */ 104 struct gatts_mtu_evt_param { 105 uint16_t conn_id; /*!< Connection ID */ 106 uint16_t mtu; /*!< MTU size */ 107 } mtu; /*!< Callback parameter for the event `ESP_GATTS_MTU_EVT` */ 108 109 /** 110 * @brief Callback parameter for the event `ESP_GATTS_CONF_EVT` 111 */ 112 struct gatts_conf_evt_param { 113 esp_gatt_status_t status; /*!< Operation status */ 114 uint16_t conn_id; /*!< Connection ID */ 115 uint16_t handle; /*!< Attribute handle */ 116 uint16_t len; /*!< The length of indication or notification value in bytes. The length is invalid if the notification or indication failed. */ 117 uint8_t *value; /*!< The indication or notification value. The value is invalid if the notification or indication failed. */ 118 } conf; /*!< Callback parameter for the event `ESP_GATTS_CONF_EVT` */ 119 120 /** 121 * @brief Callback parameter for the event `ESP_GATTS_CREATE_EVT` 122 */ 123 struct gatts_create_evt_param { 124 esp_gatt_status_t status; /*!< Operation status */ 125 uint16_t service_handle; /*!< Service attribute handle */ 126 esp_gatt_srvc_id_t service_id; /*!< Service ID, including service UUID and other information */ 127 } create; /*!< Callback parameter for the event `ESP_GATTS_CREATE_EVT` */ 128 129 /** 130 * @brief Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT` 131 */ 132 struct gatts_add_incl_srvc_evt_param { 133 esp_gatt_status_t status; /*!< Operation status */ 134 uint16_t attr_handle; /*!< Included service attribute handle */ 135 uint16_t service_handle; /*!< Service attribute handle */ 136 } add_incl_srvc; /*!< Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT` */ 137 138 /** 139 * @brief Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT` 140 */ 141 struct gatts_add_char_evt_param { 142 esp_gatt_status_t status; /*!< Operation status */ 143 uint16_t attr_handle; /*!< Characteristic attribute handle */ 144 uint16_t service_handle; /*!< Service attribute handle */ 145 esp_bt_uuid_t char_uuid; /*!< Characteristic UUID */ 146 } add_char; /*!< Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT` */ 147 148 /** 149 * @brief Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT` 150 */ 151 struct gatts_add_char_descr_evt_param { 152 esp_gatt_status_t status; /*!< Operation status */ 153 uint16_t attr_handle; /*!< Descriptor attribute handle */ 154 uint16_t service_handle; /*!< Service attribute handle */ 155 esp_bt_uuid_t descr_uuid; /*!< Characteristic descriptor UUID */ 156 } add_char_descr; /*!< Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT` */ 157 158 /** 159 * @brief Callback parameter for the event `ESP_GATTS_DELETE_EVT` 160 */ 161 struct gatts_delete_evt_param { 162 esp_gatt_status_t status; /*!< Operation status */ 163 uint16_t service_handle; /*!< Service attribute handle */ 164 } del; /*!< Callback parameter for the event `ESP_GATTS_DELETE_EVT` */ 165 166 /** 167 * @brief Callback parameter for the event `ESP_GATTS_START_EVT` 168 */ 169 struct gatts_start_evt_param { 170 esp_gatt_status_t status; /*!< Operation status */ 171 uint16_t service_handle; /*!< Service attribute handle */ 172 } start; /*!< Callback parameter for the event `ESP_GATTS_START_EVT` */ 173 174 /** 175 * @brief Callback parameter for the event `ESP_GATTS_STOP_EVT` 176 */ 177 struct gatts_stop_evt_param { 178 esp_gatt_status_t status; /*!< Operation status */ 179 uint16_t service_handle; /*!< Service attribute handle */ 180 } stop; /*!< Callback parameter for the event `ESP_GATTS_STOP_EVT` */ 181 182 /** 183 * @brief Callback parameter for the event `ESP_GATTS_CONNECT_EVT` 184 */ 185 struct gatts_connect_evt_param { 186 uint16_t conn_id; /*!< Connection ID */ 187 uint8_t link_role; /*!< Link role: master role = 0; slave role = 1 */ 188 esp_bd_addr_t remote_bda; /*!< Remote device address */ 189 esp_gatt_conn_params_t conn_params; /*!< Current connection parameters */ 190 esp_ble_addr_type_t ble_addr_type; /*!< Remote device address type */ 191 uint16_t conn_handle; /*!< HCI connection handle */ 192 } connect; /*!< Callback parameter for the event `ESP_GATTS_CONNECT_EVT` */ 193 194 /** 195 * @brief Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT` 196 */ 197 struct gatts_disconnect_evt_param { 198 uint16_t conn_id; /*!< Connection ID */ 199 esp_bd_addr_t remote_bda; /*!< Remote device address */ 200 esp_gatt_conn_reason_t reason; /*!< The reason of disconnection */ 201 } disconnect; /*!< Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT` */ 202 203 /** 204 * @brief Callback parameter for the event `ESP_GATTS_OPEN_EVT` 205 */ 206 struct gatts_open_evt_param { 207 esp_gatt_status_t status; /*!< Operation status */ 208 } open; /*!< Callback parameter for the event `ESP_GATTS_OPEN_EVT` */ 209 210 /** 211 * @brief Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT` 212 */ 213 struct gatts_cancel_open_evt_param { 214 esp_gatt_status_t status; /*!< Operation status */ 215 } cancel_open; /*!< Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT` */ 216 217 /** 218 * @brief Callback parameter for the event `ESP_GATTS_CLOSE_EVT` 219 */ 220 struct gatts_close_evt_param { 221 esp_gatt_status_t status; /*!< Operation status */ 222 uint16_t conn_id; /*!< Connection ID */ 223 } close; /*!< Callback parameter for the event `ESP_GATTS_CLOSE_EVT` */ 224 225 /** 226 * @brief Callback parameter for the event `ESP_GATTS_CONGEST_EVT` 227 */ 228 struct gatts_congest_evt_param { 229 uint16_t conn_id; /*!< Connection ID */ 230 bool congested; /*!< True indicates the connection is congested; false otherwise. */ 231 } congest; /*!< Callback parameter for the event `ESP_GATTS_CONGEST_EVT` */ 232 233 /** 234 * @brief Callback parameter for the event `ESP_GATTS_RESPONSE_EVT` 235 */ 236 struct gatts_rsp_evt_param { 237 esp_gatt_status_t status; /*!< Operation status */ 238 uint16_t conn_id; /*!< Connection ID */ 239 uint16_t handle; /*!< Attribute handle which sends the response */ 240 } rsp; /*!< Callback parameter for the event `ESP_GATTS_RESPONSE_EVT` */ 241 242 /** 243 * @brief Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT` 244 */ 245 struct gatts_add_attr_tab_evt_param{ 246 esp_gatt_status_t status; /*!< Operation status */ 247 esp_bt_uuid_t svc_uuid; /*!< Service UUID type */ 248 uint8_t svc_inst_id; /*!< Service ID */ 249 uint16_t num_handle; /*!< The number of the attribute handles which have been added to the GATT Service table */ 250 uint16_t *handles; /*!< The handles which have been added to the table */ 251 } add_attr_tab; /*!< Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT` */ 252 253 254 /** 255 * @brief Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT` 256 */ 257 struct gatts_set_attr_val_evt_param{ 258 uint16_t srvc_handle; /*!< The service handle */ 259 uint16_t attr_handle; /*!< The attribute handle */ 260 esp_gatt_status_t status; /*!< Operation status */ 261 } set_attr_val; /*!< Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT` */ 262 263 /** 264 * @brief Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT` 265 */ 266 struct gatts_send_service_change_evt_param{ 267 esp_gatt_status_t status; /*!< Operation status */ 268 } service_change; /*!< Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT` */ 269 270 } esp_ble_gatts_cb_param_t; 271 272 /** 273 * @brief GATT Server callback function type 274 * 275 * @param[in] event Event type 276 * @param[in] gatts_if GATT Server access interface. Typically, different `gatts_if` values correspond to different profiles. 277 * @param[in] param The pointer to the callback parameter, which is of a union type. 278 */ 279 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); 280 281 /** 282 * @brief Register GATT Server application callbacks 283 * 284 * @param[in] callback The pointer to the application callback function 285 * 286 * @return 287 * - ESP_OK: Success 288 * - ESP_FAIL: Failure 289 */ 290 esp_err_t esp_ble_gatts_register_callback(esp_gatts_cb_t callback); 291 292 /** 293 * @brief Get the current GATT Server application callback 294 * 295 * @return 296 * - esp_gatts_cb_t: Current callback 297 */ 298 esp_gatts_cb_t esp_ble_gatts_get_callback(void); 299 300 /** 301 * @brief Register GATT Server application 302 * 303 * @param[in] app_id: The UUID for different application 304 * 305 * @note 306 * 1. This function triggers `ESP_GATTS_REG_EVT`. 307 * 2. The maximum number of applications is limited to 6. 308 * 309 * @return 310 * - ESP_OK: Success 311 * - ESP_ERR_INVALID_ARG: The input `app_id` exceeds `ESP_APP_ID_MAX` (0x7fff) defined in esp_bt_defs.h. 312 * - ESP_FAIL: Failure due to other reasons 313 */ 314 esp_err_t esp_ble_gatts_app_register(uint16_t app_id); 315 316 /** 317 * @brief Unregister an GATT Server application 318 * 319 * @param[in] gatts_if GATT Server access interface. 320 * 321 * @note 322 * 1. This function triggers `ESP_GATTS_UNREG_EVT`. 323 * 2. The maximum number of applications is limited to 6. 324 * 325 * @return 326 * - ESP_OK: Success 327 * - ESP_FAIL: Failure 328 */ 329 esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if); 330 331 /** 332 * @brief Create a GATT Server service 333 * 334 * @param[in] gatts_if GATT Server access interface 335 * @param[in] service_id The pointer to the Service ID 336 * @param[in] num_handle The number of handles requested for this service. 337 * 338 * @note 339 * 1. This function triggers `ESP_GATTS_CREATE_EVT`. 340 * 2. `num_handle` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES. 341 * 342 * @return 343 * - ESP_OK: Success 344 * - ESP_FAIL: Failure 345 */ 346 esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if, 347 esp_gatt_srvc_id_t *service_id, uint16_t num_handle); 348 349 350 /** 351 * @brief Create a service attribute table 352 * 353 * @param[in] gatts_attr_db The pointer to the service attribute table 354 * @param[in] gatts_if GATT Server access interface 355 * @param[in] max_nb_attr The number of attributes to be added to the service database 356 * @param[in] srvc_inst_id The instance ID of the service 357 * 358 * @note 359 * 1. This function triggers `ESP_GATTS_CREAT_ATTR_TAB_EVT`. 360 * 2. `max_nb_attr` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES. 361 * 362 * @return 363 * - ESP_OK: Success 364 * - ESP_ERR_INVALID_ARG: Invalid `max_nb_attr` 365 * - ESP_FAIL: Failure 366 */ 367 esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db, 368 esp_gatt_if_t gatts_if, 369 uint16_t max_nb_attr, 370 uint8_t srvc_inst_id); 371 /** 372 * @brief Add an included service 373 * 374 * @param[in] service_handle Target service handle to add 375 * @param[in] included_service_handle The handle of included service to be added 376 * 377 * @note 378 * 1. This function triggers `ESP_GATTS_ADD_INCL_SRVC_EVT`. 379 * 2. This function has to be called between `esp_ble_gatts_create_service` and `esp_ble_gatts_add_char`. 380 * 381 * @return 382 * - ESP_OK: Success 383 * - ESP_FAIL: Failure 384 */ 385 esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle); 386 387 /** 388 * @brief Add a characteristic into a service. 389 * 390 * @param[in] service_handle Target service handle to add the characteristic 391 * @param[in] char_uuid The pointer to the characteristic UUID 392 * @param[in] perm Characteristic value declaration attribute permission 393 * @param[in] property Characteristic Properties 394 * @param[in] char_val The pointer to the characteristic value 395 * @param[in] control The pointer to the attribute response control byte 396 * 397 * @note 398 * 1. This function triggers `ESP_GATTS_ADD_CHAR_EVT`. 399 * 2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`. 400 * 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. 401 * 402 * @return 403 * - ESP_OK: Success 404 * - ESP_ERR_INVALID_ARG: Invalid arguments 405 * - ESP_FAIL: Failure due to other reasons 406 */ 407 esp_err_t esp_ble_gatts_add_char(uint16_t service_handle, esp_bt_uuid_t *char_uuid, 408 esp_gatt_perm_t perm, esp_gatt_char_prop_t property, esp_attr_value_t *char_val, 409 esp_attr_control_t *control); 410 411 /** 412 * @brief Add a characteristic descriptor 413 * 414 * @param[in] service_handle Target service handle to add the characteristic descriptor 415 * @param[in] descr_uuid The pointer to the descriptor UUID 416 * @param[in] perm Descriptor access permission 417 * @param[in] char_descr_val The pointer to the characteristic descriptor value 418 * @param[in] control The pointer to the attribute response control byte 419 * 420 * @note 421 * 1. This function triggers `ESP_GATTS_ADD_CHAR_DESCR_EVT`. 422 * 2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`. 423 * 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. 424 * 425 * @return 426 * - ESP_OK: Success 427 * - ESP_ERR_INVALID_ARG: Invalid arguments 428 * - ESP_FAIL: Failure due to other reasons 429 */ 430 esp_err_t esp_ble_gatts_add_char_descr (uint16_t service_handle, 431 esp_bt_uuid_t *descr_uuid, 432 esp_gatt_perm_t perm, esp_attr_value_t *char_descr_val, 433 esp_attr_control_t *control); 434 435 /** 436 * @brief Delete a service 437 * 438 * @param[in] service_handle Target service handle to delete 439 * 440 * @note This function triggers `ESP_GATTS_DELETE_EVT`. 441 * 442 * @return 443 * - ESP_OK: Success 444 * - ESP_FAIL: Failure 445 */ 446 esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle); 447 448 /** 449 * @brief Start a service 450 * 451 * @param[in] service_handle Target service handle to start 452 * 453 * @note This function triggers `ESP_GATTS_START_EVT`. 454 * 455 * @return 456 * - ESP_OK: Success 457 * - ESP_FAIL: Failure 458 */ 459 esp_err_t esp_ble_gatts_start_service(uint16_t service_handle); 460 461 /** 462 * @brief Stop a service. 463 * 464 * @param[in] service_handle Target service handle to stop 465 * 466 * @note This function triggers `ESP_GATTS_STOP_EVT`. 467 * 468 * @return 469 * - ESP_OK: Success 470 * - ESP_FAIL: Failure 471 */ 472 esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle); 473 474 /** 475 * @brief Send indication or notification to a GATT Client 476 * 477 * @param[in] gatts_if GATT Server access interface 478 * @param[in] conn_id Connection ID 479 * @param[in] attr_handle Attribute handle to indicate 480 * @param[in] value_len Indication value length in bytes 481 * @param[in] value Value to indicate 482 * @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. 483 * 484 * @note 485 * 1. This function triggers `ESP_GATTS_CONF_EVT`. 486 * 2. The size of indication or notification data must be less than or equal to MTU size, see `esp_ble_gattc_send_mtu_req`. 487 * 3. This function should be called only after the connection has been established. 488 * 489 * @return 490 * - ESP_OK: Success 491 * - ESP_ERR_INVALID_STATE: The connection has not been established. 492 * - ESP_FAIL: Failure due to other reasons 493 */ 494 esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t attr_handle, 495 uint16_t value_len, uint8_t *value, bool need_confirm); 496 497 /** 498 * @brief Send a response to a request 499 * 500 * @param[in] gatts_if GATT Server access interface 501 * @param[in] conn_id Connection ID 502 * @param[in] trans_id Transfer ID 503 * @param[in] status Response status 504 * @param[in] rsp The pointer to the response data 505 * 506 * @note 507 * 1. This function triggers `ESP_GATTS_RESPONSE_EVT`. 508 * 2. This function should be called only after the connection has been established. 509 * 510 * @return 511 * - ESP_OK: Success 512 * - ESP_ERR_INVALID_STATE: The connection has not been established. 513 * - ESP_FAIL: Failure due to other reasons 514 */ 515 esp_err_t esp_ble_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t trans_id, 516 esp_gatt_status_t status, esp_gatt_rsp_t *rsp); 517 518 /** 519 * @brief Set the attribute value 520 * 521 * @param[in] attr_handle Target attribute handle to set the value 522 * @param[in] length The value length in bytes 523 * @param[in] value The pointer to the attribute value 524 * 525 * @note This function triggers `ESP_GATTS_SET_ATTR_VAL_EVT`. 526 * 527 * @return 528 * - ESP_OK: Success 529 * - ESP_FAIL: Failure 530 */ 531 esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value); 532 533 /** 534 * @brief Retrieve attribute value 535 * 536 * @param[in] attr_handle Attribute handle 537 * @param[out] length The pointer to the attribute value length in bytes 538 * @param[out] value The pointer to attribute value payload. This value cannot be modified by user. 539 * 540 * @note 541 * 1. This function does not trigger any event. 542 * 2. `attr_handle` must be greater than 0. 543 * 544 * @return 545 * - ESP_OK: Success 546 * - ESP_GATT_INVALID_HANDLE: Invalid `attr_handle` 547 * - ESP_FAIL: Failure due to other reasons 548 */ 549 esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const uint8_t **value); 550 551 /** 552 * @brief Create an ACL connection when `BT_BLE_42_FEATURES_SUPPORTED` is enabled in the menuconfig 553 * 554 * @param[in] gatts_if GATT Server access interface 555 * @param[in] remote_bda Remote device address 556 * @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. 557 * 558 * @note 559 * 1. The function always triggers `ESP_GATTS_CONNECT_EVT` and `ESP_GATTS_OPEN_EVT`. 560 * 2. When the device acts as GATT Server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well. 561 * 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. 562 * 563 * @return 564 * - ESP_OK: Success 565 * - ESP_FAIL: Failure 566 */ 567 esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, bool is_direct); 568 569 /** 570 * @brief Close a connection with a remote device 571 * 572 * @param[in] gatts_if GATT Server access interface 573 * @param[in] conn_id Connection ID to be closed 574 * 575 * @note 576 * 1. This function triggers `ESP_GATTS_CLOSE_EVT`. 577 * 2. There may be multiple virtual GATT server connections when multiple `app_id` got registered. 578 * 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. 579 * 4. The API `esp_ble_gap_disconnect` can be used to disconnect the physical connection directly. 580 * 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. 581 * 582 * @return 583 * - ESP_OK: Success 584 * - ESP_FAIL: Failure 585 */ 586 esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id); 587 588 /** 589 * @brief Send service change indication 590 * 591 * @param[in] gatts_if GATT Server access interface 592 * @param[in] remote_bda Remote device address. 593 * If remote_bda is NULL then it will send service change 594 * indication to all the connected devices and if not then 595 * to a specific device. 596 * 597 * @note This function triggers `ESP_GATTS_SEND_SERVICE_CHANGE_EVT`. 598 * 599 * @return 600 * - ESP_OK: Success 601 * - ESP_FAIL: Failure 602 */ 603 esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda); 604 605 /** 606 * @brief Display the Server's local attribute database. 607 * 608 * This API prints the local attribute database of the BLE server, including details 609 * of all services, characteristics, and descriptors. 610 * 611 * @note 612 * 1. This function does not trigger any event. 613 * 2. It is primarily intended for debugging purposes to verify the server's current configuration. 614 * 615 * @return 616 * - ESP_OK: Success 617 * - ESP_FAIL: Failure 618 */ 619 esp_err_t esp_ble_gatts_show_local_database(void); 620 621 #ifdef __cplusplus 622 } 623 #endif 624 625 #endif /* __ESP_GATTS_API_H__ */ 626
