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_GATTC_API_H__ 16 #define __ESP_GATTC_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 Client callback function events 27 typedef enum { 28 ESP_GATTC_REG_EVT = 0, /*!< When GATT client is registered, the event comes */ 29 ESP_GATTC_UNREG_EVT = 1, /*!< When GATT client is unregistered, the event comes */ 30 ESP_GATTC_OPEN_EVT = 2, /*!< When GATT virtual connection is set up, the event comes */ 31 ESP_GATTC_READ_CHAR_EVT = 3, /*!< When GATT characteristic is read, the event comes */ 32 ESP_GATTC_WRITE_CHAR_EVT = 4, /*!< When GATT characteristic write operation completes, the event comes */ 33 ESP_GATTC_CLOSE_EVT = 5, /*!< When GATT virtual connection is closed, the event comes */ 34 ESP_GATTC_SEARCH_CMPL_EVT = 6, /*!< When GATT service discovery is completed, the event comes */ 35 ESP_GATTC_SEARCH_RES_EVT = 7, /*!< When GATT service discovery result is got, the event comes */ 36 ESP_GATTC_READ_DESCR_EVT = 8, /*!< When GATT characteristic descriptor read completes, the event comes */ 37 ESP_GATTC_WRITE_DESCR_EVT = 9, /*!< When GATT characteristic descriptor write completes, the event comes */ 38 ESP_GATTC_NOTIFY_EVT = 10, /*!< When GATT notification or indication arrives, the event comes */ 39 ESP_GATTC_PREP_WRITE_EVT = 11, /*!< When GATT prepare-write operation completes, the event comes */ 40 ESP_GATTC_EXEC_EVT = 12, /*!< When write execution completes, the event comes */ 41 ESP_GATTC_ACL_EVT = 13, /*!< When ACL connection is up, the event comes */ 42 ESP_GATTC_CANCEL_OPEN_EVT = 14, /*!< When GATT client ongoing connection is cancelled, the event comes */ 43 ESP_GATTC_SRVC_CHG_EVT = 15, /*!< When "service changed" occurs, the event comes */ 44 ESP_GATTC_ENC_CMPL_CB_EVT = 17, /*!< When encryption procedure completes, the event comes */ 45 ESP_GATTC_CFG_MTU_EVT = 18, /*!< When configuration of MTU completes, the event comes */ 46 ESP_GATTC_ADV_DATA_EVT = 19, /*!< When advertising of data, the event comes */ 47 ESP_GATTC_MULT_ADV_ENB_EVT = 20, /*!< When multi-advertising is enabled, the event comes */ 48 ESP_GATTC_MULT_ADV_UPD_EVT = 21, /*!< When multi-advertising parameters are updated, the event comes */ 49 ESP_GATTC_MULT_ADV_DATA_EVT = 22, /*!< When multi-advertising data arrives, the event comes */ 50 ESP_GATTC_MULT_ADV_DIS_EVT = 23, /*!< When multi-advertising is disabled, the event comes */ 51 ESP_GATTC_CONGEST_EVT = 24, /*!< When GATT connection congestion comes, the event comes */ 52 ESP_GATTC_BTH_SCAN_ENB_EVT = 25, /*!< When batch scan is enabled, the event comes */ 53 ESP_GATTC_BTH_SCAN_CFG_EVT = 26, /*!< When batch scan storage is configured, the event comes */ 54 ESP_GATTC_BTH_SCAN_RD_EVT = 27, /*!< When Batch scan read event is reported, the event comes */ 55 ESP_GATTC_BTH_SCAN_THR_EVT = 28, /*!< When Batch scan threshold is set, the event comes */ 56 ESP_GATTC_BTH_SCAN_PARAM_EVT = 29, /*!< When Batch scan parameters are set, the event comes */ 57 ESP_GATTC_BTH_SCAN_DIS_EVT = 30, /*!< When Batch scan is disabled, the event comes */ 58 ESP_GATTC_SCAN_FLT_CFG_EVT = 31, /*!< When Scan filter configuration completes, the event comes */ 59 ESP_GATTC_SCAN_FLT_PARAM_EVT = 32, /*!< When Scan filter parameters are set, the event comes */ 60 ESP_GATTC_SCAN_FLT_STATUS_EVT = 33, /*!< When Scan filter status is reported, the event comes */ 61 ESP_GATTC_ADV_VSC_EVT = 34, /*!< When advertising vendor spec content event is reported, the event comes */ 62 ESP_GATTC_REG_FOR_NOTIFY_EVT = 38, /*!< When register for notification of a service completes, the event comes */ 63 ESP_GATTC_UNREG_FOR_NOTIFY_EVT = 39, /*!< When unregister for notification of a service completes, the event comes */ 64 ESP_GATTC_CONNECT_EVT = 40, /*!< When the ble physical connection is set up, the event comes */ 65 ESP_GATTC_DISCONNECT_EVT = 41, /*!< When the ble physical connection disconnected, the event comes */ 66 ESP_GATTC_READ_MULTIPLE_EVT = 42, /*!< When the ble characteristic or descriptor multiple complete, the event comes */ 67 ESP_GATTC_QUEUE_FULL_EVT = 43, /*!< When the gattc command queue full, the event comes */ 68 ESP_GATTC_SET_ASSOC_EVT = 44, /*!< When the ble gattc set the associated address complete, the event comes */ 69 ESP_GATTC_GET_ADDR_LIST_EVT = 45, /*!< When the ble get gattc address list in cache finish, the event comes */ 70 ESP_GATTC_DIS_SRVC_CMPL_EVT = 46, /*!< When the ble discover service complete, the event comes */ 71 } esp_gattc_cb_event_t; 72 73 74 /** 75 * @brief Gatt client callback parameters union 76 */ 77 typedef union { 78 /** 79 * @brief ESP_GATTC_REG_EVT 80 */ 81 struct gattc_reg_evt_param { 82 esp_gatt_status_t status; /*!< Operation status */ 83 uint16_t app_id; /*!< Application id which input in register API */ 84 } reg; /*!< Gatt client callback param of ESP_GATTC_REG_EVT */ 85 86 /** 87 * @brief ESP_GATTC_OPEN_EVT 88 */ 89 struct gattc_open_evt_param { 90 esp_gatt_status_t status; /*!< Operation status */ 91 uint16_t conn_id; /*!< Connection id */ 92 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 93 uint16_t mtu; /*!< MTU size */ 94 } open; /*!< Gatt client callback param of ESP_GATTC_OPEN_EVT */ 95 96 /** 97 * @brief ESP_GATTC_CLOSE_EVT 98 */ 99 struct gattc_close_evt_param { 100 esp_gatt_status_t status; /*!< Operation status */ 101 uint16_t conn_id; /*!< Connection id */ 102 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 103 esp_gatt_conn_reason_t reason; /*!< The reason of gatt connection close */ 104 } close; /*!< Gatt client callback param of ESP_GATTC_CLOSE_EVT */ 105 106 /** 107 * @brief ESP_GATTC_CFG_MTU_EVT 108 */ 109 struct gattc_cfg_mtu_evt_param { 110 esp_gatt_status_t status; /*!< Operation status */ 111 uint16_t conn_id; /*!< Connection id */ 112 uint16_t mtu; /*!< MTU size */ 113 } cfg_mtu; /*!< Gatt client callback param of ESP_GATTC_CFG_MTU_EVT */ 114 115 /** 116 * @brief ESP_GATTC_SEARCH_CMPL_EVT 117 */ 118 struct gattc_search_cmpl_evt_param { 119 esp_gatt_status_t status; /*!< Operation status */ 120 uint16_t conn_id; /*!< Connection id */ 121 esp_service_source_t searched_service_source; /*!< The source of the service information */ 122 } search_cmpl; /*!< Gatt client callback param of ESP_GATTC_SEARCH_CMPL_EVT */ 123 124 /** 125 * @brief ESP_GATTC_SEARCH_RES_EVT 126 */ 127 struct gattc_search_res_evt_param { 128 uint16_t conn_id; /*!< Connection id */ 129 uint16_t start_handle; /*!< Service start handle */ 130 uint16_t end_handle; /*!< Service end handle */ 131 esp_gatt_id_t srvc_id; /*!< Service id, include service uuid and other information */ 132 bool is_primary; /*!< True if this is the primary service */ 133 } search_res; /*!< Gatt client callback param of ESP_GATTC_SEARCH_RES_EVT */ 134 135 /** 136 * @brief ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT 137 */ 138 struct gattc_read_char_evt_param { 139 140 esp_gatt_status_t status; /*!< Operation status */ 141 uint16_t conn_id; /*!< Connection id */ 142 uint16_t handle; /*!< Characteristic handle */ 143 uint8_t *value; /*!< Characteristic value */ 144 uint16_t value_len; /*!< Characteristic value length */ 145 } read; /*!< Gatt client callback param of ESP_GATTC_READ_CHAR_EVT */ 146 147 /** 148 * @brief ESP_GATTC_WRITE_CHAR_EVT, ESP_GATTC_PREP_WRITE_EVT, ESP_GATTC_WRITE_DESCR_EVT 149 */ 150 struct gattc_write_evt_param { 151 esp_gatt_status_t status; /*!< Operation status */ 152 uint16_t conn_id; /*!< Connection id */ 153 uint16_t handle; /*!< The Characteristic or descriptor handle */ 154 uint16_t offset; /*!< The prepare write offset, this value is valid only when prepare write */ 155 } write; /*!< Gatt client callback param of ESP_GATTC_WRITE_DESCR_EVT */ 156 157 /** 158 * @brief ESP_GATTC_EXEC_EVT 159 */ 160 struct gattc_exec_cmpl_evt_param { 161 esp_gatt_status_t status; /*!< Operation status */ 162 uint16_t conn_id; /*!< Connection id */ 163 } exec_cmpl; /*!< Gatt client callback param of ESP_GATTC_EXEC_EVT */ 164 165 /** 166 * @brief ESP_GATTC_NOTIFY_EVT 167 */ 168 struct gattc_notify_evt_param { 169 uint16_t conn_id; /*!< Connection id */ 170 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 171 uint16_t handle; /*!< The Characteristic or descriptor handle */ 172 uint16_t value_len; /*!< Notify attribute value */ 173 uint8_t *value; /*!< Notify attribute value */ 174 bool is_notify; /*!< True means notify, false means indicate */ 175 } notify; /*!< Gatt client callback param of ESP_GATTC_NOTIFY_EVT */ 176 177 /** 178 * @brief ESP_GATTC_SRVC_CHG_EVT 179 */ 180 struct gattc_srvc_chg_evt_param { 181 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 182 } srvc_chg; /*!< Gatt client callback param of ESP_GATTC_SRVC_CHG_EVT */ 183 184 /** 185 * @brief ESP_GATTC_CONGEST_EVT 186 */ 187 struct gattc_congest_evt_param { 188 uint16_t conn_id; /*!< Connection id */ 189 bool congested; /*!< Congested or not */ 190 } congest; /*!< Gatt client callback param of ESP_GATTC_CONGEST_EVT */ 191 /** 192 * @brief ESP_GATTC_REG_FOR_NOTIFY_EVT 193 */ 194 struct gattc_reg_for_notify_evt_param { 195 esp_gatt_status_t status; /*!< Operation status */ 196 uint16_t handle; /*!< The characteristic or descriptor handle */ 197 } reg_for_notify; /*!< Gatt client callback param of ESP_GATTC_REG_FOR_NOTIFY_EVT */ 198 199 /** 200 * @brief ESP_GATTC_UNREG_FOR_NOTIFY_EVT 201 */ 202 struct gattc_unreg_for_notify_evt_param { 203 esp_gatt_status_t status; /*!< Operation status */ 204 uint16_t handle; /*!< The characteristic or descriptor handle */ 205 } unreg_for_notify; /*!< Gatt client callback param of ESP_GATTC_UNREG_FOR_NOTIFY_EVT */ 206 207 /** 208 * @brief ESP_GATTC_CONNECT_EVT 209 */ 210 struct gattc_connect_evt_param { 211 uint16_t conn_id; /*!< Connection id */ 212 uint8_t link_role; /*!< Link role : master role = 0 ; slave role = 1*/ 213 esp_bd_addr_t remote_bda; /*!< Remote bluetooth device address */ 214 esp_gatt_conn_params_t conn_params; /*!< current connection parameters */ 215 } connect; /*!< Gatt client callback param of ESP_GATTC_CONNECT_EVT */ 216 217 /** 218 * @brief 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 bluetooth device address */ 224 } disconnect; /*!< Gatt client callback param of ESP_GATTC_DISCONNECT_EVT */ 225 /** 226 * @brief ESP_GATTC_SET_ASSOC_EVT 227 */ 228 struct gattc_set_assoc_addr_cmp_evt_param { 229 esp_gatt_status_t status; /*!< Operation status */ 230 } set_assoc_cmp; /*!< Gatt client callback param of ESP_GATTC_SET_ASSOC_EVT */ 231 /** 232 * @brief ESP_GATTC_GET_ADDR_LIST_EVT 233 */ 234 struct gattc_get_addr_list_evt_param { 235 esp_gatt_status_t status; /*!< Operation status */ 236 uint8_t num_addr; /*!< The number of address in the gattc cache address list */ 237 esp_bd_addr_t *addr_list; /*!< The pointer to the address list which has been get from the gattc cache */ 238 } get_addr_list; /*!< Gatt client callback param of ESP_GATTC_GET_ADDR_LIST_EVT */ 239 240 /** 241 * @brief ESP_GATTC_QUEUE_FULL_EVT 242 */ 243 struct gattc_queue_full_evt_param { 244 esp_gatt_status_t status; /*!< Operation status */ 245 uint16_t conn_id; /*!< Connection id */ 246 bool is_full; /*!< The gattc command queue is full or not */ 247 } queue_full; /*!< Gatt client callback param of ESP_GATTC_QUEUE_FULL_EVT */ 248 249 /** 250 * @brief ESP_GATTC_DIS_SRVC_CMPL_EVT 251 */ 252 struct gattc_dis_srvc_cmpl_evt_param { 253 esp_gatt_status_t status; /*!< Operation status */ 254 uint16_t conn_id; /*!< Connection id */ 255 } dis_srvc_cmpl; /*!< Gatt client callback param of ESP_GATTC_DIS_SRVC_CMPL_EVT */ 256 257 } esp_ble_gattc_cb_param_t; /*!< GATT client callback parameter union type */ 258 259 /** 260 * @brief GATT Client callback function type 261 * @param event : Event type 262 * @param gattc_if : GATT client access interface, normally 263 * different gattc_if correspond to different profile 264 * @param param : Point to callback parameter, currently is union type 265 */ 266 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); 267 268 /** 269 * @brief This function is called to register application callbacks 270 * with GATTC module. 271 * 272 * @param[in] callback : pointer to the application callback function. 273 * 274 * @return 275 * - ESP_OK: success 276 * - other: failed 277 * 278 */ 279 esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback); 280 281 282 /** 283 * @brief This function is called to register application callbacks 284 * with GATTC module. 285 * 286 * @param[in] app_id : Application Identify (UUID), for different application 287 * 288 * @return 289 * - ESP_OK: success 290 * - other: failed 291 * 292 */ 293 esp_err_t esp_ble_gattc_app_register(uint16_t app_id); 294 295 296 /** 297 * @brief This function is called to unregister an application 298 * from GATTC module. 299 * 300 * @param[in] gattc_if: Gatt client access interface. 301 * 302 * @return 303 * - ESP_OK: success 304 * - other: failed 305 * 306 */ 307 esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if); 308 309 #if (BLE_42_FEATURE_SUPPORT == TRUE) 310 /** 311 * @brief Open a direct connection or add a background auto connection 312 * 313 * @param[in] gattc_if: Gatt client access interface. 314 * @param[in] remote_bda: remote device bluetooth device address. 315 * @param[in] remote_addr_type: remote device bluetooth device the address type. 316 * @param[in] is_direct: direct connection or background auto connection(by now, background auto connection is not supported). 317 * 318 * @return 319 * - ESP_OK: success 320 * - other: failed 321 * 322 */ 323 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); 324 #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) 325 326 #if (BLE_50_FEATURE_SUPPORT == TRUE) 327 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); 328 #endif // #if (BLE_50_FEATURE_SUPPORT == TRUE) 329 /** 330 * @brief Close the virtual connection to the GATT server. gattc may have multiple virtual GATT server connections when multiple app_id registered, 331 * this API only close one virtual GATT server connection. if there exist other virtual GATT server connections, 332 * it does not disconnect the physical connection. 333 * if you want to disconnect the physical connection directly, you can use esp_ble_gap_disconnect(esp_bd_addr_t remote_device). 334 * 335 * @param[in] gattc_if: Gatt client access interface. 336 * @param[in] conn_id: connection ID to be closed. 337 * 338 * @return 339 * - ESP_OK: success 340 * - other: failed 341 * 342 */ 343 esp_err_t esp_ble_gattc_close (esp_gatt_if_t gattc_if, uint16_t conn_id); 344 345 346 /** 347 * @brief Configure the MTU size in the GATT channel. This can be done 348 * only once per connection. Before using, use esp_ble_gatt_set_local_mtu() 349 * to configure the local MTU size. 350 * 351 * 352 * @param[in] gattc_if: Gatt client access interface. 353 * @param[in] conn_id: connection ID. 354 * 355 * @return 356 * - ESP_OK: success 357 * - other: failed 358 * 359 */ 360 esp_err_t esp_ble_gattc_send_mtu_req (esp_gatt_if_t gattc_if, uint16_t conn_id); 361 362 363 /** 364 * @brief This function is called to get service from local cache. 365 * This function report service search result by a callback 366 * event, and followed by a service search complete event. 367 * 368 * @param[in] gattc_if: Gatt client access interface. 369 * @param[in] conn_id: connection ID. 370 * @param[in] filter_uuid: a UUID of the service application is interested in. 371 * If Null, discover for all services. 372 * 373 * @return 374 * - ESP_OK: success 375 * - other: failed 376 * 377 */ 378 esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *filter_uuid); 379 380 /** 381 * @brief Find all the service with the given service uuid in the gattc cache, if the svc_uuid is NULL, find all the service. 382 * Note: It just get service from local cache, won't get from remote devices. If want to get it from remote device, need 383 * to used the esp_ble_gattc_search_service. 384 * 385 * @param[in] gattc_if: Gatt client access interface. 386 * @param[in] conn_id: connection ID which identify the server. 387 * @param[in] svc_uuid: the pointer to the service uuid. 388 * @param[out] result: The pointer to the service which has been found in the gattc cache. 389 * @param[inout] count: input the number of service want to find, 390 * it will output the number of service has been found in the gattc cache with the given service uuid. 391 * @param[in] offset: Offset of the service position to get. 392 * 393 * @return 394 * - ESP_OK: success 395 * - other: failed 396 * 397 */ 398 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, 399 esp_gattc_service_elem_t *result, uint16_t *count, uint16_t offset); 400 401 /** 402 * @brief Find all the characteristic with the given service in the gattc cache 403 * Note: It just get characteristic from local cache, won't get from remote devices. 404 * 405 * @param[in] gattc_if: Gatt client access interface. 406 * @param[in] conn_id: connection ID which identify the server. 407 * @param[in] start_handle: the attribute start handle. 408 * @param[in] end_handle: the attribute end handle 409 * @param[out] result: The pointer to the characteristic in the service. 410 * @param[inout] count: input the number of characteristic want to find, 411 * it will output the number of characteristic has been found in the gattc cache with the given service. 412 * @param[in] offset: Offset of the characteristic position to get. 413 * 414 * @return 415 * - ESP_OK: success 416 * - other: failed 417 * 418 */ 419 esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if, 420 uint16_t conn_id, 421 uint16_t start_handle, 422 uint16_t end_handle, 423 esp_gattc_char_elem_t *result, 424 uint16_t *count, uint16_t offset); 425 426 /** 427 * @brief Find all the descriptor with the given characteristic in the gattc cache 428 * Note: It just get descriptor from local cache, won't get from remote devices. 429 * 430 * @param[in] gattc_if: Gatt client access interface. 431 * @param[in] conn_id: connection ID which identify the server. 432 * @param[in] char_handle: the given characteristic handle 433 * @param[out] result: The pointer to the descriptor in the characteristic. 434 * @param[inout] count: input the number of descriptor want to find, 435 * it will output the number of descriptor has been found in the gattc cache with the given characteristic. 436 * @param[in] offset: Offset of the descriptor position to get. 437 * 438 * @return 439 * - ESP_OK: success 440 * - other: failed 441 * 442 */ 443 esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if, 444 uint16_t conn_id, 445 uint16_t char_handle, 446 esp_gattc_descr_elem_t *result, 447 uint16_t *count, uint16_t offset); 448 449 450 /** 451 * @brief Find the characteristic with the given characteristic uuid in the gattc cache 452 * Note: It just get characteristic from local cache, won't get from remote devices. 453 * 454 * @param[in] gattc_if: Gatt client access interface. 455 * @param[in] conn_id: connection ID which identify the server. 456 * @param[in] start_handle: the attribute start handle 457 * @param[in] end_handle: the attribute end handle 458 * @param[in] char_uuid: the characteristic uuid 459 * @param[out] result: The pointer to the characteristic in the service. 460 * @param[inout] count: input the number of characteristic want to find, 461 * it will output the number of characteristic has been found in the gattc cache with the given service. 462 * 463 * @return 464 * - ESP_OK: success 465 * - other: failed 466 * 467 */ 468 esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if, 469 uint16_t conn_id, 470 uint16_t start_handle, 471 uint16_t end_handle, 472 esp_bt_uuid_t char_uuid, 473 esp_gattc_char_elem_t *result, 474 uint16_t *count); 475 476 /** 477 * @brief Find the descriptor with the given characteristic uuid in the gattc cache 478 * Note: It just get descriptor from local cache, won't get from remote devices. 479 * 480 * @param[in] gattc_if: Gatt client access interface. 481 * @param[in] conn_id: connection ID which identify the server. 482 * @param[in] start_handle: the attribute start handle 483 * @param[in] end_handle: the attribute end handle 484 * @param[in] char_uuid: the characteristic uuid. 485 * @param[in] descr_uuid: the descriptor uuid. 486 * @param[out] result: The pointer to the descriptor in the given characteristic. 487 * @param[inout] count: input the number of descriptor want to find, 488 * it will output the number of descriptor has been found in the gattc cache with the given characteristic. 489 * 490 * @return 491 * - ESP_OK: success 492 * - other: failed 493 * 494 */ 495 esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if, 496 uint16_t conn_id, 497 uint16_t start_handle, 498 uint16_t end_handle, 499 esp_bt_uuid_t char_uuid, 500 esp_bt_uuid_t descr_uuid, 501 esp_gattc_descr_elem_t *result, 502 uint16_t *count); 503 504 /** 505 * @brief Find the descriptor with the given characteristic handle in the gattc cache 506 * Note: It just get descriptor from local cache, won't get from remote devices. 507 * 508 * @param[in] gattc_if: Gatt client access interface. 509 * @param[in] conn_id: connection ID which identify the server. 510 * @param[in] char_handle: the characteristic handle. 511 * @param[in] descr_uuid: the descriptor uuid. 512 * @param[out] result: The pointer to the descriptor in the given characteristic. 513 * @param[inout] count: input the number of descriptor want to find, 514 * it will output the number of descriptor has been found in the gattc cache with the given characteristic. 515 * 516 * @return 517 * - ESP_OK: success 518 * - other: failed 519 * 520 */ 521 esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if, 522 uint16_t conn_id, 523 uint16_t char_handle, 524 esp_bt_uuid_t descr_uuid, 525 esp_gattc_descr_elem_t *result, 526 uint16_t *count); 527 528 /** 529 * @brief Find the include service with the given service handle in the gattc cache 530 * Note: It just get include service from local cache, won't get from remote devices. 531 * 532 * @param[in] gattc_if: Gatt client access interface. 533 * @param[in] conn_id: connection ID which identify the server. 534 * @param[in] start_handle: the attribute start handle 535 * @param[in] end_handle: the attribute end handle 536 * @param[in] incl_uuid: the include service uuid 537 * @param[out] result: The pointer to the include service in the given service. 538 * @param[inout] count: input the number of include service want to find, 539 * it will output the number of include service has been found in the gattc cache with the given service. 540 * 541 * @return 542 * - ESP_OK: success 543 * - other: failed 544 * 545 */ 546 esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if, 547 uint16_t conn_id, 548 uint16_t start_handle, 549 uint16_t end_handle, 550 esp_bt_uuid_t *incl_uuid, 551 esp_gattc_incl_svc_elem_t *result, 552 uint16_t *count); 553 554 555 /** 556 * @brief Find the attribute count with the given service or characteristic in the gattc cache 557 * 558 * @param[in] gattc_if: Gatt client access interface. 559 * @param[in] conn_id: connection ID which identify the server. 560 * @param[in] type: the attribute type. 561 * @param[in] start_handle: the attribute start handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore 562 * @param[in] end_handle: the attribute end handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore 563 * @param[in] char_handle: the characteristic handle, this parameter valid when the type is ESP_GATT_DB_DESCRIPTOR. If the type 564 * isn't ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore. 565 * @param[out] count: output the number of attribute has been found in the gattc cache with the given attribute type. 566 * 567 * @return 568 * - ESP_OK: success 569 * - other: failed 570 * 571 */ 572 esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if, 573 uint16_t conn_id, 574 esp_gatt_db_attr_type_t type, 575 uint16_t start_handle, 576 uint16_t end_handle, 577 uint16_t char_handle, 578 uint16_t *count); 579 580 /** 581 * @brief This function is called to get the GATT database. 582 * Note: It just get attribute data base from local cache, won't get from remote devices. 583 * 584 * @param[in] gattc_if: Gatt client access interface. 585 * @param[in] start_handle: the attribute start handle 586 * @param[in] end_handle: the attribute end handle 587 * @param[in] conn_id: connection ID which identify the server. 588 * @param[in] db: output parameter which will contain the GATT database copy. 589 * Caller is responsible for freeing it. 590 * @param[in] count: number of elements in database. 591 * 592 * @return 593 * - ESP_OK: success 594 * - other: failed 595 * 596 */ 597 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, 598 esp_gattc_db_elem_t *db, uint16_t *count); 599 600 /** 601 * @brief This function is called to read a service's characteristics of 602 * the given characteristic handle 603 * 604 * @param[in] gattc_if: Gatt client access interface. 605 * @param[in] conn_id : connection ID. 606 * @param[in] handle : characteritic handle to read. 607 * @param[in] auth_req : authenticate request type 608 * 609 * @return 610 * - ESP_OK: success 611 * - other: failed 612 * 613 */ 614 esp_err_t esp_ble_gattc_read_char (esp_gatt_if_t gattc_if, 615 uint16_t conn_id, 616 uint16_t handle, 617 esp_gatt_auth_req_t auth_req); 618 619 /** 620 * @brief This function is called to read a service's characteristics of 621 * the given characteristic UUID 622 * 623 * @param[in] gattc_if: Gatt client access interface. 624 * @param[in] conn_id : connection ID. 625 * @param[in] start_handle : the attribute start handle. 626 * @param[in] end_handle : the attribute end handle 627 * @param[in] uuid : The UUID of attribute which will be read. 628 * @param[in] auth_req : authenticate request type 629 * 630 * @return 631 * - ESP_OK: success 632 * - other: failed 633 * 634 */ 635 esp_err_t esp_ble_gattc_read_by_type (esp_gatt_if_t gattc_if, 636 uint16_t conn_id, 637 uint16_t start_handle, 638 uint16_t end_handle, 639 esp_bt_uuid_t *uuid, 640 esp_gatt_auth_req_t auth_req); 641 642 /** 643 * @brief This function is called to read multiple characteristic or 644 * characteristic descriptors. 645 * 646 * @param[in] gattc_if: Gatt client access interface. 647 * @param[in] conn_id : connection ID. 648 * @param[in] read_multi : pointer to the read multiple parameter. 649 * @param[in] auth_req : authenticate request type 650 * 651 * @return 652 * - ESP_OK: success 653 * - other: failed 654 * 655 */ 656 esp_err_t esp_ble_gattc_read_multiple(esp_gatt_if_t gattc_if, 657 uint16_t conn_id, esp_gattc_multi_t *read_multi, 658 esp_gatt_auth_req_t auth_req); 659 660 661 /** 662 * @brief This function is called to read a characteristics descriptor. 663 * 664 * @param[in] gattc_if: Gatt client access interface. 665 * @param[in] conn_id : connection ID. 666 * @param[in] handle : descriptor handle to read. 667 * @param[in] auth_req : authenticate request type 668 * 669 * @return 670 * - ESP_OK: success 671 * - other: failed 672 * 673 */ 674 esp_err_t esp_ble_gattc_read_char_descr (esp_gatt_if_t gattc_if, 675 uint16_t conn_id, 676 uint16_t handle, 677 esp_gatt_auth_req_t auth_req); 678 679 680 /** 681 * @brief This function is called to write characteristic value. 682 * 683 * @param[in] gattc_if: Gatt client access interface. 684 * @param[in] conn_id : connection ID. 685 * @param[in] handle : characteristic handle to write. 686 * @param[in] value_len: length of the value to be written. 687 * @param[in] value : the value to be written. 688 * @param[in] write_type : the type of attribute write operation. 689 * @param[in] auth_req : authentication request. 690 * 691 * @return 692 * - ESP_OK: success 693 * - other: failed 694 * 695 */ 696 esp_err_t esp_ble_gattc_write_char( esp_gatt_if_t gattc_if, 697 uint16_t conn_id, 698 uint16_t handle, 699 uint16_t value_len, 700 uint8_t *value, 701 esp_gatt_write_type_t write_type, 702 esp_gatt_auth_req_t auth_req); 703 704 705 /** 706 * @brief This function is called to write characteristic descriptor value. 707 * 708 * @param[in] gattc_if: Gatt client access interface. 709 * @param[in] conn_id : connection ID 710 * @param[in] handle : descriptor hadle to write. 711 * @param[in] value_len: length of the value to be written. 712 * @param[in] value : the value to be written. 713 * @param[in] write_type : the type of attribute write operation. 714 * @param[in] auth_req : authentication request. 715 * 716 * @return 717 * - ESP_OK: success 718 * - other: failed 719 * 720 */ 721 esp_err_t esp_ble_gattc_write_char_descr (esp_gatt_if_t gattc_if, 722 uint16_t conn_id, 723 uint16_t handle, 724 uint16_t value_len, 725 uint8_t *value, 726 esp_gatt_write_type_t write_type, 727 esp_gatt_auth_req_t auth_req); 728 729 730 /** 731 * @brief This function is called to prepare write a characteristic value. 732 * 733 * @param[in] gattc_if: Gatt client access interface. 734 * @param[in] conn_id : connection ID. 735 * @param[in] handle : characteristic handle to prepare write. 736 * @param[in] offset : offset of the write value. 737 * @param[in] value_len: length of the value to be written. 738 * @param[in] value : the value to be written. 739 * @param[in] auth_req : authentication request. 740 * 741 * @return 742 * - ESP_OK: success 743 * - other: failed 744 * 745 */ 746 esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if, 747 uint16_t conn_id, 748 uint16_t handle, 749 uint16_t offset, 750 uint16_t value_len, 751 uint8_t *value, 752 esp_gatt_auth_req_t auth_req); 753 754 755 /** 756 * @brief This function is called to prepare write a characteristic descriptor value. 757 * 758 * @param[in] gattc_if: Gatt client access interface. 759 * @param[in] conn_id : connection ID. 760 * @param[in] handle : characteristic descriptor handle to prepare write. 761 * @param[in] offset : offset of the write value. 762 * @param[in] value_len: length of the value to be written. 763 * @param[in] value : the value to be written. 764 * @param[in] auth_req : authentication request. 765 * 766 * @return 767 * - ESP_OK: success 768 * - other: failed 769 * 770 */ 771 esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if, 772 uint16_t conn_id, 773 uint16_t handle, 774 uint16_t offset, 775 uint16_t value_len, 776 uint8_t *value, 777 esp_gatt_auth_req_t auth_req); 778 779 780 /** 781 * @brief This function is called to execute write a prepare write sequence. 782 * 783 * @param[in] gattc_if: Gatt client access interface. 784 * @param[in] conn_id : connection ID. 785 * @param[in] is_execute : execute or cancel. 786 * 787 * @return 788 * - ESP_OK: success 789 * - other: failed 790 * 791 */ 792 esp_err_t esp_ble_gattc_execute_write (esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute); 793 794 795 /** 796 * @brief This function is called to register for notification of a service. 797 * 798 * @param[in] gattc_if: Gatt client access interface. 799 * @param[in] server_bda : target GATT server. 800 * @param[in] handle : GATT characteristic handle. 801 * 802 * @return 803 * - ESP_OK: registration succeeds 804 * - other: failed 805 * 806 */ 807 esp_err_t esp_ble_gattc_register_for_notify (esp_gatt_if_t gattc_if, 808 esp_bd_addr_t server_bda, 809 uint16_t handle); 810 811 812 /** 813 * @brief This function is called to de-register for notification of a service. 814 * 815 * @param[in] gattc_if: Gatt client access interface. 816 * @param[in] server_bda : target GATT server. 817 * @param[in] handle : GATT characteristic handle. 818 * 819 * @return 820 * - ESP_OK: unregister succeeds 821 * - other: failed 822 * 823 */ 824 esp_err_t esp_ble_gattc_unregister_for_notify (esp_gatt_if_t gattc_if, 825 esp_bd_addr_t server_bda, 826 uint16_t handle); 827 828 829 /** 830 * @brief Refresh the server cache store in the gattc stack of the remote device. If 831 * the device is connected, this API will restart the discovery of service information of the remote device 832 * 833 * @param[in] remote_bda: remote device BD address. 834 * 835 * @return 836 * - ESP_OK: success 837 * - other: failed 838 * 839 */ 840 esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda); 841 842 /** 843 * @brief Add or delete the associated address with the source address. 844 * Note: The role of this API is mainly when the client side has stored a server-side database, 845 * when it needs to connect another device, but the device's attribute database is the same 846 * as the server database stored on the client-side, calling this API can use the database 847 * that the device has stored used as the peer server database to reduce the attribute 848 * database search and discovery process and speed up the connection time. 849 * The associated address mains that device want to used the database has stored in the local cache. 850 * The source address mains that device want to share the database to the associated address device. 851 * 852 * @param[in] gattc_if: Gatt client access interface. 853 * @param[in] src_addr: the source address which provide the attribute table. 854 * @param[in] assoc_addr: the associated device address which went to share the attribute table with the source address. 855 * @param[in] is_assoc: true add the associated device address, false remove the associated device address. 856 * @return 857 * - ESP_OK: success 858 * - other: failed 859 * 860 */ 861 esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr, 862 esp_bd_addr_t assoc_addr, bool is_assoc); 863 /** 864 * @brief Get the address list which has store the attribute table in the gattc cache. There will 865 * callback ESP_GATTC_GET_ADDR_LIST_EVT event when get address list complete. 866 * 867 * @param[in] gattc_if: Gatt client access interface. 868 * @return 869 * - ESP_OK: success 870 * - other: failed 871 * 872 */ 873 esp_err_t esp_ble_gattc_cache_get_addr_list(esp_gatt_if_t gattc_if); 874 875 /** 876 * @brief Clean the service cache of this device in the gattc stack, 877 * 878 * @param[in] remote_bda: remote device BD address. 879 * 880 * @return 881 * - ESP_OK: success 882 * - other: failed 883 * 884 */ 885 esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda); 886 887 #ifdef __cplusplus 888 } 889 #endif 890 891 #endif /* __ESP_GATTC_API_H__ */ 892
