1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef __ESP_GATTS_API_H__ 16 #define __ESP_GATTS_API_H__ 17 18 #include "esp_bt_defs.h" 19 #include "esp_gatt_defs.h" 20 #include "esp_err.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 /// GATT Server callback function events 27 typedef enum { 28 ESP_GATTS_REG_EVT = 0, /*!< When register application id, the event comes */ 29 ESP_GATTS_READ_EVT = 1, /*!< When gatt client request read operation, the event comes */ 30 ESP_GATTS_WRITE_EVT = 2, /*!< When gatt client request write operation, the event comes */ 31 ESP_GATTS_EXEC_WRITE_EVT = 3, /*!< When gatt client request execute write, the event comes */ 32 ESP_GATTS_MTU_EVT = 4, /*!< When set mtu complete, the event comes */ 33 ESP_GATTS_CONF_EVT = 5, /*!< When receive confirm, the event comes */ 34 ESP_GATTS_UNREG_EVT = 6, /*!< When unregister application id, the event comes */ 35 ESP_GATTS_CREATE_EVT = 7, /*!< When create service complete, the event comes */ 36 ESP_GATTS_ADD_INCL_SRVC_EVT = 8, /*!< When add included service complete, the event comes */ 37 ESP_GATTS_ADD_CHAR_EVT = 9, /*!< When add characteristic complete, the event comes */ 38 ESP_GATTS_ADD_CHAR_DESCR_EVT = 10, /*!< When add descriptor complete, the event comes */ 39 ESP_GATTS_DELETE_EVT = 11, /*!< When delete service complete, the event comes */ 40 ESP_GATTS_START_EVT = 12, /*!< When start service complete, the event comes */ 41 ESP_GATTS_STOP_EVT = 13, /*!< When stop service complete, the event comes */ 42 ESP_GATTS_CONNECT_EVT = 14, /*!< When gatt client connect, the event comes */ 43 ESP_GATTS_DISCONNECT_EVT = 15, /*!< When gatt client disconnect, the event comes */ 44 ESP_GATTS_OPEN_EVT = 16, /*!< When connect to peer, the event comes */ 45 ESP_GATTS_CANCEL_OPEN_EVT = 17, /*!< When disconnect from peer, the event comes */ 46 ESP_GATTS_CLOSE_EVT = 18, /*!< When gatt server close, the event comes */ 47 ESP_GATTS_LISTEN_EVT = 19, /*!< When gatt listen to be connected the event comes */ 48 ESP_GATTS_CONGEST_EVT = 20, /*!< When congest happen, the event comes */ 49 /* following is extra event */ 50 ESP_GATTS_RESPONSE_EVT = 21, /*!< When gatt send response complete, the event comes */ 51 ESP_GATTS_CREAT_ATTR_TAB_EVT = 22, /*!< When gatt create table complete, the event comes */ 52 ESP_GATTS_SET_ATTR_VAL_EVT = 23, /*!< When gatt set attr value complete, the event comes */ 53 ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24, /*!< When gatt send service change indication complete, the event comes */ 54 } esp_gatts_cb_event_t; 55 56 /** 57 * @brief Gatt server callback parameters union 58 */ 59 typedef union { 60 /** 61 * @brief ESP_GATTS_REG_EVT 62 */ 63 struct gatts_reg_evt_param { 64 esp_gatt_status_t status; /*!< Operation status */ 65 uint16_t app_id; /*!< Application id which input in register API */ 66 } reg; /*!< Gatt server callback param of ESP_GATTS_REG_EVT */ 67 68 /** 69 * @brief ESP_GATTS_READ_EVT 70 */ 71 struct gatts_read_evt_param { 72 uint16_t conn_id; /*!< Connection id */ 73 uint32_t trans_id; /*!< Transfer id */ 74 esp_bd_addr_t bda; /*!< The bluetooth device address which been read */ 75 uint16_t handle; /*!< The attribute handle */ 76 uint16_t offset; /*!< Offset of the value, if the value is too long */ 77 bool is_long; /*!< The value is too long or not */ 78 bool need_rsp; /*!< The read operation need to do response */ 79 } read; /*!< Gatt server callback param of ESP_GATTS_READ_EVT */ 80 81 82 /** 83 * @brief ESP_GATTS_WRITE_EVT 84 */ 85 struct gatts_write_evt_param { 86 uint16_t conn_id; /*!< Connection id */ 87 uint32_t trans_id; /*!< Transfer id */ 88 esp_bd_addr_t bda; /*!< The bluetooth device address which been written */ 89 uint16_t handle; /*!< The attribute handle */ 90 uint16_t offset; /*!< Offset of the value, if the value is too long */ 91 bool need_rsp; /*!< The write operation need to do response */ 92 bool is_prep; /*!< This write operation is prepare write */ 93 uint16_t len; /*!< The write attribute value length */ 94 uint8_t *value; /*!< The write attribute value */ 95 } write; /*!< Gatt server callback param of ESP_GATTS_WRITE_EVT */ 96 97 /** 98 * @brief ESP_GATTS_EXEC_WRITE_EVT 99 */ 100 struct gatts_exec_write_evt_param { 101 uint16_t conn_id; /*!< Connection id */ 102 uint32_t trans_id; /*!< Transfer id */ 103 esp_bd_addr_t bda; /*!< The bluetooth device address which been written */ 104 #define ESP_GATT_PREP_WRITE_CANCEL 0x00 /*!< Prepare write flag to indicate cancel prepare write */ 105 #define ESP_GATT_PREP_WRITE_EXEC 0x01 /*!< Prepare write flag to indicate execute prepare write */ 106 uint8_t exec_write_flag; /*!< Execute write flag */ 107 } exec_write; /*!< Gatt server callback param of ESP_GATTS_EXEC_WRITE_EVT */ 108 109 /** 110 * @brief ESP_GATTS_MTU_EVT 111 */ 112 struct gatts_mtu_evt_param { 113 uint16_t conn_id; /*!< Connection id */ 114 uint16_t mtu; /*!< MTU size */ 115 } mtu; /*!< Gatt server callback param of ESP_GATTS_MTU_EVT */ 116 117 /** 118 * @brief ESP_GATTS_CONF_EVT 119 */ 120 struct gatts_conf_evt_param { 121 esp_gatt_status_t status; /*!< Operation status */ 122 uint16_t conn_id; /*!< Connection id */ 123 uint16_t handle; /*!< attribute handle */ 124 uint16_t len; /*!< The indication or notification value length, len is valid when send notification or indication failed */ 125 uint8_t *value; /*!< The indication or notification value , value is valid when send notification or indication failed */ 126 } conf; /*!< Gatt server callback param of ESP_GATTS_CONF_EVT (confirm) */ 127 128 /** 129 * @brief ESP_GATTS_UNREG_EVT 130 */ 131 132 /** 133 * @brief ESP_GATTS_CREATE_EVT 134 */ 135 struct gatts_create_evt_param { 136 esp_gatt_status_t status; /*!< Operation status */ 137 uint16_t service_handle; /*!< Service attribute handle */ 138 esp_gatt_srvc_id_t service_id; /*!< Service id, include service uuid and other information */ 139 } create; /*!< Gatt server callback param of ESP_GATTS_CREATE_EVT */ 140 141 /** 142 * @brief ESP_GATTS_ADD_INCL_SRVC_EVT 143 */ 144 struct gatts_add_incl_srvc_evt_param { 145 esp_gatt_status_t status; /*!< Operation status */ 146 uint16_t attr_handle; /*!< Included service attribute handle */ 147 uint16_t service_handle; /*!< Service attribute handle */ 148 } add_incl_srvc; /*!< Gatt server callback param of ESP_GATTS_ADD_INCL_SRVC_EVT */ 149 150 /** 151 * @brief ESP_GATTS_ADD_CHAR_EVT 152 */ 153 struct gatts_add_char_evt_param { 154 esp_gatt_status_t status; /*!< Operation status */ 155 uint16_t attr_handle; /*!< Characteristic attribute handle */ 156 uint16_t service_handle; /*!< Service attribute handle */ 157 esp_bt_uuid_t char_uuid; /*!< Characteristic uuid */ 158 } add_char; /*!< Gatt server callback param of ESP_GATTS_ADD_CHAR_EVT */ 159 160 /** 161 * @brief ESP_GATTS_ADD_CHAR_DESCR_EVT 162 */ 163 struct gatts_add_char_descr_evt_param { 164 esp_gatt_status_t status; /*!< Operation status */ 165 uint16_t attr_handle; /*!< Descriptor attribute handle */ 166 uint16_t service_handle; /*!< Service attribute handle */ 167 esp_bt_uuid_t descr_uuid; /*!< Characteristic descriptor uuid */ 168 } add_char_descr; /*!< Gatt server callback param of ESP_GATTS_ADD_CHAR_DESCR_EVT */ 169 170 /** 171 * @brief ESP_GATTS_DELETE_EVT 172 */ 173 struct gatts_delete_evt_param { 174 esp_gatt_status_t status; /*!< Operation status */ 175 uint16_t service_handle; /*!< Service attribute handle */ 176 } del; /*!< Gatt server callback param of ESP_GATTS_DELETE_EVT */ 177 178 /** 179 * @brief ESP_GATTS_START_EVT 180 */ 181 struct gatts_start_evt_param { 182 esp_gatt_status_t status; /*!< Operation status */ 183 uint16_t service_handle; /*!< Service attribute handle */ 184 } start; /*!< Gatt server callback param of ESP_GATTS_START_EVT */ 185 186 /** 187 * @brief ESP_GATTS_STOP_EVT 188 */ 189 struct gatts_stop_evt_param { 190 esp_gatt_status_t status; /*!< Operation status */ 191 uint16_t service_handle; /*!< Service attribute handle */ 192 } stop; /*!< Gatt server callback param of ESP_GATTS_STOP_EVT */ 193 194 /** 195 * @brief ESP_GATTS_CONNECT_EVT 196 */ 197 struct gatts_connect_evt_param { 198 uint16_t conn_id; /*!< Connection id */ 199 uint8_t link_role; /*!< Link role : master role = 0 ; slave role = 1*/ 200 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 201 esp_gatt_conn_params_t conn_params; /*!< current Connection parameters */ 202 } connect; /*!< Gatt server callback param of ESP_GATTS_CONNECT_EVT */ 203 204 /** 205 * @brief ESP_GATTS_DISCONNECT_EVT 206 */ 207 struct gatts_disconnect_evt_param { 208 uint16_t conn_id; /*!< Connection id */ 209 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 210 esp_gatt_conn_reason_t reason; /*!< Indicate the reason of disconnection */ 211 } disconnect; /*!< Gatt server callback param of ESP_GATTS_DISCONNECT_EVT */ 212 213 /** 214 * @brief ESP_GATTS_OPEN_EVT 215 */ 216 struct gatts_open_evt_param { 217 esp_gatt_status_t status; /*!< Operation status */ 218 } open; /*!< Gatt server callback param of ESP_GATTS_OPEN_EVT */ 219 220 /** 221 * @brief ESP_GATTS_CANCEL_OPEN_EVT 222 */ 223 struct gatts_cancel_open_evt_param { 224 esp_gatt_status_t status; /*!< Operation status */ 225 } cancel_open; /*!< Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT */ 226 227 /** 228 * @brief ESP_GATTS_CLOSE_EVT 229 */ 230 struct gatts_close_evt_param { 231 esp_gatt_status_t status; /*!< Operation status */ 232 uint16_t conn_id; /*!< Connection id */ 233 } close; /*!< Gatt server callback param of ESP_GATTS_CLOSE_EVT */ 234 235 /** 236 * @brief ESP_GATTS_LISTEN_EVT 237 */ 238 /** 239 * @brief ESP_GATTS_CONGEST_EVT 240 */ 241 struct gatts_congest_evt_param { 242 uint16_t conn_id; /*!< Connection id */ 243 bool congested; /*!< Congested or not */ 244 } congest; /*!< Gatt server callback param of ESP_GATTS_CONGEST_EVT */ 245 246 /** 247 * @brief ESP_GATTS_RESPONSE_EVT 248 */ 249 struct gatts_rsp_evt_param { 250 esp_gatt_status_t status; /*!< Operation status */ 251 uint16_t handle; /*!< Attribute handle which send response */ 252 } rsp; /*!< Gatt server callback param of ESP_GATTS_RESPONSE_EVT */ 253 254 /** 255 * @brief ESP_GATTS_CREAT_ATTR_TAB_EVT 256 */ 257 struct gatts_add_attr_tab_evt_param{ 258 esp_gatt_status_t status; /*!< Operation status */ 259 esp_bt_uuid_t svc_uuid; /*!< Service uuid type */ 260 uint8_t svc_inst_id; /*!< Service id */ 261 uint16_t num_handle; /*!< The number of the attribute handle to be added to the gatts database */ 262 uint16_t *handles; /*!< The number to the handles */ 263 } add_attr_tab; /*!< Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT */ 264 265 266 /** 267 * @brief ESP_GATTS_SET_ATTR_VAL_EVT 268 */ 269 struct gatts_set_attr_val_evt_param{ 270 uint16_t srvc_handle; /*!< The service handle */ 271 uint16_t attr_handle; /*!< The attribute handle */ 272 esp_gatt_status_t status; /*!< Operation status*/ 273 } set_attr_val; /*!< Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT */ 274 275 /** 276 * @brief ESP_GATTS_SEND_SERVICE_CHANGE_EVT 277 */ 278 struct gatts_send_service_change_evt_param{ 279 esp_gatt_status_t status; /*!< Operation status*/ 280 } service_change; /*!< Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT */ 281 282 } esp_ble_gatts_cb_param_t; 283 284 /** 285 * @brief GATT Server callback function type 286 * @param event : Event type 287 * @param gatts_if : GATT server access interface, normally 288 * different gatts_if correspond to different profile 289 * @param param : Point to callback parameter, currently is union type 290 */ 291 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); 292 293 /** 294 * @brief This function is called to register application callbacks 295 * with BTA GATTS module. 296 * 297 * @return 298 * - ESP_OK : success 299 * - other : failed 300 * 301 */ 302 esp_err_t esp_ble_gatts_register_callback(esp_gatts_cb_t callback); 303 304 /** 305 * @brief This function is called to register application identifier 306 * 307 * @return 308 * - ESP_OK : success 309 * - other : failed 310 * 311 */ 312 esp_err_t esp_ble_gatts_app_register(uint16_t app_id); 313 314 315 316 /** 317 * @brief unregister with GATT Server. 318 * 319 * @param[in] gatts_if: GATT server access interface 320 * @return 321 * - ESP_OK : success 322 * - other : failed 323 * 324 */ 325 esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if); 326 327 328 /** 329 * @brief Create a service. When service creation is done, a callback 330 * event ESP_GATTS_CREATE_EVT is called to report status 331 * and service ID to the profile. The service ID obtained in 332 * the callback function needs to be used when adding included 333 * service and characteristics/descriptors into the service. 334 * 335 * @param[in] gatts_if: GATT server access interface 336 * @param[in] service_id: service ID. 337 * @param[in] num_handle: number of handle requested for this service. 338 * 339 * @return 340 * - ESP_OK : success 341 * - other : failed 342 * 343 */ 344 esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if, 345 esp_gatt_srvc_id_t *service_id, uint16_t num_handle); 346 347 348 /** 349 * @brief Create a service attribute tab. 350 * @param[in] gatts_attr_db: the pointer to the service attr tab 351 * @param[in] gatts_if: GATT server access interface 352 * @param[in] max_nb_attr: the number of attribute to be added to the service database. 353 * @param[in] srvc_inst_id: the instance id of the service 354 * 355 * @return 356 * - ESP_OK : success 357 * - other : failed 358 * 359 */ 360 esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db, 361 esp_gatt_if_t gatts_if, 362 uint8_t max_nb_attr, 363 uint8_t srvc_inst_id); 364 /** 365 * @brief This function is called to add an included service. This function have to be called between 366 * 'esp_ble_gatts_create_service' and 'esp_ble_gatts_add_char'. After included 367 * service is included, a callback event ESP_GATTS_ADD_INCL_SRVC_EVT 368 * is reported the included service ID. 369 * 370 * @param[in] service_handle: service handle to which this included service is to 371 * be added. 372 * @param[in] included_service_handle: the service ID to be included. 373 * 374 * @return 375 * - ESP_OK : success 376 * - other : failed 377 * 378 */ 379 esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle); 380 381 382 383 /** 384 * @brief This function is called to add a characteristic into a service. 385 * 386 * @param[in] service_handle: service handle to which this included service is to 387 * be added. 388 * @param[in] char_uuid : Characteristic UUID. 389 * @param[in] perm : Characteristic value declaration attribute permission. 390 * @param[in] property : Characteristic Properties 391 * @param[in] char_val : Characteristic value 392 * @param[in] control : attribute response control byte 393 * 394 * @return 395 * - ESP_OK : success 396 * - other : failed 397 * 398 */ 399 esp_err_t esp_ble_gatts_add_char(uint16_t service_handle, esp_bt_uuid_t *char_uuid, 400 esp_gatt_perm_t perm, esp_gatt_char_prop_t property, esp_attr_value_t *char_val, 401 esp_attr_control_t *control); 402 403 404 /** 405 * @brief This function is called to add characteristic descriptor. When 406 * it's done, a callback event ESP_GATTS_ADD_DESCR_EVT is called 407 * to report the status and an ID number for this descriptor. 408 * 409 * @param[in] service_handle: service handle to which this characteristic descriptor is to 410 * be added. 411 * @param[in] perm: descriptor access permission. 412 * @param[in] descr_uuid: descriptor UUID. 413 * @param[in] char_descr_val : Characteristic descriptor value 414 * @param[in] control : attribute response control byte 415 * @return 416 * - ESP_OK : success 417 * - other : failed 418 * 419 */ 420 esp_err_t esp_ble_gatts_add_char_descr (uint16_t service_handle, 421 esp_bt_uuid_t *descr_uuid, 422 esp_gatt_perm_t perm, esp_attr_value_t *char_descr_val, 423 esp_attr_control_t *control); 424 425 426 427 /** 428 * @brief This function is called to delete a service. When this is done, 429 * a callback event ESP_GATTS_DELETE_EVT is report with the status. 430 * 431 * @param[in] service_handle: service_handle to be deleted. 432 * 433 * @return 434 * - ESP_OK : success 435 * - other : failed 436 * 437 */ 438 esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle); 439 440 441 442 /** 443 * @brief This function is called to start a service. 444 * 445 * @param[in] service_handle: the service handle to be started. 446 * 447 * @return 448 * - ESP_OK : success 449 * - other : failed 450 * 451 */ 452 esp_err_t esp_ble_gatts_start_service(uint16_t service_handle); 453 454 455 456 /** 457 * @brief This function is called to stop a service. 458 * 459 * @param[in] service_handle - service to be topped. 460 * 461 * @return 462 * - ESP_OK : success 463 * - other : failed 464 * 465 */ 466 esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle); 467 468 469 470 /** 471 * @brief Send indicate or notify to GATT client. 472 * Set param need_confirm as false will send notification, otherwise indication. 473 * 474 * @param[in] gatts_if: GATT server access interface 475 * @param[in] conn_id - connection id to indicate. 476 * @param[in] attr_handle - attribute handle to indicate. 477 * @param[in] value_len - indicate value length. 478 * @param[in] value: value to indicate. 479 * @param[in] need_confirm - Whether a confirmation is required. 480 * false sends a GATT notification, true sends a GATT indication. 481 * 482 * @return 483 * - ESP_OK : success 484 * - other : failed 485 * 486 */ 487 esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t attr_handle, 488 uint16_t value_len, uint8_t *value, bool need_confirm); 489 490 491 /** 492 * @brief This function is called to send a response to a request. 493 * 494 * @param[in] gatts_if: GATT server access interface 495 * @param[in] conn_id - connection identifier. 496 * @param[in] trans_id - transfer id 497 * @param[in] status - response status 498 * @param[in] rsp - response data. 499 * 500 * @return 501 * - ESP_OK : success 502 * - other : failed 503 * 504 */ 505 esp_err_t esp_ble_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t trans_id, 506 esp_gatt_status_t status, esp_gatt_rsp_t *rsp); 507 508 509 /** 510 * @brief This function is called to set the attribute value by the application 511 * 512 * @param[in] attr_handle: the attribute handle which to be set 513 * @param[in] length: the value length 514 * @param[in] value: the pointer to the attribute value 515 * 516 * @return 517 * - ESP_OK : success 518 * - other : failed 519 * 520 */ 521 esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value); 522 523 /** 524 * @brief Retrieve attribute value 525 * 526 * @param[in] attr_handle: Attribute handle. 527 * @param[out] length: pointer to the attribute value length 528 * @param[out] value: Pointer to attribute value payload, the value cannot be modified by user 529 * 530 * @return 531 * - ESP_GATT_OK : success 532 * - other : failed 533 * 534 */ 535 esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const uint8_t **value); 536 537 538 /** 539 * @brief Open a direct open connection or add a background auto connection 540 * 541 * @param[in] gatts_if: GATT server access interface 542 * @param[in] remote_bda: remote device bluetooth device address. 543 * @param[in] is_direct: direct connection or background auto connection 544 * 545 * @return 546 * - ESP_OK : success 547 * - other : failed 548 * 549 */ 550 esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, bool is_direct); 551 552 /** 553 * @brief Close a connection a remote device. 554 * 555 * @param[in] gatts_if: GATT server access interface 556 * @param[in] conn_id: connection ID to be closed. 557 * 558 * @return 559 * - ESP_OK : success 560 * - other : failed 561 * 562 */ 563 esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id); 564 565 /** 566 * @brief Send service change indication 567 * 568 * @param[in] gatts_if: GATT server access interface 569 * @param[in] remote_bda: remote device bluetooth device address. 570 * If remote_bda is NULL then it will send service change 571 * indication to all the connected devices and if not then 572 * to a specific device 573 * 574 * @return 575 * - ESP_OK : success 576 * - other : failed 577 * 578 */ 579 esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda); 580 581 #ifdef __cplusplus 582 } 583 #endif 584 585 #endif /* __ESP_GATTS_API_H__ */ 586
