1 /* 2 * Copyright (C) 2014 BlueKitchen GmbH 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions 6 * are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 3. Neither the name of the copyright holders nor the names of 14 * contributors may be used to endorse or promote products derived 15 * from this software without specific prior written permission. 16 * 4. Any redistribution, use, or modification is done solely for 17 * personal benefit and not for any commercial purpose or for 18 * monetary gain. 19 * 20 * THIS SOFTWARE IS PROVIDED BY BLUEKITCHEN GMBH AND CONTRIBUTORS 21 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 23 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL BLUEKITCHEN 24 * GMBH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 25 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 27 * OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 30 * THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31 * SUCH DAMAGE. 32 * 33 * Please inquire about commercial licensing options at 34 * [email protected] 35 * 36 */ 37 38 /** 39 * @title GATT Client 40 * 41 */ 42 43 #ifndef btstack_gatt_client_h 44 #define btstack_gatt_client_h 45 46 #include "hci.h" 47 48 #if defined __cplusplus 49 extern "C" { 50 #endif 51 52 typedef enum { 53 P_READY, 54 P_W2_SEND_SERVICE_QUERY, 55 P_W4_SERVICE_QUERY_RESULT, 56 P_W2_SEND_SERVICE_WITH_UUID_QUERY, 57 P_W4_SERVICE_WITH_UUID_RESULT, 58 59 P_W2_SEND_ALL_CHARACTERISTICS_OF_SERVICE_QUERY, 60 P_W4_ALL_CHARACTERISTICS_OF_SERVICE_QUERY_RESULT, 61 P_W2_SEND_CHARACTERISTIC_WITH_UUID_QUERY, 62 P_W4_CHARACTERISTIC_WITH_UUID_QUERY_RESULT, 63 64 P_W2_SEND_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY, 65 P_W4_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT, 66 67 P_W2_SEND_INCLUDED_SERVICE_QUERY, 68 P_W4_INCLUDED_SERVICE_QUERY_RESULT, 69 P_W2_SEND_INCLUDED_SERVICE_WITH_UUID_QUERY, 70 P_W4_INCLUDED_SERVICE_UUID_WITH_QUERY_RESULT, 71 72 P_W2_SEND_READ_CHARACTERISTIC_VALUE_QUERY, 73 P_W4_READ_CHARACTERISTIC_VALUE_RESULT, 74 75 P_W2_SEND_READ_BLOB_QUERY, 76 P_W4_READ_BLOB_RESULT, 77 78 P_W2_SEND_READ_BY_TYPE_REQUEST, 79 P_W4_READ_BY_TYPE_RESPONSE, 80 81 P_W2_SEND_READ_MULTIPLE_REQUEST, 82 P_W4_READ_MULTIPLE_RESPONSE, 83 84 P_W2_SEND_WRITE_CHARACTERISTIC_VALUE, 85 P_W4_WRITE_CHARACTERISTIC_VALUE_RESULT, 86 87 P_W2_PREPARE_WRITE, 88 P_W4_PREPARE_WRITE_RESULT, 89 P_W2_PREPARE_RELIABLE_WRITE, 90 P_W4_PREPARE_RELIABLE_WRITE_RESULT, 91 92 P_W2_EXECUTE_PREPARED_WRITE, 93 P_W4_EXECUTE_PREPARED_WRITE_RESULT, 94 P_W2_CANCEL_PREPARED_WRITE, 95 P_W4_CANCEL_PREPARED_WRITE_RESULT, 96 P_W2_CANCEL_PREPARED_WRITE_DATA_MISMATCH, 97 P_W4_CANCEL_PREPARED_WRITE_DATA_MISMATCH_RESULT, 98 99 #ifdef ENABLE_GATT_FIND_INFORMATION_FOR_CCC_DISCOVERY 100 P_W2_SEND_FIND_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 101 P_W4_FIND_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 102 #else 103 P_W2_SEND_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 104 P_W4_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 105 #endif 106 P_W2_WRITE_CLIENT_CHARACTERISTIC_CONFIGURATION, 107 P_W4_CLIENT_CHARACTERISTIC_CONFIGURATION_RESULT, 108 109 P_W2_SEND_READ_CHARACTERISTIC_DESCRIPTOR_QUERY, 110 P_W4_READ_CHARACTERISTIC_DESCRIPTOR_RESULT, 111 112 P_W2_SEND_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_QUERY, 113 P_W4_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_RESULT, 114 115 P_W2_SEND_WRITE_CHARACTERISTIC_DESCRIPTOR, 116 P_W4_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 117 118 // all long writes use this 119 P_W2_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR, 120 P_W4_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 121 P_W2_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR, 122 P_W4_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 123 124 // gatt reliable write API use this (manual version of the above) 125 P_W2_PREPARE_WRITE_SINGLE, 126 P_W4_PREPARE_WRITE_SINGLE_RESULT, 127 128 P_W4_IDENTITY_RESOLVING, 129 P_W4_CMAC_READY, 130 P_W4_CMAC_RESULT, 131 P_W2_SEND_SIGNED_WRITE, 132 P_W4_SEND_SINGED_WRITE_DONE, 133 134 P_W2_SDP_QUERY, 135 P_W4_SDP_QUERY, 136 P_W4_L2CAP_CONNECTION, 137 } gatt_client_state_t; 138 139 140 typedef enum{ 141 SEND_MTU_EXCHANGE, 142 SENT_MTU_EXCHANGE, 143 MTU_EXCHANGED, 144 MTU_AUTO_EXCHANGE_DISABLED 145 } gatt_client_mtu_t; 146 147 typedef struct gatt_client{ 148 btstack_linked_item_t item; 149 // TODO: rename gatt_client_state -> state 150 gatt_client_state_t gatt_client_state; 151 152 // user callback 153 btstack_packet_handler_t callback; 154 155 // can write without response callback 156 btstack_packet_handler_t write_without_response_callback; 157 158 // can write without response requests 159 btstack_linked_list_t write_without_response_requests; 160 161 // regular gatt query requests 162 btstack_linked_list_t query_requests; 163 164 hci_con_handle_t con_handle; 165 166 #ifdef ENABLE_GATT_OVER_CLASSIC 167 bd_addr_t addr; 168 uint16_t l2cap_psm; 169 uint16_t l2cap_cid; 170 btstack_context_callback_registration_t sdp_query_request; 171 #endif 172 173 uint16_t mtu; 174 gatt_client_mtu_t mtu_state; 175 176 uint16_t uuid16; 177 uint8_t uuid128[16]; 178 179 uint16_t start_group_handle; 180 uint16_t end_group_handle; 181 182 uint16_t query_start_handle; 183 uint16_t query_end_handle; 184 185 uint8_t characteristic_properties; 186 uint16_t characteristic_start_handle; 187 188 uint16_t attribute_handle; 189 uint16_t attribute_offset; 190 uint16_t attribute_length; 191 uint8_t* attribute_value; 192 193 // read multiple characteristic values 194 uint16_t read_multiple_handle_count; 195 uint16_t * read_multiple_handles; 196 197 uint16_t client_characteristic_configuration_handle; 198 uint8_t client_characteristic_configuration_value[2]; 199 200 uint8_t filter_with_uuid; 201 uint8_t send_confirmation; 202 203 int le_device_index; 204 uint8_t cmac[8]; 205 206 btstack_timer_source_t gc_timeout; 207 208 uint8_t security_counter; 209 uint8_t wait_for_authentication_complete; 210 uint8_t pending_error_code; 211 212 bool reencryption_active; 213 uint8_t reencryption_result; 214 215 gap_security_level_t security_level; 216 217 } gatt_client_t; 218 219 typedef struct gatt_client_notification { 220 btstack_linked_item_t item; 221 btstack_packet_handler_t callback; 222 hci_con_handle_t con_handle; 223 uint16_t attribute_handle; 224 } gatt_client_notification_t; 225 226 /* API_START */ 227 228 typedef struct { 229 uint16_t start_group_handle; 230 uint16_t end_group_handle; 231 uint16_t uuid16; 232 uint8_t uuid128[16]; 233 } gatt_client_service_t; 234 235 typedef struct { 236 uint16_t start_handle; 237 uint16_t value_handle; 238 uint16_t end_handle; 239 uint16_t properties; 240 uint16_t uuid16; 241 uint8_t uuid128[16]; 242 } gatt_client_characteristic_t; 243 244 typedef struct { 245 uint16_t handle; 246 uint16_t uuid16; 247 uint8_t uuid128[16]; 248 } gatt_client_characteristic_descriptor_t; 249 250 /** 251 * @brief Set up GATT client. 252 */ 253 void gatt_client_init(void); 254 255 /** 256 * @brief Set minimum required security level for GATT Client 257 * @note The Bluetooth specification makes the GATT Server responsible to check for security. 258 * This allows an attacker to spoof an existing device with a GATT Servers, but skip the authentication part. 259 * If your application is exchanging sensitive data with a remote device, you would need to manually check 260 * the security level before sending/receive such data. 261 * With level > 0, the GATT Client triggers authentication for all GATT Requests and defers any exchange 262 * until the required security level is established. 263 * gatt_client_request_can_write_without_response_event does not trigger authentication 264 * gatt_client_request_to_write_without_response does not trigger authentication 265 * @pram level, default LEVEL_0 (no encryption required) 266 */ 267 void gatt_client_set_required_security_level(gap_security_level_t level); 268 269 /** 270 * @brief Connect to remote GATT Server over Classic (BR/EDR) Connection 271 * @note requires ENABLE_GATT_OVER_CLASSIC 272 * @param addr 273 * @return status 274 */ 275 uint8_t gatt_client_classic_connect(btstack_packet_handler_t callback, bd_addr_t addr); 276 277 /** 278 * @brief Disconnect o Classic (BR/EDR) connection to a remote GATT Server 279 * @note requires ENABLE_GATT_OVER_CLASSIC 280 * @param addr 281 * @return status 282 */ 283 uint8_t gatt_client_classic_disconnect(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 284 285 /** 286 * @brief MTU is available after the first query has completed. If status is equal to ERROR_CODE_SUCCESS, it returns the real value, 287 * otherwise the default value ATT_DEFAULT_MTU (see bluetooth.h). 288 * @param con_handle 289 * @param mtu 290 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 291 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 292 * GATT_CLIENT_IN_WRONG_STATE if MTU is not exchanged and MTU auto-exchange is disabled 293 * ERROR_CODE_SUCCESS if query is successfully registered 294 */ 295 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 296 297 /** 298 * @brief Sets whether a MTU Exchange Request shall be automatically send before the 299 * first attribute read request is send. Default is enabled. 300 * @param enabled 301 */ 302 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 303 304 /** 305 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU 306 * when gatt_client_mtu_enable_auto_negotiation is disabled. 307 * @param callback 308 * @param con_handle 309 */ 310 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 311 312 /** 313 * @brief Returns 1 if the GATT client is ready to receive a query. It is used with daemon. 314 * @param con_handle 315 * @return is_ready_status 0 - if no GATT client for con_handle is found, or is not ready, otherwise 1 316 */ 317 int gatt_client_is_ready(hci_con_handle_t con_handle); 318 319 /** 320 * @brief Discovers all primary services. 321 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 322 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 323 * @param callback 324 * @param con_handle 325 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 326 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 327 * ERROR_CODE_SUCCESS , if query is successfully registered 328 */ 329 uint8_t gatt_client_discover_primary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 330 331 /** 332 * @brief Discovers all secondary services. 333 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 334 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 335 * @param callback 336 * @param con_handle 337 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 338 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 339 * ERROR_CODE_SUCCESS , if query is successfully registered 340 */ 341 uint8_t gatt_client_discover_secondary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 342 343 /** 344 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 345 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 346 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 347 * @param callback 348 * @param con_handle 349 * @param uuid16 350 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 351 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 352 * ERROR_CODE_SUCCESS , if query is successfully registered 353 */ 354 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 355 356 /** 357 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 358 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 359 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 360 * @param callback 361 * @param con_handle 362 * @param uuid128 363 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 364 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 365 * ERROR_CODE_SUCCESS , if query is successfully registered 366 */ 367 uint8_t gatt_client_discover_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 368 369 /** 370 * @brief Finds included services within the specified service. 371 * For each found included service a GATT_EVENT_INCLUDED_SERVICE_QUERY_RESULT event will be emitted. 372 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 373 * Information about included service type (primary/secondary) can be retrieved either by sending 374 * an ATT find information request for the returned start group handle 375 * (returning the handle and the UUID for primary or secondary service) or by comparing the service 376 * to the list of all primary services. 377 * @param callback 378 * @param con_handle 379 * @param service 380 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 381 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 382 * ERROR_CODE_SUCCESS , if query is successfully registered 383 */ 384 uint8_t gatt_client_find_included_services_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service); 385 386 /** 387 * @brief Discovers all characteristics within the specified service. 388 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will be emited. 389 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 390 * @param callback 391 * @param con_handle 392 * @param service 393 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 394 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 395 * ERROR_CODE_SUCCESS , if query is successfully registered 396 */ 397 uint8_t gatt_client_discover_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service); 398 399 /** 400 * @brief The following four functions are used to discover all characteristics within 401 * the specified service or handle range, and return those that match the given UUID. 402 * 403 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 404 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 405 * @param callback 406 * @param con_handle 407 * @param start_handle 408 * @param end_handle 409 * @param uuid16 410 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 411 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 412 * ERROR_CODE_SUCCESS , if query is successfully registered 413 */ 414 uint8_t gatt_client_discover_characteristics_for_handle_range_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t start_handle, uint16_t end_handle, uint16_t uuid16); 415 416 /** 417 * @brief The following four functions are used to discover all characteristics within the 418 * specified service or handle range, and return those that match the given UUID. 419 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 420 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 421 * @param callback 422 * @param con_handle 423 * @param start_handle 424 * @param end_handle 425 * @param uuid128 426 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 427 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 428 * ERROR_CODE_SUCCESS , if query is successfully registered 429 */ 430 uint8_t gatt_client_discover_characteristics_for_handle_range_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t start_handle, uint16_t end_handle, const uint8_t * uuid128); 431 432 /** 433 * @brief The following four functions are used to discover all characteristics within the 434 * specified service or handle range, and return those that match the given UUID. 435 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 436 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 437 * @param callback 438 * @param con_handle 439 * @param service 440 * @param uuid16 441 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 442 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 443 * ERROR_CODE_SUCCESS , if query is successfully registered 444 */ 445 uint8_t gatt_client_discover_characteristics_for_service_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service, uint16_t uuid16); 446 447 /** 448 * @brief The following four functions are used to discover all characteristics within the 449 * specified service or handle range, and return those that match the given UUID. 450 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 451 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 452 * @param callback 453 * @param con_handle 454 * @param service 455 * @param uuid128 456 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 457 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 458 * ERROR_CODE_SUCCESS , if query is successfully registered 459 */ 460 uint8_t gatt_client_discover_characteristics_for_service_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service, const uint8_t * uuid128); 461 462 /** 463 * @brief Discovers attribute handle and UUID of a characteristic descriptor within the specified characteristic. 464 * For each found descriptor a GATT_EVENT_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT event will be emitted. 465 * 466 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 467 * @param callback 468 * @param con_handle 469 * @param characteristic 470 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 471 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 472 * ERROR_CODE_SUCCESS , if query is successfully registered 473 */ 474 uint8_t gatt_client_discover_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 475 476 /** 477 * @brief Reads the characteristic value using the characteristic's value handle. 478 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 479 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 480 * @param callback 481 * @param con_handle 482 * @param characteristic 483 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 484 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 485 * ERROR_CODE_SUCCESS , if query is successfully registered 486 */ 487 uint8_t gatt_client_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 488 489 /** 490 * @brief Reads the characteristic value using the characteristic's value handle. 491 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 492 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 493 * @param callback 494 * @param con_handle 495 * @param value_handle 496 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 497 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 498 * ERROR_CODE_SUCCESS , if query is successfully registered 499 */ 500 uint8_t gatt_client_read_value_of_characteristic_using_value_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle); 501 502 /** 503 * @brief Reads the characteric value of all characteristics with the uuid. 504 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 505 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 506 * @param callback 507 * @param con_handle 508 * @param start_handle 509 * @param end_handle 510 * @param uuid16 511 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 512 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 513 * ERROR_CODE_SUCCESS , if query is successfully registered 514 */ 515 uint8_t gatt_client_read_value_of_characteristics_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t start_handle, uint16_t end_handle, uint16_t uuid16); 516 517 /** 518 * @brief Reads the characteric value of all characteristics with the uuid. 519 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 520 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 521 * @param callback 522 * @param con_handle 523 * @param start_handle 524 * @param end_handle 525 * @param uuid128 526 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 527 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 528 * ERROR_CODE_SUCCESS , if query is successfully registered 529 */ 530 uint8_t gatt_client_read_value_of_characteristics_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t start_handle, uint16_t end_handle, const uint8_t * uuid128); 531 532 /** 533 * @brief Reads the long characteristic value using the characteristic's value handle. 534 * The value will be returned in several blobs. 535 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 536 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 537 * @param callback 538 * @param con_handle 539 * @param characteristic 540 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 541 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 542 * ERROR_CODE_SUCCESS , if query is successfully registered 543 */ 544 uint8_t gatt_client_read_long_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 545 546 /** 547 * @brief Reads the long characteristic value using the characteristic's value handle. 548 * The value will be returned in several blobs. 549 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 550 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 551 * @param callback 552 * @param con_handle 553 * @param value_handle 554 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 555 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 556 * ERROR_CODE_SUCCESS , if query is successfully registered 557 */ 558 uint8_t gatt_client_read_long_value_of_characteristic_using_value_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle); 559 560 /** 561 * @brief Reads the long characteristic value using the characteristic's value handle. 562 * The value will be returned in several blobs. 563 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 564 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 565 * @param callback 566 * @param con_handle 567 * @param value_handle 568 * @param offset 569 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 570 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 571 * ERROR_CODE_SUCCESS , if query is successfully registered 572 */ 573 uint8_t gatt_client_read_long_value_of_characteristic_using_value_handle_with_offset(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle, uint16_t offset); 574 575 /* 576 * @brief Read multiple characteristic values. 577 * The all results are emitted via single GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event, 578 * followed by the GATT_EVENT_QUERY_COMPLETE event, which marks the end of read. 579 * @param callback 580 * @param con_handle 581 * @param num_value_handles 582 * @param value_handles list of handles 583 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 584 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 585 * ERROR_CODE_SUCCESS , if query is successfully registered 586 */ 587 uint8_t gatt_client_read_multiple_characteristic_values(btstack_packet_handler_t callback, hci_con_handle_t con_handle, int num_value_handles, uint16_t * value_handles); 588 589 /** 590 * @brief Writes the characteristic value using the characteristic's value handle without 591 * an acknowledgment that the write was successfully performed. 592 * @param con_handle 593 * @param value_handle 594 * @param value_length 595 * @param value is copied on success and does not need to be retained 596 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 597 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 598 * BTSTACK_ACL_BUFFERS_FULL , if L2CAP cannot send, there are no free ACL slots 599 * ERROR_CODE_SUCCESS , if query is successfully registered 600 */ 601 uint8_t gatt_client_write_value_of_characteristic_without_response(hci_con_handle_t con_handle, uint16_t value_handle, uint16_t value_length, uint8_t * value); 602 603 /** 604 * @brief Writes the authenticated characteristic value using the characteristic's value handle 605 * without an acknowledgment that the write was successfully performed. 606 * @note GATT_EVENT_QUERY_COMPLETE is emitted with ATT_ERROR_SUCCESS for success, 607 * or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored. 608 * @param callback 609 * @param con_handle 610 * @param value_handle 611 * @param message_len 612 * @param message is not copied, make sure memory is accessible until write is done 613 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 614 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 615 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 616 * ERROR_CODE_SUCCESS if query is successfully registered 617 */ 618 uint8_t gatt_client_signed_write_without_response(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle, uint16_t message_len, uint8_t * message); 619 620 /** 621 * @brief Writes the characteristic value using the characteristic's value handle. 622 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 623 * The write is successfully performed, if the event's att_status field is set to 624 * ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 625 * @param callback 626 * @param con_handle 627 * @param value_handle 628 * @param value_length 629 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 630 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 631 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 632 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 633 * ERROR_CODE_SUCCESS if query is successfully registered 634 */ 635 uint8_t gatt_client_write_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle, uint16_t value_length, uint8_t * value); 636 637 /** 638 * @brief Writes the characteristic value using the characteristic's value handle. 639 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 640 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 641 * @param callback 642 * @param con_handle 643 * @param value_handle 644 * @param value_length 645 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 646 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 647 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 648 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 649 * ERROR_CODE_SUCCESS if query is successfully registered 650 */ 651 uint8_t gatt_client_write_long_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle, uint16_t value_length, uint8_t * value); 652 653 /** 654 * @brief Writes the characteristic value using the characteristic's value handle. 655 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 656 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 657 * @param callback 658 * @param con_handle 659 * @param value_handle 660 * @param offset of value 661 * @param value_length 662 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 663 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 664 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 665 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 666 * ERROR_CODE_SUCCESS if query is successfully registered 667 */ 668 uint8_t gatt_client_write_long_value_of_characteristic_with_offset(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle, uint16_t offset, uint16_t value_length, uint8_t * value); 669 670 /** 671 * @brief Writes of the long characteristic value using the characteristic's value handle. 672 * It uses server response to validate that the write was correctly received. 673 * The GATT_EVENT_QUERY_COMPLETE EVENT marks the end of write. 674 * The write is successfully performed, if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 675 * @param callback 676 * @param con_handle 677 * @param value_handle 678 * @param value_length 679 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 680 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 681 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 682 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 683 * ERROR_CODE_SUCCESS if query is successfully registered 684 */ 685 uint8_t gatt_client_reliable_write_long_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle, uint16_t value_length, uint8_t * value); 686 687 /** 688 * @brief Reads the characteristic descriptor using its handle. 689 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 690 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 691 * @param callback 692 * @param con_handle 693 * @param descriptor 694 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 695 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 696 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 697 * ERROR_CODE_SUCCESS if query is successfully registered 698 */ 699 uint8_t gatt_client_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 700 701 /** 702 * @brief Reads the characteristic descriptor using its handle. 703 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 704 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 705 * @param callback 706 * @param con_handle 707 * @param descriptor 708 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 709 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 710 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 711 * ERROR_CODE_SUCCESS if query is successfully registered 712 */ 713 uint8_t gatt_client_read_characteristic_descriptor_using_descriptor_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle); 714 715 /** 716 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 717 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 718 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 719 * @param callback 720 * @param con_handle 721 * @param descriptor 722 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 723 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 724 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 725 * ERROR_CODE_SUCCESS if query is successfully registered 726 */ 727 uint8_t gatt_client_read_long_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 728 729 /** 730 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 731 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 732 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 733 * @param callback 734 * @param con_handle 735 * @param descriptor_handle 736 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 737 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 738 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 739 * ERROR_CODE_SUCCESS if query is successfully registered 740 */ 741 uint8_t gatt_client_read_long_characteristic_descriptor_using_descriptor_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle); 742 743 /** 744 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 745 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 746 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 747 * @param callback 748 * @param con_handle 749 * @param descriptor_handle 750 * @param offset 751 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 752 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 753 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 754 * ERROR_CODE_SUCCESS if query is successfully registered 755 */ 756 uint8_t gatt_client_read_long_characteristic_descriptor_using_descriptor_handle_with_offset(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle, uint16_t offset); 757 758 /** 759 * @brief Writes the characteristic descriptor using its handle. 760 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 761 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 762 * @param callback 763 * @param con_handle 764 * @param descriptor 765 * @param value_length 766 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 767 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 768 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 769 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 770 * ERROR_CODE_SUCCESS if query is successfully registered 771 */ 772 uint8_t gatt_client_write_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor, uint16_t value_length, uint8_t * value); 773 774 /** 775 * @brief Writes the characteristic descriptor using its handle. 776 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 777 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 778 * @param callback 779 * @param con_handle 780 * @param descriptor_handle 781 * @param value_length 782 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 783 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 784 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 785 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 786 * ERROR_CODE_SUCCESS if query is successfully registered 787 */ 788 uint8_t gatt_client_write_characteristic_descriptor_using_descriptor_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle, uint16_t value_length, uint8_t * value); 789 790 /** 791 * @brief Writes the characteristic descriptor using its handle. 792 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 793 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 794 * @param callback 795 * @param con_handle 796 * @param descriptor 797 * @param value_length 798 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 799 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 800 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 801 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 802 * ERROR_CODE_SUCCESS if query is successfully registered 803 */ 804 uint8_t gatt_client_write_long_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor, uint16_t value_length, uint8_t * value); 805 806 /** 807 * @brief Writes the characteristic descriptor using its handle. 808 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 809 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 810 * @param callback 811 * @param con_handle 812 * @param descriptor_handle 813 * @param value_length 814 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 815 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 816 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 817 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 818 * ERROR_CODE_SUCCESS if query is successfully registered 819 */ 820 uint8_t gatt_client_write_long_characteristic_descriptor_using_descriptor_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle, uint16_t value_length, uint8_t * value); 821 822 /** 823 * @brief Writes the characteristic descriptor using its handle. 824 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 825 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 826 * @param callback 827 * @param con_handle 828 * @param descriptor_handle 829 * @param offset of value 830 * @param value_length 831 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 832 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 833 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 834 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 835 * ERROR_CODE_SUCCESS if query is successfully registered 836 */ 837 uint8_t gatt_client_write_long_characteristic_descriptor_using_descriptor_handle_with_offset(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle, uint16_t offset, uint16_t value_length, uint8_t * value); 838 839 /** 840 * @brief Writes the client characteristic configuration of the specified characteristic. 841 * It is used to subscribe for notifications or indications of the characteristic value. 842 * For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION 843 * resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 844 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 845 * The write is successfully performed if the event's att_status field is set to ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 846 * @param callback 847 * @param con_handle 848 * @param characteristic 849 * @param configuration GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION, GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 850 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 851 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 852 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 853 * GATT_CLIENT_CHARACTERISTIC_NOTIFICATION_NOT_SUPPORTED if configuring notification, but characteristic has no notification property set 854 * GATT_CLIENT_CHARACTERISTIC_INDICATION_NOT_SUPPORTED if configuring indication, but characteristic has no indication property set 855 * ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if configuration is invalid 856 * ERROR_CODE_SUCCESS if query is successfully registered 857 */ 858 uint8_t gatt_client_write_client_characteristic_configuration(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic, uint16_t configuration); 859 860 /** 861 * @brief Register for notifications and indications of a characteristic enabled by 862 * the gatt_client_write_client_characteristic_configuration function. 863 * @param notification struct used to store registration 864 * @param callback 865 * @param con_handle or GATT_CLIENT_ANY_CONNECTION to receive updates from all connected devices 866 * @param characteristic or NULL to receive updates for all characteristics 867 */ 868 void gatt_client_listen_for_characteristic_value_updates(gatt_client_notification_t * notification, btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 869 870 /** 871 * @brief Stop listening to characteristic value updates registered with 872 * the gatt_client_listen_for_characteristic_value_updates function. 873 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 874 */ 875 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 876 877 /** 878 * @brief Transactional write. It can be called as many times as it is needed to write the characteristics within the same transaction. 879 * Call the gatt_client_execute_write function to commit the transaction. 880 * @param callback 881 * @param con_handle 882 * @param attribute_handle 883 * @param offset of value 884 * @param value_length 885 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 886 */ 887 uint8_t gatt_client_prepare_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t attribute_handle, uint16_t offset, uint16_t value_length, uint8_t * value); 888 889 /** 890 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 891 * @param callback 892 * @param con_handle 893 * @return status 894 */ 895 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 896 897 /** 898 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 899 * @param callback 900 * @param con_handle 901 * @return status 902 */ 903 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 904 905 /** 906 * @brief Request callback when regular gatt query can be sent 907 * @note callback might happen during call to this function 908 * @param callback_registration to point to callback function and context information 909 * @param con_handle 910 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 911 */ 912 uint8_t gatt_client_request_to_send_gatt_query(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 913 914 /** 915 * @brief Request callback when writing characteristic value without response is possible 916 * @note callback might happen during call to this function 917 * @param callback_registration to point to callback function and context information 918 * @param con_handle 919 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 920 */ 921 uint8_t gatt_client_request_to_write_without_response(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 922 923 924 // the following functions are marked as deprecated and will be removed eventually 925 /** 926 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees 927 * a single successful gatt_client_write_value_of_characteristic_without_response call. 928 * @deprecated please use gatt_client_request_to_write_without_response instead 929 * @param callback 930 * @param con_handle 931 * @return status 932 */ 933 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 934 935 936 /* API_END */ 937 938 // used by generated btstack_event.c 939 940 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t * service); 941 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 942 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 943 944 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 945 void gatt_client_att_packet_handler_fuzz(uint8_t packet_type, uint16_t handle, uint8_t *packet, uint16_t size); 946 uint8_t gatt_client_get_client(hci_con_handle_t con_handle, gatt_client_t ** gatt_client); 947 #endif 948 949 #if defined __cplusplus 950 } 951 #endif 952 953 #endif 954