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 } gatt_client_state_t; 134 135 136 typedef enum{ 137 SEND_MTU_EXCHANGE, 138 SENT_MTU_EXCHANGE, 139 MTU_EXCHANGED, 140 MTU_AUTO_EXCHANGE_DISABLED 141 } gatt_client_mtu_t; 142 143 typedef struct gatt_client{ 144 btstack_linked_item_t item; 145 // TODO: rename gatt_client_state -> state 146 gatt_client_state_t gatt_client_state; 147 148 // user callback 149 btstack_packet_handler_t callback; 150 151 // can write without response callback 152 btstack_packet_handler_t write_without_response_callback; 153 154 // can write without response requests 155 btstack_linked_list_t write_without_response_requests; 156 157 // regular gatt query requests 158 btstack_linked_list_t query_requests; 159 160 hci_con_handle_t con_handle; 161 162 uint16_t mtu; 163 gatt_client_mtu_t mtu_state; 164 165 uint16_t uuid16; 166 uint8_t uuid128[16]; 167 168 uint16_t start_group_handle; 169 uint16_t end_group_handle; 170 171 uint16_t query_start_handle; 172 uint16_t query_end_handle; 173 174 uint8_t characteristic_properties; 175 uint16_t characteristic_start_handle; 176 177 uint16_t attribute_handle; 178 uint16_t attribute_offset; 179 uint16_t attribute_length; 180 uint8_t* attribute_value; 181 182 // read multiple characteristic values 183 uint16_t read_multiple_handle_count; 184 uint16_t * read_multiple_handles; 185 186 uint16_t client_characteristic_configuration_handle; 187 uint8_t client_characteristic_configuration_value[2]; 188 189 uint8_t filter_with_uuid; 190 uint8_t send_confirmation; 191 192 int le_device_index; 193 uint8_t cmac[8]; 194 195 btstack_timer_source_t gc_timeout; 196 197 uint8_t security_counter; 198 uint8_t wait_for_authentication_complete; 199 uint8_t pending_error_code; 200 201 bool reencryption_active; 202 uint8_t reencryption_result; 203 204 gap_security_level_t security_level; 205 206 } gatt_client_t; 207 208 typedef struct gatt_client_notification { 209 btstack_linked_item_t item; 210 btstack_packet_handler_t callback; 211 hci_con_handle_t con_handle; 212 uint16_t attribute_handle; 213 } gatt_client_notification_t; 214 215 /* API_START */ 216 217 typedef struct { 218 uint16_t start_group_handle; 219 uint16_t end_group_handle; 220 uint16_t uuid16; 221 uint8_t uuid128[16]; 222 } gatt_client_service_t; 223 224 typedef struct { 225 uint16_t start_handle; 226 uint16_t value_handle; 227 uint16_t end_handle; 228 uint16_t properties; 229 uint16_t uuid16; 230 uint8_t uuid128[16]; 231 } gatt_client_characteristic_t; 232 233 typedef struct { 234 uint16_t handle; 235 uint16_t uuid16; 236 uint8_t uuid128[16]; 237 } gatt_client_characteristic_descriptor_t; 238 239 /** 240 * @brief Set up GATT client. 241 */ 242 void gatt_client_init(void); 243 244 /** 245 * @brief Set minimum required security level for GATT Client 246 * @note The Bluetooth specification makes the GATT Server responsible to check for security. 247 * This allows an attacker to spoof an existing device with a GATT Servers, but skip the authentication part. 248 * If your application is exchanging sensitive data with a remote device, you would need to manually check 249 * the security level before sending/receive such data. 250 * With level > 0, the GATT Client triggers authentication for all GATT Requests and defers any exchange 251 * until the required security level is established. 252 * gatt_client_request_can_write_without_response_event does not trigger authentication 253 * gatt_client_request_to_write_without_response does not trigger authentication 254 * @pram level, default LEVEL_0 (no encryption required) 255 */ 256 void gatt_client_set_required_security_level(gap_security_level_t level); 257 258 /** 259 * @brief MTU is available after the first query has completed. If status is equal to ERROR_CODE_SUCCESS, it returns the real value, 260 * otherwise the default value ATT_DEFAULT_MTU (see bluetooth.h). 261 * @param con_handle 262 * @param mtu 263 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 264 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 265 * GATT_CLIENT_IN_WRONG_STATE if MTU is not exchanged and MTU auto-exchange is disabled 266 * ERROR_CODE_SUCCESS if query is successfully registered 267 */ 268 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 269 270 /** 271 * @brief Sets whether a MTU Exchange Request shall be automatically send before the 272 * first attribute read request is send. Default is enabled. 273 * @param enabled 274 */ 275 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 276 277 /** 278 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU 279 * when gatt_client_mtu_enable_auto_negotiation is disabled. 280 * @param callback 281 * @param con_handle 282 */ 283 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 284 285 /** 286 * @brief Returns 1 if the GATT client is ready to receive a query. It is used with daemon. 287 * @param con_handle 288 * @return is_ready_status 0 - if no GATT client for con_handle is found, or is not ready, otherwise 1 289 */ 290 int gatt_client_is_ready(hci_con_handle_t con_handle); 291 292 /** 293 * @brief Discovers all primary services. 294 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 295 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 296 * @param callback 297 * @param con_handle 298 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 299 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 300 * ERROR_CODE_SUCCESS , if query is successfully registered 301 */ 302 uint8_t gatt_client_discover_primary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 303 304 /** 305 * @brief Discovers all secondary services. 306 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 307 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 308 * @param callback 309 * @param con_handle 310 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 311 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 312 * ERROR_CODE_SUCCESS , if query is successfully registered 313 */ 314 uint8_t gatt_client_discover_secondary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 315 316 /** 317 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 318 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 319 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 320 * @param callback 321 * @param con_handle 322 * @param uuid16 323 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 324 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 325 * ERROR_CODE_SUCCESS , if query is successfully registered 326 */ 327 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 328 329 /** 330 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 331 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 332 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 333 * @param callback 334 * @param con_handle 335 * @param uuid128 336 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 337 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 338 * ERROR_CODE_SUCCESS , if query is successfully registered 339 */ 340 uint8_t gatt_client_discover_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 341 342 /** 343 * @brief Finds included services within the specified service. 344 * For each found included service a GATT_EVENT_INCLUDED_SERVICE_QUERY_RESULT event will be emitted. 345 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 346 * Information about included service type (primary/secondary) can be retrieved either by sending 347 * an ATT find information request for the returned start group handle 348 * (returning the handle and the UUID for primary or secondary service) or by comparing the service 349 * to the list of all primary services. 350 * @param callback 351 * @param con_handle 352 * @param service 353 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 354 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 355 * ERROR_CODE_SUCCESS , if query is successfully registered 356 */ 357 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); 358 359 /** 360 * @brief Discovers all characteristics within the specified service. 361 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will be emited. 362 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 363 * @param callback 364 * @param con_handle 365 * @param service 366 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 367 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 368 * ERROR_CODE_SUCCESS , if query is successfully registered 369 */ 370 uint8_t gatt_client_discover_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service); 371 372 /** 373 * @brief The following four functions are used to discover all characteristics within 374 * the specified service or handle range, and return those that match the given UUID. 375 * 376 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 377 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 378 * @param callback 379 * @param con_handle 380 * @param start_handle 381 * @param end_handle 382 * @param uuid16 383 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 384 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 385 * ERROR_CODE_SUCCESS , if query is successfully registered 386 */ 387 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); 388 389 /** 390 * @brief The following four functions are used to discover all characteristics within the 391 * specified service or handle range, and return those that match the given UUID. 392 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 393 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 394 * @param callback 395 * @param con_handle 396 * @param start_handle 397 * @param end_handle 398 * @param uuid128 399 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 400 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 401 * ERROR_CODE_SUCCESS , if query is successfully registered 402 */ 403 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); 404 405 /** 406 * @brief The following four functions are used to discover all characteristics within the 407 * specified service or handle range, and return those that match the given UUID. 408 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 409 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 410 * @param callback 411 * @param con_handle 412 * @param service 413 * @param uuid16 414 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 415 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 416 * ERROR_CODE_SUCCESS , if query is successfully registered 417 */ 418 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); 419 420 /** 421 * @brief The following four functions are used to discover all characteristics within the 422 * specified service or handle range, and return those that match the given UUID. 423 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 424 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 425 * @param callback 426 * @param con_handle 427 * @param service 428 * @param uuid128 429 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 430 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 431 * ERROR_CODE_SUCCESS , if query is successfully registered 432 */ 433 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); 434 435 /** 436 * @brief Discovers attribute handle and UUID of a characteristic descriptor within the specified characteristic. 437 * For each found descriptor a GATT_EVENT_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT event will be emitted. 438 * 439 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 440 * @param callback 441 * @param con_handle 442 * @param characteristic 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_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 448 449 /** 450 * @brief Reads the characteristic value using the characteristic's value handle. 451 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 452 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 453 * @param callback 454 * @param con_handle 455 * @param characteristic 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_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 461 462 /** 463 * @brief Reads the characteristic value using the characteristic's value handle. 464 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 465 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 466 * @param callback 467 * @param con_handle 468 * @param value_handle 469 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 470 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 471 * ERROR_CODE_SUCCESS , if query is successfully registered 472 */ 473 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); 474 475 /** 476 * @brief Reads the characteric value of all characteristics with the uuid. 477 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 478 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 479 * @param callback 480 * @param con_handle 481 * @param start_handle 482 * @param end_handle 483 * @param uuid16 484 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 485 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 486 * ERROR_CODE_SUCCESS , if query is successfully registered 487 */ 488 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); 489 490 /** 491 * @brief Reads the characteric value of all characteristics with the uuid. 492 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 493 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 494 * @param callback 495 * @param con_handle 496 * @param start_handle 497 * @param end_handle 498 * @param uuid128 499 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 500 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 501 * ERROR_CODE_SUCCESS , if query is successfully registered 502 */ 503 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); 504 505 /** 506 * @brief Reads the long characteristic value using the characteristic's value handle. 507 * The value will be returned in several blobs. 508 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 509 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 510 * @param callback 511 * @param con_handle 512 * @param characteristic 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_long_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 518 519 /** 520 * @brief Reads the long characteristic value using the characteristic's value handle. 521 * The value will be returned in several blobs. 522 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 523 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 524 * @param callback 525 * @param con_handle 526 * @param value_handle 527 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 528 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 529 * ERROR_CODE_SUCCESS , if query is successfully registered 530 */ 531 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); 532 533 /** 534 * @brief Reads the long characteristic value using the characteristic's value handle. 535 * The value will be returned in several blobs. 536 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 537 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 538 * @param callback 539 * @param con_handle 540 * @param value_handle 541 * @param offset 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_using_value_handle_with_offset(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t value_handle, uint16_t offset); 547 548 /* 549 * @brief Read multiple characteristic values. 550 * The all results are emitted via single GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event, 551 * followed by the GATT_EVENT_QUERY_COMPLETE event, which marks the end of read. 552 * @param callback 553 * @param con_handle 554 * @param num_value_handles 555 * @param value_handles list of handles 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_multiple_characteristic_values(btstack_packet_handler_t callback, hci_con_handle_t con_handle, int num_value_handles, uint16_t * value_handles); 561 562 /** 563 * @brief Writes the characteristic value using the characteristic's value handle without 564 * an acknowledgment that the write was successfully performed. 565 * @param con_handle 566 * @param value_handle 567 * @param value_length 568 * @param value is copied on success and does not need to be retained 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 * BTSTACK_ACL_BUFFERS_FULL , if L2CAP cannot send, there are no free ACL slots 572 * ERROR_CODE_SUCCESS , if query is successfully registered 573 */ 574 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); 575 576 /** 577 * @brief Writes the authenticated characteristic value using the characteristic's value handle 578 * without an acknowledgment that the write was successfully performed. 579 * @note GATT_EVENT_QUERY_COMPLETE is emitted with ATT_ERROR_SUCCESS for success, 580 * or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored. 581 * @param callback 582 * @param con_handle 583 * @param value_handle 584 * @param message_len 585 * @param message is not copied, make sure memory is accessible until write is done 586 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 587 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 588 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 589 * ERROR_CODE_SUCCESS if query is successfully registered 590 */ 591 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); 592 593 /** 594 * @brief Writes the characteristic value using the characteristic's value handle. 595 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 596 * The write is successfully performed, if the event's att_status field is set to 597 * ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 598 * @param callback 599 * @param con_handle 600 * @param value_handle 601 * @param value_length 602 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 603 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 604 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 605 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 606 * ERROR_CODE_SUCCESS if query is successfully registered 607 */ 608 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); 609 610 /** 611 * @brief Writes the characteristic value using the characteristic's value handle. 612 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 613 * 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). 614 * @param callback 615 * @param con_handle 616 * @param value_handle 617 * @param value_length 618 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 619 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 620 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 621 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 622 * ERROR_CODE_SUCCESS if query is successfully registered 623 */ 624 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); 625 626 /** 627 * @brief Writes the characteristic value using the characteristic's value handle. 628 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 629 * 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). 630 * @param callback 631 * @param con_handle 632 * @param value_handle 633 * @param offset of value 634 * @param value_length 635 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 636 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 637 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 638 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 639 * ERROR_CODE_SUCCESS if query is successfully registered 640 */ 641 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); 642 643 /** 644 * @brief Writes of the long characteristic value using the characteristic's value handle. 645 * It uses server response to validate that the write was correctly received. 646 * The GATT_EVENT_QUERY_COMPLETE EVENT marks the end of write. 647 * 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). 648 * @param callback 649 * @param con_handle 650 * @param value_handle 651 * @param value_length 652 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 653 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 654 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 655 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 656 * ERROR_CODE_SUCCESS if query is successfully registered 657 */ 658 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); 659 660 /** 661 * @brief Reads the characteristic descriptor using its handle. 662 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 663 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 664 * @param callback 665 * @param con_handle 666 * @param descriptor 667 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 668 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 669 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 670 * ERROR_CODE_SUCCESS if query is successfully registered 671 */ 672 uint8_t gatt_client_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 673 674 /** 675 * @brief Reads the characteristic descriptor using its handle. 676 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 677 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 678 * @param callback 679 * @param con_handle 680 * @param descriptor 681 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 682 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 683 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 684 * ERROR_CODE_SUCCESS if query is successfully registered 685 */ 686 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); 687 688 /** 689 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 690 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 691 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 692 * @param callback 693 * @param con_handle 694 * @param descriptor 695 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 696 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 697 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 698 * ERROR_CODE_SUCCESS if query is successfully registered 699 */ 700 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); 701 702 /** 703 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 704 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 705 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 706 * @param callback 707 * @param con_handle 708 * @param descriptor_handle 709 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 710 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 711 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 712 * ERROR_CODE_SUCCESS if query is successfully registered 713 */ 714 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); 715 716 /** 717 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 718 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 719 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 720 * @param callback 721 * @param con_handle 722 * @param descriptor_handle 723 * @param offset 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_using_descriptor_handle_with_offset(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle, uint16_t offset); 730 731 /** 732 * @brief Writes the characteristic descriptor using its handle. 733 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 734 * 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). 735 * @param callback 736 * @param con_handle 737 * @param descriptor 738 * @param value_length 739 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 740 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 741 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 742 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 743 * ERROR_CODE_SUCCESS if query is successfully registered 744 */ 745 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); 746 747 /** 748 * @brief Writes the characteristic descriptor using its handle. 749 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 750 * 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). 751 * @param callback 752 * @param con_handle 753 * @param descriptor_handle 754 * @param value_length 755 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 756 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 757 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 758 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 759 * ERROR_CODE_SUCCESS if query is successfully registered 760 */ 761 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); 762 763 /** 764 * @brief Writes the characteristic descriptor using its handle. 765 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 766 * 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). 767 * @param callback 768 * @param con_handle 769 * @param descriptor 770 * @param value_length 771 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 772 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 773 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 774 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 775 * ERROR_CODE_SUCCESS if query is successfully registered 776 */ 777 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); 778 779 /** 780 * @brief Writes the characteristic descriptor using its handle. 781 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 782 * 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). 783 * @param callback 784 * @param con_handle 785 * @param descriptor_handle 786 * @param value_length 787 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 788 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 789 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 790 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 791 * ERROR_CODE_SUCCESS if query is successfully registered 792 */ 793 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); 794 795 /** 796 * @brief Writes the characteristic descriptor using its handle. 797 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 798 * 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). 799 * @param callback 800 * @param con_handle 801 * @param descriptor_handle 802 * @param offset of value 803 * @param value_length 804 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 805 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 806 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 807 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 808 * ERROR_CODE_SUCCESS if query is successfully registered 809 */ 810 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); 811 812 /** 813 * @brief Writes the client characteristic configuration of the specified characteristic. 814 * It is used to subscribe for notifications or indications of the characteristic value. 815 * For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION 816 * resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 817 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 818 * 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). 819 * @param callback 820 * @param con_handle 821 * @param characteristic 822 * @param configuration GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION, GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 823 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 824 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 825 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 826 * GATT_CLIENT_CHARACTERISTIC_NOTIFICATION_NOT_SUPPORTED if configuring notification, but characteristic has no notification property set 827 * GATT_CLIENT_CHARACTERISTIC_INDICATION_NOT_SUPPORTED if configuring indication, but characteristic has no indication property set 828 * ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if configuration is invalid 829 * ERROR_CODE_SUCCESS if query is successfully registered 830 */ 831 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); 832 833 /** 834 * @brief Register for notifications and indications of a characteristic enabled by 835 * the gatt_client_write_client_characteristic_configuration function. 836 * @param notification struct used to store registration 837 * @param callback 838 * @param con_handle or GATT_CLIENT_ANY_CONNECTION to receive updates from all connected devices 839 * @param characteristic or NULL to receive updates for all characteristics 840 */ 841 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); 842 843 /** 844 * @brief Stop listening to characteristic value updates registered with 845 * the gatt_client_listen_for_characteristic_value_updates function. 846 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 847 */ 848 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 849 850 /** 851 * @brief Transactional write. It can be called as many times as it is needed to write the characteristics within the same transaction. 852 * Call the gatt_client_execute_write function to commit the transaction. 853 * @param callback 854 * @param con_handle 855 * @param attribute_handle 856 * @param offset of value 857 * @param value_length 858 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 859 */ 860 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); 861 862 /** 863 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 864 * @param callback 865 * @param con_handle 866 * @return status 867 */ 868 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 869 870 /** 871 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 872 * @param callback 873 * @param con_handle 874 * @return status 875 */ 876 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 877 878 /** 879 * @brief Request callback when regular gatt query can be sent 880 * @note callback might happen during call to this function 881 * @param callback_registration to point to callback function and context information 882 * @param con_handle 883 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 884 */ 885 uint8_t gatt_client_request_to_send_gatt_query(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 886 887 /** 888 * @brief Request callback when writing characteristic value without response is possible 889 * @note callback might happen during call to this function 890 * @param callback_registration to point to callback function and context information 891 * @param con_handle 892 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 893 */ 894 uint8_t gatt_client_request_to_write_without_response(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 895 896 897 // the following functions are marked as deprecated and will be removed eventually 898 /** 899 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees 900 * a single successful gatt_client_write_value_of_characteristic_without_response call. 901 * @deprecated please use gatt_client_request_to_write_without_response instead 902 * @param callback 903 * @param con_handle 904 * @return status 905 */ 906 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 907 908 909 /* API_END */ 910 911 // used by generated btstack_event.c 912 913 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t * service); 914 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 915 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 916 917 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 918 void gatt_client_att_packet_handler_fuzz(uint8_t packet_type, uint16_t handle, uint8_t *packet, uint16_t size); 919 uint8_t gatt_client_get_client(hci_con_handle_t con_handle, gatt_client_t ** gatt_client); 920 #endif 921 922 #if defined __cplusplus 923 } 924 #endif 925 926 #endif 927