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 // spec defines 100 ms, PTS might indicate an error if we sent after 100 ms 49 #define GATT_CLIENT_COLLISION_BACKOFF_MS 150 50 #if defined __cplusplus 51 extern "C" { 52 #endif 53 54 typedef enum { 55 P_READY, 56 P_W2_EMIT_QUERY_COMPLETE_EVENT, 57 P_W2_SEND_SERVICE_QUERY, 58 P_W4_SERVICE_QUERY_RESULT, 59 P_W2_SEND_SERVICE_WITH_UUID_QUERY, 60 P_W4_SERVICE_WITH_UUID_RESULT, 61 62 P_W2_SEND_ALL_CHARACTERISTICS_OF_SERVICE_QUERY, 63 P_W4_ALL_CHARACTERISTICS_OF_SERVICE_QUERY_RESULT, 64 P_W2_SEND_CHARACTERISTIC_WITH_UUID_QUERY, 65 P_W4_CHARACTERISTIC_WITH_UUID_QUERY_RESULT, 66 67 P_W2_SEND_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY, 68 P_W4_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT, 69 70 P_W2_SEND_INCLUDED_SERVICE_QUERY, 71 P_W4_INCLUDED_SERVICE_QUERY_RESULT, 72 P_W2_SEND_INCLUDED_SERVICE_WITH_UUID_QUERY, 73 P_W4_INCLUDED_SERVICE_UUID_WITH_QUERY_RESULT, 74 75 P_W2_SEND_READ_CHARACTERISTIC_VALUE_QUERY, 76 P_W4_READ_CHARACTERISTIC_VALUE_RESULT, 77 78 P_W2_SEND_READ_BLOB_QUERY, 79 P_W4_READ_BLOB_RESULT, 80 81 P_W2_SEND_READ_BY_TYPE_REQUEST, 82 P_W4_READ_BY_TYPE_RESPONSE, 83 84 P_W2_SEND_READ_MULTIPLE_REQUEST, 85 P_W4_READ_MULTIPLE_RESPONSE, 86 87 P_W2_SEND_READ_MULTIPLE_VARIABLE_REQUEST, 88 P_W4_READ_MULTIPLE_VARIABLE_RESPONSE, 89 90 P_W2_SEND_WRITE_CHARACTERISTIC_VALUE, 91 P_W4_WRITE_CHARACTERISTIC_VALUE_RESULT, 92 93 P_W2_PREPARE_WRITE, 94 P_W4_PREPARE_WRITE_RESULT, 95 P_W2_PREPARE_RELIABLE_WRITE, 96 P_W4_PREPARE_RELIABLE_WRITE_RESULT, 97 98 P_W2_EXECUTE_PREPARED_WRITE, 99 P_W4_EXECUTE_PREPARED_WRITE_RESULT, 100 P_W2_CANCEL_PREPARED_WRITE, 101 P_W4_CANCEL_PREPARED_WRITE_RESULT, 102 P_W2_CANCEL_PREPARED_WRITE_DATA_MISMATCH, 103 P_W4_CANCEL_PREPARED_WRITE_DATA_MISMATCH_RESULT, 104 105 #ifdef ENABLE_GATT_FIND_INFORMATION_FOR_CCC_DISCOVERY 106 P_W2_SEND_FIND_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 107 P_W4_FIND_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 108 #else 109 P_W2_SEND_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 110 P_W4_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 111 #endif 112 P_W2_WRITE_CLIENT_CHARACTERISTIC_CONFIGURATION, 113 P_W4_CLIENT_CHARACTERISTIC_CONFIGURATION_RESULT, 114 115 P_W2_SEND_READ_CHARACTERISTIC_DESCRIPTOR_QUERY, 116 P_W4_READ_CHARACTERISTIC_DESCRIPTOR_RESULT, 117 118 P_W2_SEND_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_QUERY, 119 P_W4_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_RESULT, 120 121 P_W2_SEND_WRITE_CHARACTERISTIC_DESCRIPTOR, 122 P_W4_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 123 124 // all long writes use this 125 P_W2_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR, 126 P_W4_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 127 P_W2_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR, 128 P_W4_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 129 130 // gatt reliable write API use this (manual version of the above) 131 P_W2_PREPARE_WRITE_SINGLE, 132 P_W4_PREPARE_WRITE_SINGLE_RESULT, 133 134 P_W4_IDENTITY_RESOLVING, 135 P_W4_CMAC_READY, 136 P_W4_CMAC_RESULT, 137 P_W2_SEND_SIGNED_WRITE, 138 P_W4_SEND_SIGNED_WRITE_DONE, 139 140 P_W2_SDP_QUERY, 141 P_W4_SDP_QUERY, 142 P_W2_L2CAP_CONNECT, 143 P_W4_L2CAP_CONNECTION, 144 P_W2_EMIT_CONNECTED, 145 P_L2CAP_CLOSED, 146 } gatt_client_state_t; 147 148 149 typedef enum{ 150 SEND_MTU_EXCHANGE, 151 SENT_MTU_EXCHANGE, 152 MTU_EXCHANGED, 153 MTU_AUTO_EXCHANGE_DISABLED 154 } gatt_client_mtu_t; 155 156 #ifdef ENABLE_GATT_OVER_EATT 157 typedef enum { 158 GATT_CLIENT_EATT_IDLE, 159 GATT_CLIENT_EATT_DISCOVER_GATT_SERVICE_W2_SEND, 160 GATT_CLIENT_EATT_DISCOVER_GATT_SERVICE_W4_DONE, 161 GATT_CLIENT_EATT_READ_SERVER_SUPPORTED_FEATURES_W2_SEND, 162 GATT_CLIENT_EATT_READ_SERVER_SUPPORTED_FEATURES_W4_DONE, 163 GATT_CLIENT_EATT_FIND_CLIENT_SUPPORTED_FEATURES_W2_SEND, 164 GATT_CLIENT_EATT_FIND_CLIENT_SUPPORTED_FEATURES_W4_DONE, 165 GATT_CLIENT_EATT_WRITE_ClIENT_SUPPORTED_FEATURES_W2_SEND, 166 GATT_CLIENT_EATT_WRITE_ClIENT_SUPPORTED_FEATURES_W4_DONE, 167 GATT_CLIENT_EATT_L2CAP_SETUP, 168 GATT_CLIENT_EATT_READY, 169 } gatt_client_eatt_state_t; 170 #endif 171 172 typedef struct gatt_client{ 173 btstack_linked_item_t item; 174 175 gatt_client_state_t state; 176 177 // user callback 178 btstack_packet_handler_t callback; 179 180 // can write without response callback 181 btstack_packet_handler_t write_without_response_callback; 182 183 // can write without response requests 184 btstack_linked_list_t write_without_response_requests; 185 186 // regular gatt query requests 187 btstack_linked_list_t query_requests; 188 189 hci_con_handle_t con_handle; 190 191 att_bearer_type_t bearer_type; 192 193 #if defined(ENABLE_GATT_OVER_CLASSIC) || defined(ENABLE_GATT_OVER_EATT) 194 uint16_t l2cap_cid; 195 bd_addr_t addr; 196 #endif 197 198 #ifdef ENABLE_GATT_OVER_CLASSIC 199 uint16_t l2cap_psm; 200 btstack_context_callback_registration_t callback_request; 201 #endif 202 203 #ifdef ENABLE_GATT_OVER_EATT 204 gatt_client_eatt_state_t eatt_state; 205 btstack_linked_list_t eatt_clients; 206 uint8_t * eatt_storage_buffer; 207 uint16_t eatt_storage_size; 208 uint8_t eatt_num_clients; 209 uint8_t gatt_server_supported_features; 210 uint16_t gatt_service_start_group_handle; 211 uint16_t gatt_service_end_group_handle; 212 uint16_t gatt_client_supported_features_handle; 213 #endif 214 215 uint16_t mtu; 216 gatt_client_mtu_t mtu_state; 217 218 uint16_t uuid16; 219 uint8_t uuid128[16]; 220 221 uint16_t start_group_handle; 222 uint16_t end_group_handle; 223 224 uint16_t query_start_handle; 225 uint16_t query_end_handle; 226 227 uint8_t characteristic_properties; 228 uint16_t characteristic_start_handle; 229 230 uint16_t attribute_handle; 231 uint16_t attribute_offset; 232 uint16_t attribute_length; 233 uint8_t* attribute_value; 234 235 // read multiple characteristic values 236 uint16_t read_multiple_handle_count; 237 uint16_t * read_multiple_handles; 238 239 uint16_t client_characteristic_configuration_handle; 240 uint8_t client_characteristic_configuration_value[2]; 241 242 bool filter_with_uuid; 243 bool send_confirmation; 244 245 int le_device_index; 246 uint8_t cmac[8]; 247 248 btstack_timer_source_t gc_timeout; 249 250 uint8_t security_counter; 251 bool wait_for_authentication_complete; 252 uint8_t pending_error_code; 253 254 bool reencryption_active; 255 uint8_t reencryption_result; 256 257 gap_security_level_t security_level; 258 259 } gatt_client_t; 260 261 typedef struct gatt_client_notification { 262 btstack_linked_item_t item; 263 btstack_packet_handler_t callback; 264 hci_con_handle_t con_handle; 265 uint16_t attribute_handle; 266 } gatt_client_notification_t; 267 268 /* API_START */ 269 270 typedef struct { 271 uint16_t start_group_handle; 272 uint16_t end_group_handle; 273 uint16_t uuid16; 274 uint8_t uuid128[16]; 275 } gatt_client_service_t; 276 277 typedef struct { 278 uint16_t start_handle; 279 uint16_t value_handle; 280 uint16_t end_handle; 281 uint16_t properties; 282 uint16_t uuid16; 283 uint8_t uuid128[16]; 284 } gatt_client_characteristic_t; 285 286 typedef struct { 287 uint16_t handle; 288 uint16_t uuid16; 289 uint8_t uuid128[16]; 290 } gatt_client_characteristic_descriptor_t; 291 292 /** 293 * @brief Set up GATT client. 294 */ 295 void gatt_client_init(void); 296 297 /** 298 * @brief Set minimum required security level for GATT Client 299 * @note The Bluetooth specification makes the GATT Server responsible to check for security. 300 * This allows an attacker to spoof an existing device with a GATT Servers, but skip the authentication part. 301 * If your application is exchanging sensitive data with a remote device, you would need to manually check 302 * the security level before sending/receive such data. 303 * With level > 0, the GATT Client triggers authentication for all GATT Requests and defers any exchange 304 * until the required security level is established. 305 * gatt_client_request_can_write_without_response_event does not trigger authentication 306 * gatt_client_request_to_write_without_response does not trigger authentication 307 * @pram level, default LEVEL_0 (no encryption required) 308 */ 309 void gatt_client_set_required_security_level(gap_security_level_t level); 310 311 /** 312 * @brief Connect to remote GATT Server over Classic (BR/EDR) Connection 313 * GATT_EVENT_CONNECTED with status and con_handle for other API functions 314 * is emitted on connection complete. 315 * @note requires ENABLE_GATT_OVER_CLASSIC. 316 * @param addr 317 * @return status 318 */ 319 uint8_t gatt_client_classic_connect(btstack_packet_handler_t callback, bd_addr_t addr); 320 321 /** 322 * @brief Disconnect o Classic (BR/EDR) connection to a remote GATT Server 323 * @note requires ENABLE_GATT_OVER_CLASSIC 324 * @param con_handle 325 * @return status 326 */ 327 uint8_t gatt_client_classic_disconnect(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 328 329 /** 330 * @brief Setup Enhanced LE Bearer with up to 5 channels on existing LE connection 331 * @param callback for GATT_EVENT_CONNECTED and GATT_EVENT_DISCONNECTED events 332 * @param con_handle 333 * @param num_channels 334 * @param storage_buffer for L2CAP connection 335 * @param storage_size - each channel requires (2 * ATT MTU) + 10 bytes 336 * @return 337 */ 338 uint8_t gatt_client_le_enhanced_connect(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint8_t num_channels, uint8_t * storage_buffer, uint16_t storage_size); 339 340 /** 341 * @brief MTU is available after the first query has completed. If status is equal to ERROR_CODE_SUCCESS, it returns the real value, 342 * otherwise the default value ATT_DEFAULT_MTU (see bluetooth.h). 343 * @param con_handle 344 * @param mtu 345 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 346 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 347 * GATT_CLIENT_IN_WRONG_STATE if MTU is not exchanged and MTU auto-exchange is disabled 348 * ERROR_CODE_SUCCESS if query is successfully registered 349 */ 350 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 351 352 /** 353 * @brief Sets whether a MTU Exchange Request shall be automatically send before the 354 * first attribute read request is send. Default is enabled. 355 * @param enabled 356 */ 357 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 358 359 /** 360 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU 361 * when gatt_client_mtu_enable_auto_negotiation is disabled. 362 * @param callback 363 * @param con_handle 364 */ 365 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 366 367 /** 368 * @brief Returns 1 if the GATT client is ready to receive a query. It is used with daemon. 369 * @param con_handle 370 * @return is_ready_status 0 - if no GATT client for con_handle is found, or is not ready, otherwise 1 371 */ 372 int gatt_client_is_ready(hci_con_handle_t con_handle); 373 374 /** 375 * @brief Discovers all primary services. 376 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 377 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 378 * @param callback 379 * @param con_handle 380 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 381 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 382 * ERROR_CODE_SUCCESS , if query is successfully registered 383 */ 384 uint8_t gatt_client_discover_primary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 385 386 /** 387 * @brief Discovers all secondary services. 388 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 389 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 390 * @param callback 391 * @param con_handle 392 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 393 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 394 * ERROR_CODE_SUCCESS , if query is successfully registered 395 */ 396 uint8_t gatt_client_discover_secondary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 397 398 /** 399 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 400 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 401 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 402 * @param callback 403 * @param con_handle 404 * @param uuid16 405 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 406 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 407 * ERROR_CODE_SUCCESS , if query is successfully registered 408 */ 409 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 410 411 /** 412 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 413 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 414 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 415 * @param callback 416 * @param con_handle 417 * @param uuid128 418 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 419 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 420 * ERROR_CODE_SUCCESS , if query is successfully registered 421 */ 422 uint8_t gatt_client_discover_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 423 424 /** 425 * @brief Finds included services within the specified service. 426 * For each found included service a GATT_EVENT_INCLUDED_SERVICE_QUERY_RESULT event will be emitted. 427 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 428 * Information about included service type (primary/secondary) can be retrieved either by sending 429 * an ATT find information request for the returned start group handle 430 * (returning the handle and the UUID for primary or secondary service) or by comparing the service 431 * to the list of all primary services. 432 * @param callback 433 * @param con_handle 434 * @param service 435 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 436 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 437 * ERROR_CODE_SUCCESS , if query is successfully registered 438 */ 439 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); 440 441 /** 442 * @brief Discovers all characteristics within the specified service. 443 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will be emited. 444 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 445 * @param callback 446 * @param con_handle 447 * @param service 448 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 449 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 450 * ERROR_CODE_SUCCESS , if query is successfully registered 451 */ 452 uint8_t gatt_client_discover_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service); 453 454 /** 455 * @brief The following four functions are used to discover all characteristics within 456 * the specified service or handle range, and return those that match the given UUID. 457 * 458 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 459 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 460 * @param callback 461 * @param con_handle 462 * @param start_handle 463 * @param end_handle 464 * @param uuid16 465 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 466 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 467 * ERROR_CODE_SUCCESS , if query is successfully registered 468 */ 469 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); 470 471 /** 472 * @brief The following four functions are used to discover all characteristics within the 473 * specified service or handle range, and return those that match the given UUID. 474 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 475 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 476 * @param callback 477 * @param con_handle 478 * @param start_handle 479 * @param end_handle 480 * @param uuid128 481 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 482 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 483 * ERROR_CODE_SUCCESS , if query is successfully registered 484 */ 485 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); 486 487 /** 488 * @brief The following four functions are used to discover all characteristics within the 489 * specified service or handle range, and return those that match the given UUID. 490 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 491 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 492 * @param callback 493 * @param con_handle 494 * @param service 495 * @param uuid16 496 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 497 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 498 * ERROR_CODE_SUCCESS , if query is successfully registered 499 */ 500 uint8_t gatt_client_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); 501 502 /** 503 * @brief The following four functions are used to discover all characteristics within the 504 * specified service or handle range, and return those that match the given UUID. 505 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 506 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 507 * @param callback 508 * @param con_handle 509 * @param service 510 * @param uuid128 511 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 512 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 513 * ERROR_CODE_SUCCESS , if query is successfully registered 514 */ 515 uint8_t gatt_client_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); 516 517 /** 518 * @brief Discovers attribute handle and UUID of a characteristic descriptor within the specified characteristic. 519 * For each found descriptor a GATT_EVENT_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT event will be emitted. 520 * 521 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 522 * @param callback 523 * @param con_handle 524 * @param characteristic 525 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 526 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 527 * ERROR_CODE_SUCCESS , if query is successfully registered 528 */ 529 uint8_t gatt_client_discover_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 530 531 /** 532 * @brief Reads the characteristic value using the characteristic's value handle. 533 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 534 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 535 * @param callback 536 * @param con_handle 537 * @param characteristic 538 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 539 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 540 * ERROR_CODE_SUCCESS , if query is successfully registered 541 */ 542 uint8_t gatt_client_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 543 544 /** 545 * @brief Reads the characteristic value using the characteristic's value handle. 546 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 547 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 548 * @param callback 549 * @param con_handle 550 * @param value_handle 551 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 552 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 553 * ERROR_CODE_SUCCESS , if query is successfully registered 554 */ 555 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); 556 557 /** 558 * @brief Reads the characteric value of all characteristics with the uuid. 559 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 560 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 561 * @param callback 562 * @param con_handle 563 * @param start_handle 564 * @param end_handle 565 * @param uuid16 566 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 567 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 568 * ERROR_CODE_SUCCESS , if query is successfully registered 569 */ 570 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); 571 572 /** 573 * @brief Reads the characteric value of all characteristics with the uuid. 574 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 575 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 576 * @param callback 577 * @param con_handle 578 * @param start_handle 579 * @param end_handle 580 * @param uuid128 581 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 582 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 583 * ERROR_CODE_SUCCESS , if query is successfully registered 584 */ 585 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); 586 587 /** 588 * @brief Reads the long characteristic value using the characteristic's value handle. 589 * The value will be returned in several blobs. 590 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 591 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 592 * @param callback 593 * @param con_handle 594 * @param characteristic 595 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 596 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 597 * ERROR_CODE_SUCCESS , if query is successfully registered 598 */ 599 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); 600 601 /** 602 * @brief Reads the long characteristic value using the characteristic's value handle. 603 * The value will be returned in several blobs. 604 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 605 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 606 * @param callback 607 * @param con_handle 608 * @param value_handle 609 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 610 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 611 * ERROR_CODE_SUCCESS , if query is successfully registered 612 */ 613 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); 614 615 /** 616 * @brief Reads the long characteristic value using the characteristic's value handle. 617 * The value will be returned in several blobs. 618 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 619 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 620 * @param callback 621 * @param con_handle 622 * @param value_handle 623 * @param offset 624 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 625 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 626 * ERROR_CODE_SUCCESS , if query is successfully registered 627 */ 628 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); 629 630 /* 631 * @brief Read multiple characteristic values. 632 * The all results are emitted via single GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event, 633 * followed by the GATT_EVENT_QUERY_COMPLETE event, which marks the end of read. 634 * @param callback 635 * @param con_handle 636 * @param num_value_handles 637 * @param value_handles list of handles 638 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 639 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 640 * ERROR_CODE_SUCCESS , if query is successfully registered 641 */ 642 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); 643 644 /* 645 * @brief Read multiple varaible characteristic values. Only supported over LE Enhanced Bearer 646 * The all results are emitted via single GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event, 647 * followed by the GATT_EVENT_QUERY_COMPLETE event, which marks the end of read. 648 * @param callback 649 * @param con_handle 650 * @param num_value_handles 651 * @param value_handles list of handles 652 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 653 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 654 * ERROR_CODE_SUCCESS , if query is successfully registered 655 */ 656 uint8_t gatt_client_read_multiple_variable_characteristic_values(btstack_packet_handler_t callback, hci_con_handle_t con_handle, int num_value_handles, uint16_t * value_handles); 657 658 /** 659 * @brief Writes the characteristic value using the characteristic's value handle without 660 * an acknowledgment that the write was successfully performed. 661 * @param con_handle 662 * @param value_handle 663 * @param value_length 664 * @param value is copied on success and does not need to be retained 665 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 666 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 667 * BTSTACK_ACL_BUFFERS_FULL , if L2CAP cannot send, there are no free ACL slots 668 * ERROR_CODE_SUCCESS , if query is successfully registered 669 */ 670 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); 671 672 /** 673 * @brief Writes the authenticated characteristic value using the characteristic's value handle 674 * without an acknowledgment that the write was successfully performed. 675 * @note GATT_EVENT_QUERY_COMPLETE is emitted with ATT_ERROR_SUCCESS for success, 676 * or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored. 677 * @param callback 678 * @param con_handle 679 * @param value_handle 680 * @param message_len 681 * @param message is not copied, make sure memory is accessible until write is done 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_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); 688 689 /** 690 * @brief Writes the characteristic value using the characteristic's value handle. 691 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 692 * The write is successfully performed, if the event's att_status field is set to 693 * ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 694 * @param callback 695 * @param con_handle 696 * @param value_handle 697 * @param value_length 698 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 699 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 700 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 701 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 702 * ERROR_CODE_SUCCESS if query is successfully registered 703 */ 704 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); 705 706 /** 707 * @brief Writes the characteristic value using the characteristic's value handle. 708 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 709 * 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). 710 * @param callback 711 * @param con_handle 712 * @param value_handle 713 * @param value_length 714 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 715 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 716 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 717 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 718 * ERROR_CODE_SUCCESS if query is successfully registered 719 */ 720 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); 721 722 /** 723 * @brief Writes the characteristic value using the characteristic's value handle. 724 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 725 * 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). 726 * @param callback 727 * @param con_handle 728 * @param value_handle 729 * @param offset of value 730 * @param value_length 731 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 732 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 733 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 734 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 735 * ERROR_CODE_SUCCESS if query is successfully registered 736 */ 737 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); 738 739 /** 740 * @brief Writes of the long characteristic value using the characteristic's value handle. 741 * It uses server response to validate that the write was correctly received. 742 * The GATT_EVENT_QUERY_COMPLETE EVENT marks the end of write. 743 * 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). 744 * @param callback 745 * @param con_handle 746 * @param value_handle 747 * @param value_length 748 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 749 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 750 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 751 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 752 * ERROR_CODE_SUCCESS if query is successfully registered 753 */ 754 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); 755 756 /** 757 * @brief Reads the characteristic descriptor using its handle. 758 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 759 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 760 * @param callback 761 * @param con_handle 762 * @param descriptor 763 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 764 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 765 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 766 * ERROR_CODE_SUCCESS if query is successfully registered 767 */ 768 uint8_t gatt_client_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 769 770 /** 771 * @brief Reads the characteristic descriptor using its handle. 772 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 773 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 774 * @param callback 775 * @param con_handle 776 * @param descriptor 777 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 778 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 779 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 780 * ERROR_CODE_SUCCESS if query is successfully registered 781 */ 782 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); 783 784 /** 785 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 786 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 787 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 788 * @param callback 789 * @param con_handle 790 * @param descriptor 791 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 792 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 793 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 794 * ERROR_CODE_SUCCESS if query is successfully registered 795 */ 796 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); 797 798 /** 799 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 800 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 801 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 802 * @param callback 803 * @param con_handle 804 * @param descriptor_handle 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_read_long_characteristic_descriptor_using_descriptor_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle); 811 812 /** 813 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 814 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 815 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 816 * @param callback 817 * @param con_handle 818 * @param descriptor_handle 819 * @param offset 820 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 821 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 822 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 823 * ERROR_CODE_SUCCESS if query is successfully registered 824 */ 825 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); 826 827 /** 828 * @brief Writes the characteristic descriptor using its handle. 829 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 830 * 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). 831 * @param callback 832 * @param con_handle 833 * @param descriptor 834 * @param value_length 835 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 836 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 837 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 838 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 839 * ERROR_CODE_SUCCESS if query is successfully registered 840 */ 841 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); 842 843 /** 844 * @brief Writes the characteristic descriptor using its handle. 845 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 846 * 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). 847 * @param callback 848 * @param con_handle 849 * @param descriptor_handle 850 * @param value_length 851 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 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 * ERROR_CODE_SUCCESS if query is successfully registered 856 */ 857 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); 858 859 /** 860 * @brief Writes the characteristic descriptor using its handle. 861 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 862 * 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). 863 * @param callback 864 * @param con_handle 865 * @param descriptor 866 * @param value_length 867 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 868 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 869 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 870 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 871 * ERROR_CODE_SUCCESS if query is successfully registered 872 */ 873 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); 874 875 /** 876 * @brief Writes the characteristic descriptor using its handle. 877 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 878 * 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). 879 * @param callback 880 * @param con_handle 881 * @param descriptor_handle 882 * @param value_length 883 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 884 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 885 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 886 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 887 * ERROR_CODE_SUCCESS if query is successfully registered 888 */ 889 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); 890 891 /** 892 * @brief Writes the characteristic descriptor using its handle. 893 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 894 * 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). 895 * @param callback 896 * @param con_handle 897 * @param descriptor_handle 898 * @param offset of value 899 * @param value_length 900 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 901 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 902 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 903 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 904 * ERROR_CODE_SUCCESS if query is successfully registered 905 */ 906 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); 907 908 /** 909 * @brief Writes the client characteristic configuration of the specified characteristic. 910 * It is used to subscribe for notifications or indications of the characteristic value. 911 * For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION 912 * resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 913 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 914 * 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). 915 * @param callback 916 * @param con_handle 917 * @param characteristic 918 * @param configuration GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION, GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 919 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 920 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 921 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 922 * GATT_CLIENT_CHARACTERISTIC_NOTIFICATION_NOT_SUPPORTED if configuring notification, but characteristic has no notification property set 923 * GATT_CLIENT_CHARACTERISTIC_INDICATION_NOT_SUPPORTED if configuring indication, but characteristic has no indication property set 924 * ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if configuration is invalid 925 * ERROR_CODE_SUCCESS if query is successfully registered 926 */ 927 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); 928 929 /** 930 * @brief Register for notifications and indications of a characteristic enabled by 931 * the gatt_client_write_client_characteristic_configuration function. 932 * @param notification struct used to store registration 933 * @param callback 934 * @param con_handle or GATT_CLIENT_ANY_CONNECTION to receive updates from all connected devices 935 * @param characteristic or NULL to receive updates for all characteristics 936 */ 937 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); 938 939 /** 940 * @brief Stop listening to characteristic value updates registered with 941 * the gatt_client_listen_for_characteristic_value_updates function. 942 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 943 */ 944 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 945 946 /** 947 * @brief Transactional write. It can be called as many times as it is needed to write the characteristics within the same transaction. 948 * Call the gatt_client_execute_write function to commit the transaction. 949 * @param callback 950 * @param con_handle 951 * @param attribute_handle 952 * @param offset of value 953 * @param value_length 954 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 955 */ 956 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); 957 958 /** 959 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 960 * @param callback 961 * @param con_handle 962 * @return status 963 */ 964 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 965 966 /** 967 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 968 * @param callback 969 * @param con_handle 970 * @return status 971 */ 972 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 973 974 /** 975 * @brief Request callback when regular gatt query can be sent 976 * @note callback might happen during call to this function 977 * @param callback_registration to point to callback function and context information 978 * @param con_handle 979 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 980 */ 981 uint8_t gatt_client_request_to_send_gatt_query(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 982 983 /** 984 * @brief Remove queued callback for regular gatt queries, to be used on disconnect for example 985 * @param callback_registration 986 * @param con_handle 987 * @return ERROR_CODE_SUCCESS if ok 988 */ 989 uint8_t gatt_client_remove_gatt_query(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 990 991 /** 992 * @brief Request callback when writing characteristic value without response is possible 993 * @note callback might happen during call to this function 994 * @param callback_registration to point to callback function and context information 995 * @param con_handle 996 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 997 */ 998 uint8_t gatt_client_request_to_write_without_response(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 999 1000 1001 // the following functions are marked as deprecated and will be removed eventually 1002 /** 1003 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees 1004 * a single successful gatt_client_write_value_of_characteristic_without_response call. 1005 * @deprecated please use gatt_client_request_to_write_without_response instead 1006 * @param callback 1007 * @param con_handle 1008 * @return status 1009 */ 1010 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 1011 1012 1013 /* API_END */ 1014 1015 // used by generated btstack_event.c 1016 1017 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t * service); 1018 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 1019 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 1020 1021 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 1022 void gatt_client_att_packet_handler_fuzz(uint8_t packet_type, uint16_t handle, uint8_t *packet, uint16_t size); 1023 uint8_t gatt_client_get_client(hci_con_handle_t con_handle, gatt_client_t ** gatt_client); 1024 #endif 1025 1026 #if defined __cplusplus 1027 } 1028 #endif 1029 1030 #endif 1031