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 * GATT_EVENT_CONNECTED with status and con_handle for other API functions 272 * is emitted on connection complete. 273 * @note requires ENABLE_GATT_OVER_CLASSIC. 274 * @param addr 275 * @return status 276 */ 277 uint8_t gatt_client_classic_connect(btstack_packet_handler_t callback, bd_addr_t addr); 278 279 /** 280 * @brief Disconnect o Classic (BR/EDR) connection to a remote GATT Server 281 * @note requires ENABLE_GATT_OVER_CLASSIC 282 * @param con_handle 283 * @return status 284 */ 285 uint8_t gatt_client_classic_disconnect(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 286 287 /** 288 * @brief MTU is available after the first query has completed. If status is equal to ERROR_CODE_SUCCESS, it returns the real value, 289 * otherwise the default value ATT_DEFAULT_MTU (see bluetooth.h). 290 * @param con_handle 291 * @param mtu 292 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 293 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 294 * GATT_CLIENT_IN_WRONG_STATE if MTU is not exchanged and MTU auto-exchange is disabled 295 * ERROR_CODE_SUCCESS if query is successfully registered 296 */ 297 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 298 299 /** 300 * @brief Sets whether a MTU Exchange Request shall be automatically send before the 301 * first attribute read request is send. Default is enabled. 302 * @param enabled 303 */ 304 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 305 306 /** 307 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU 308 * when gatt_client_mtu_enable_auto_negotiation is disabled. 309 * @param callback 310 * @param con_handle 311 */ 312 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 313 314 /** 315 * @brief Returns 1 if the GATT client is ready to receive a query. It is used with daemon. 316 * @param con_handle 317 * @return is_ready_status 0 - if no GATT client for con_handle is found, or is not ready, otherwise 1 318 */ 319 int gatt_client_is_ready(hci_con_handle_t con_handle); 320 321 /** 322 * @brief Discovers all primary services. 323 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 324 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 325 * @param callback 326 * @param con_handle 327 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 328 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 329 * ERROR_CODE_SUCCESS , if query is successfully registered 330 */ 331 uint8_t gatt_client_discover_primary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 332 333 /** 334 * @brief Discovers all secondary services. 335 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 336 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 337 * @param callback 338 * @param con_handle 339 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 340 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 341 * ERROR_CODE_SUCCESS , if query is successfully registered 342 */ 343 uint8_t gatt_client_discover_secondary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 344 345 /** 346 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 347 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 348 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 349 * @param callback 350 * @param con_handle 351 * @param uuid16 352 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 353 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 354 * ERROR_CODE_SUCCESS , if query is successfully registered 355 */ 356 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 357 358 /** 359 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 360 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 361 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 362 * @param callback 363 * @param con_handle 364 * @param uuid128 365 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 366 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 367 * ERROR_CODE_SUCCESS , if query is successfully registered 368 */ 369 uint8_t gatt_client_discover_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 370 371 /** 372 * @brief Finds included services within the specified service. 373 * For each found included service a GATT_EVENT_INCLUDED_SERVICE_QUERY_RESULT event will be emitted. 374 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 375 * Information about included service type (primary/secondary) can be retrieved either by sending 376 * an ATT find information request for the returned start group handle 377 * (returning the handle and the UUID for primary or secondary service) or by comparing the service 378 * to the list of all primary services. 379 * @param callback 380 * @param con_handle 381 * @param service 382 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 383 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 384 * ERROR_CODE_SUCCESS , if query is successfully registered 385 */ 386 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); 387 388 /** 389 * @brief Discovers all characteristics within the specified service. 390 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will be emited. 391 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 392 * @param callback 393 * @param con_handle 394 * @param service 395 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 396 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 397 * ERROR_CODE_SUCCESS , if query is successfully registered 398 */ 399 uint8_t gatt_client_discover_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service); 400 401 /** 402 * @brief The following four functions are used to discover all characteristics within 403 * the specified service or handle range, and return those that match the given UUID. 404 * 405 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 406 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 407 * @param callback 408 * @param con_handle 409 * @param start_handle 410 * @param end_handle 411 * @param uuid16 412 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 413 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 414 * ERROR_CODE_SUCCESS , if query is successfully registered 415 */ 416 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); 417 418 /** 419 * @brief The following four functions are used to discover all characteristics within the 420 * specified service or handle range, and return those that match the given UUID. 421 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 422 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 423 * @param callback 424 * @param con_handle 425 * @param start_handle 426 * @param end_handle 427 * @param uuid128 428 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 429 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 430 * ERROR_CODE_SUCCESS , if query is successfully registered 431 */ 432 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); 433 434 /** 435 * @brief The following four functions are used to discover all characteristics within the 436 * specified service or handle range, and return those that match the given UUID. 437 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 438 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 439 * @param callback 440 * @param con_handle 441 * @param service 442 * @param uuid16 443 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 444 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 445 * ERROR_CODE_SUCCESS , if query is successfully registered 446 */ 447 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); 448 449 /** 450 * @brief The following four functions are used to discover all characteristics within the 451 * specified service or handle range, and return those that match the given UUID. 452 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 453 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 454 * @param callback 455 * @param con_handle 456 * @param service 457 * @param uuid128 458 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 459 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 460 * ERROR_CODE_SUCCESS , if query is successfully registered 461 */ 462 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); 463 464 /** 465 * @brief Discovers attribute handle and UUID of a characteristic descriptor within the specified characteristic. 466 * For each found descriptor a GATT_EVENT_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT event will be emitted. 467 * 468 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 469 * @param callback 470 * @param con_handle 471 * @param characteristic 472 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 473 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 474 * ERROR_CODE_SUCCESS , if query is successfully registered 475 */ 476 uint8_t gatt_client_discover_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 477 478 /** 479 * @brief Reads the characteristic value using the characteristic's value handle. 480 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 481 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 482 * @param callback 483 * @param con_handle 484 * @param characteristic 485 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 486 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 487 * ERROR_CODE_SUCCESS , if query is successfully registered 488 */ 489 uint8_t gatt_client_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 490 491 /** 492 * @brief Reads the characteristic value using the characteristic's value handle. 493 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 494 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 495 * @param callback 496 * @param con_handle 497 * @param value_handle 498 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 499 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 500 * ERROR_CODE_SUCCESS , if query is successfully registered 501 */ 502 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); 503 504 /** 505 * @brief Reads the characteric value of all characteristics with the uuid. 506 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 507 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 508 * @param callback 509 * @param con_handle 510 * @param start_handle 511 * @param end_handle 512 * @param uuid16 513 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 514 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 515 * ERROR_CODE_SUCCESS , if query is successfully registered 516 */ 517 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); 518 519 /** 520 * @brief Reads the characteric value of all characteristics with the uuid. 521 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 522 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 523 * @param callback 524 * @param con_handle 525 * @param start_handle 526 * @param end_handle 527 * @param uuid128 528 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 529 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 530 * ERROR_CODE_SUCCESS , if query is successfully registered 531 */ 532 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); 533 534 /** 535 * @brief Reads the long characteristic value using the characteristic's value handle. 536 * The value will be returned in several blobs. 537 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 538 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 539 * @param callback 540 * @param con_handle 541 * @param characteristic 542 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 543 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 544 * ERROR_CODE_SUCCESS , if query is successfully registered 545 */ 546 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); 547 548 /** 549 * @brief Reads the long characteristic value using the characteristic's value handle. 550 * The value will be returned in several blobs. 551 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 552 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 553 * @param callback 554 * @param con_handle 555 * @param value_handle 556 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 557 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 558 * ERROR_CODE_SUCCESS , if query is successfully registered 559 */ 560 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); 561 562 /** 563 * @brief Reads the long characteristic value using the characteristic's value handle. 564 * The value will be returned in several blobs. 565 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 566 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 567 * @param callback 568 * @param con_handle 569 * @param value_handle 570 * @param offset 571 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 572 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 573 * ERROR_CODE_SUCCESS , if query is successfully registered 574 */ 575 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); 576 577 /* 578 * @brief Read multiple characteristic values. 579 * The all results are emitted via single GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event, 580 * followed by the GATT_EVENT_QUERY_COMPLETE event, which marks the end of read. 581 * @param callback 582 * @param con_handle 583 * @param num_value_handles 584 * @param value_handles list of handles 585 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 586 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 587 * ERROR_CODE_SUCCESS , if query is successfully registered 588 */ 589 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); 590 591 /** 592 * @brief Writes the characteristic value using the characteristic's value handle without 593 * an acknowledgment that the write was successfully performed. 594 * @param con_handle 595 * @param value_handle 596 * @param value_length 597 * @param value is copied on success and does not need to be retained 598 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 599 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 600 * BTSTACK_ACL_BUFFERS_FULL , if L2CAP cannot send, there are no free ACL slots 601 * ERROR_CODE_SUCCESS , if query is successfully registered 602 */ 603 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); 604 605 /** 606 * @brief Writes the authenticated characteristic value using the characteristic's value handle 607 * without an acknowledgment that the write was successfully performed. 608 * @note GATT_EVENT_QUERY_COMPLETE is emitted with ATT_ERROR_SUCCESS for success, 609 * or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored. 610 * @param callback 611 * @param con_handle 612 * @param value_handle 613 * @param message_len 614 * @param message is not copied, make sure memory is accessible until write is done 615 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 616 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 617 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 618 * ERROR_CODE_SUCCESS if query is successfully registered 619 */ 620 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); 621 622 /** 623 * @brief Writes the characteristic value using the characteristic's value handle. 624 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 625 * The write is successfully performed, if the event's att_status field is set to 626 * ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 627 * @param callback 628 * @param con_handle 629 * @param value_handle 630 * @param value_length 631 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 632 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 633 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 634 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 635 * ERROR_CODE_SUCCESS if query is successfully registered 636 */ 637 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); 638 639 /** 640 * @brief Writes the characteristic value using the characteristic's value handle. 641 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 642 * 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). 643 * @param callback 644 * @param con_handle 645 * @param value_handle 646 * @param value_length 647 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 648 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 649 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 650 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 651 * ERROR_CODE_SUCCESS if query is successfully registered 652 */ 653 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); 654 655 /** 656 * @brief Writes the characteristic value using the characteristic's value handle. 657 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 658 * 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). 659 * @param callback 660 * @param con_handle 661 * @param value_handle 662 * @param offset of value 663 * @param value_length 664 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 665 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 666 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 667 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 668 * ERROR_CODE_SUCCESS if query is successfully registered 669 */ 670 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); 671 672 /** 673 * @brief Writes of the long characteristic value using the characteristic's value handle. 674 * It uses server response to validate that the write was correctly received. 675 * The GATT_EVENT_QUERY_COMPLETE EVENT marks the end of write. 676 * 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). 677 * @param callback 678 * @param con_handle 679 * @param value_handle 680 * @param value_length 681 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 682 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 683 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 684 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 685 * ERROR_CODE_SUCCESS if query is successfully registered 686 */ 687 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); 688 689 /** 690 * @brief Reads the characteristic descriptor using its handle. 691 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 692 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 693 * @param callback 694 * @param con_handle 695 * @param descriptor 696 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 697 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 698 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 699 * ERROR_CODE_SUCCESS if query is successfully registered 700 */ 701 uint8_t gatt_client_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 702 703 /** 704 * @brief Reads the characteristic descriptor using its handle. 705 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 706 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 707 * @param callback 708 * @param con_handle 709 * @param descriptor 710 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 711 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 712 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 713 * ERROR_CODE_SUCCESS if query is successfully registered 714 */ 715 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); 716 717 /** 718 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 719 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 720 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 721 * @param callback 722 * @param con_handle 723 * @param descriptor 724 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 725 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 726 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 727 * ERROR_CODE_SUCCESS if query is successfully registered 728 */ 729 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); 730 731 /** 732 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 733 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 734 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 735 * @param callback 736 * @param con_handle 737 * @param descriptor_handle 738 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 739 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 740 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 741 * ERROR_CODE_SUCCESS if query is successfully registered 742 */ 743 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); 744 745 /** 746 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 747 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 748 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 749 * @param callback 750 * @param con_handle 751 * @param descriptor_handle 752 * @param offset 753 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 754 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 755 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 756 * ERROR_CODE_SUCCESS if query is successfully registered 757 */ 758 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); 759 760 /** 761 * @brief Writes the characteristic descriptor using its handle. 762 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 763 * 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). 764 * @param callback 765 * @param con_handle 766 * @param descriptor 767 * @param value_length 768 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 769 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 770 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 771 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 772 * ERROR_CODE_SUCCESS if query is successfully registered 773 */ 774 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); 775 776 /** 777 * @brief Writes the characteristic descriptor using its handle. 778 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 779 * 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). 780 * @param callback 781 * @param con_handle 782 * @param descriptor_handle 783 * @param value_length 784 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 785 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 786 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 787 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 788 * ERROR_CODE_SUCCESS if query is successfully registered 789 */ 790 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); 791 792 /** 793 * @brief Writes the characteristic descriptor using its handle. 794 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 795 * 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). 796 * @param callback 797 * @param con_handle 798 * @param descriptor 799 * @param value_length 800 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 801 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 802 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 803 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 804 * ERROR_CODE_SUCCESS if query is successfully registered 805 */ 806 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); 807 808 /** 809 * @brief Writes the characteristic descriptor using its handle. 810 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 811 * 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). 812 * @param callback 813 * @param con_handle 814 * @param descriptor_handle 815 * @param value_length 816 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 817 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 818 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 819 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 820 * ERROR_CODE_SUCCESS if query is successfully registered 821 */ 822 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); 823 824 /** 825 * @brief Writes the characteristic descriptor using its handle. 826 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 827 * 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). 828 * @param callback 829 * @param con_handle 830 * @param descriptor_handle 831 * @param offset of value 832 * @param value_length 833 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 834 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 835 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 836 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 837 * ERROR_CODE_SUCCESS if query is successfully registered 838 */ 839 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); 840 841 /** 842 * @brief Writes the client characteristic configuration of the specified characteristic. 843 * It is used to subscribe for notifications or indications of the characteristic value. 844 * For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION 845 * resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 846 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 847 * 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). 848 * @param callback 849 * @param con_handle 850 * @param characteristic 851 * @param configuration GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION, GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 852 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 853 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 854 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 855 * GATT_CLIENT_CHARACTERISTIC_NOTIFICATION_NOT_SUPPORTED if configuring notification, but characteristic has no notification property set 856 * GATT_CLIENT_CHARACTERISTIC_INDICATION_NOT_SUPPORTED if configuring indication, but characteristic has no indication property set 857 * ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if configuration is invalid 858 * ERROR_CODE_SUCCESS if query is successfully registered 859 */ 860 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); 861 862 /** 863 * @brief Register for notifications and indications of a characteristic enabled by 864 * the gatt_client_write_client_characteristic_configuration function. 865 * @param notification struct used to store registration 866 * @param callback 867 * @param con_handle or GATT_CLIENT_ANY_CONNECTION to receive updates from all connected devices 868 * @param characteristic or NULL to receive updates for all characteristics 869 */ 870 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); 871 872 /** 873 * @brief Stop listening to characteristic value updates registered with 874 * the gatt_client_listen_for_characteristic_value_updates function. 875 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 876 */ 877 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 878 879 /** 880 * @brief Transactional write. It can be called as many times as it is needed to write the characteristics within the same transaction. 881 * Call the gatt_client_execute_write function to commit the transaction. 882 * @param callback 883 * @param con_handle 884 * @param attribute_handle 885 * @param offset of value 886 * @param value_length 887 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 888 */ 889 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); 890 891 /** 892 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 893 * @param callback 894 * @param con_handle 895 * @return status 896 */ 897 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 898 899 /** 900 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 901 * @param callback 902 * @param con_handle 903 * @return status 904 */ 905 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 906 907 /** 908 * @brief Request callback when regular gatt query can be sent 909 * @note callback might happen during call to this function 910 * @param callback_registration to point to callback function and context information 911 * @param con_handle 912 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 913 */ 914 uint8_t gatt_client_request_to_send_gatt_query(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 915 916 /** 917 * @brief Request callback when writing characteristic value without response is possible 918 * @note callback might happen during call to this function 919 * @param callback_registration to point to callback function and context information 920 * @param con_handle 921 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 922 */ 923 uint8_t gatt_client_request_to_write_without_response(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 924 925 926 // the following functions are marked as deprecated and will be removed eventually 927 /** 928 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees 929 * a single successful gatt_client_write_value_of_characteristic_without_response call. 930 * @deprecated please use gatt_client_request_to_write_without_response instead 931 * @param callback 932 * @param con_handle 933 * @return status 934 */ 935 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 936 937 938 /* API_END */ 939 940 // used by generated btstack_event.c 941 942 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t * service); 943 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 944 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 945 946 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 947 void gatt_client_att_packet_handler_fuzz(uint8_t packet_type, uint16_t handle, uint8_t *packet, uint16_t size); 948 uint8_t gatt_client_get_client(hci_con_handle_t con_handle, gatt_client_t ** gatt_client); 949 #endif 950 951 #if defined __cplusplus 952 } 953 #endif 954 955 #endif 956