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 typedef enum { 157 GATT_CLIENT_SERVICE_DISCOVER_W2_SEND, 158 GATT_CLIENT_SERVICE_DISCOVER_W4_DONE, 159 GATT_CLIENT_SERVICE_DISCOVER_CHARACTERISTICS_W2_SEND, 160 GATT_CLIENT_SERVICE_DISCOVER_CHARACTERISTICS_W4_DONE, 161 GATT_CLIENT_SERVICE_SERVICE_CHANGED_WRITE_CCCD_W2_SEND, 162 GATT_CLIENT_SERVICE_SERVICE_CHANGED_WRITE_CCCD_W4_DONE, 163 GATT_CLIENT_SERVICE_DATABASE_HASH_READ_W2_SEND, 164 GATT_CLIENT_SERVICE_DATABASE_HASH_READ_W4_DONE, 165 GATT_CLIENT_SERVICE_DATABASE_HASH_WRITE_CCCD_W2_SEND, 166 GATT_CLIENT_SERVICE_DATABASE_HASH_WRITE_CCCD_W4_DONE, 167 GATT_CLIENT_SERVICE_DONE, 168 } gatt_client_service_state_t; 169 170 #ifdef ENABLE_GATT_OVER_EATT 171 typedef enum { 172 GATT_CLIENT_EATT_IDLE, 173 GATT_CLIENT_EATT_DISCOVER_GATT_SERVICE_W2_SEND, 174 GATT_CLIENT_EATT_DISCOVER_GATT_SERVICE_W4_DONE, 175 GATT_CLIENT_EATT_READ_SERVER_SUPPORTED_FEATURES_W2_SEND, 176 GATT_CLIENT_EATT_READ_SERVER_SUPPORTED_FEATURES_W4_DONE, 177 GATT_CLIENT_EATT_FIND_CLIENT_SUPPORTED_FEATURES_W2_SEND, 178 GATT_CLIENT_EATT_FIND_CLIENT_SUPPORTED_FEATURES_W4_DONE, 179 GATT_CLIENT_EATT_WRITE_ClIENT_SUPPORTED_FEATURES_W2_SEND, 180 GATT_CLIENT_EATT_WRITE_ClIENT_SUPPORTED_FEATURES_W4_DONE, 181 GATT_CLIENT_EATT_L2CAP_SETUP, 182 GATT_CLIENT_EATT_READY, 183 } gatt_client_eatt_state_t; 184 #endif 185 186 typedef struct gatt_client{ 187 btstack_linked_item_t item; 188 189 gatt_client_state_t state; 190 191 // user callback 192 btstack_packet_handler_t callback; 193 194 // can write without response callback 195 btstack_packet_handler_t write_without_response_callback; 196 197 // can write without response requests 198 btstack_linked_list_t write_without_response_requests; 199 200 // regular gatt query requests 201 btstack_linked_list_t query_requests; 202 203 hci_con_handle_t con_handle; 204 205 att_bearer_type_t bearer_type; 206 207 #if defined(ENABLE_GATT_OVER_CLASSIC) || defined(ENABLE_GATT_OVER_EATT) 208 uint16_t l2cap_cid; 209 bd_addr_t addr; 210 #endif 211 212 #ifdef ENABLE_GATT_OVER_CLASSIC 213 uint16_t l2cap_psm; 214 btstack_context_callback_registration_t callback_request; 215 #endif 216 217 #ifdef ENABLE_GATT_OVER_EATT 218 gatt_client_eatt_state_t eatt_state; 219 btstack_linked_list_t eatt_clients; 220 uint8_t * eatt_storage_buffer; 221 uint16_t eatt_storage_size; 222 uint8_t eatt_num_clients; 223 uint8_t gatt_server_supported_features; 224 uint16_t gatt_client_supported_features_handle; 225 #endif 226 227 uint16_t mtu; 228 gatt_client_mtu_t mtu_state; 229 230 uint16_t uuid16; 231 uint8_t uuid128[16]; 232 233 uint16_t start_group_handle; 234 uint16_t end_group_handle; 235 236 uint16_t query_start_handle; 237 uint16_t query_end_handle; 238 239 uint8_t characteristic_properties; 240 uint16_t characteristic_start_handle; 241 242 uint16_t attribute_handle; 243 uint16_t attribute_offset; 244 uint16_t attribute_length; 245 uint8_t* attribute_value; 246 247 // read multiple characteristic values 248 uint16_t read_multiple_handle_count; 249 uint16_t * read_multiple_handles; 250 251 uint16_t client_characteristic_configuration_handle; 252 uint8_t client_characteristic_configuration_value[2]; 253 254 bool filter_with_uuid; 255 bool send_confirmation; 256 257 int le_device_index; 258 uint8_t cmac[8]; 259 260 btstack_timer_source_t gc_timeout; 261 262 uint8_t security_counter; 263 bool wait_for_authentication_complete; 264 uint8_t pending_error_code; 265 266 bool reencryption_active; 267 uint8_t reencryption_result; 268 269 gap_security_level_t security_level; 270 271 // GATT Service Changes 272 gatt_client_service_state_t gatt_service_state; 273 uint16_t gatt_service_start_group_handle; 274 uint16_t gatt_service_end_group_handle; 275 // - Service Changed 276 uint16_t gatt_service_changed_value_handle; 277 uint16_t gatt_service_changed_cccd_handle; 278 uint16_t gatt_service_changed_end_handle; 279 // - Database Hash 280 uint16_t gatt_service_database_hash_value_handle; 281 uint16_t gatt_service_database_hash_cccd_handle; 282 uint16_t gatt_service_database_hash_end_handle; 283 284 } gatt_client_t; 285 286 typedef struct gatt_client_notification { 287 btstack_linked_item_t item; 288 btstack_packet_handler_t callback; 289 hci_con_handle_t con_handle; 290 uint16_t attribute_handle; 291 } gatt_client_notification_t; 292 293 /* API_START */ 294 295 typedef struct { 296 uint16_t start_group_handle; 297 uint16_t end_group_handle; 298 uint16_t uuid16; 299 uint8_t uuid128[16]; 300 } gatt_client_service_t; 301 302 typedef struct { 303 uint16_t start_handle; 304 uint16_t value_handle; 305 uint16_t end_handle; 306 uint16_t properties; 307 uint16_t uuid16; 308 uint8_t uuid128[16]; 309 } gatt_client_characteristic_t; 310 311 typedef struct { 312 uint16_t handle; 313 uint16_t uuid16; 314 uint8_t uuid128[16]; 315 } gatt_client_characteristic_descriptor_t; 316 317 /** 318 * @brief Set up GATT client. 319 */ 320 void gatt_client_init(void); 321 322 /** 323 * @brief Set minimum required security level for GATT Client 324 * @note The Bluetooth specification makes the GATT Server responsible to check for security. 325 * This allows an attacker to spoof an existing device with a GATT Servers, but skip the authentication part. 326 * If your application is exchanging sensitive data with a remote device, you would need to manually check 327 * the security level before sending/receive such data. 328 * With level > 0, the GATT Client triggers authentication for all GATT Requests and defers any exchange 329 * until the required security level is established. 330 * gatt_client_request_can_write_without_response_event does not trigger authentication 331 * gatt_client_request_to_write_without_response does not trigger authentication 332 * @pram level, default LEVEL_0 (no encryption required) 333 */ 334 void gatt_client_set_required_security_level(gap_security_level_t level); 335 336 /** 337 * @brief Connect to remote GATT Server over Classic (BR/EDR) Connection 338 * GATT_EVENT_CONNECTED with status and con_handle for other API functions 339 * is emitted on connection complete. 340 * @note requires ENABLE_GATT_OVER_CLASSIC. 341 * @param addr 342 * @return status 343 */ 344 uint8_t gatt_client_classic_connect(btstack_packet_handler_t callback, bd_addr_t addr); 345 346 /** 347 * @brief Disconnect o Classic (BR/EDR) connection to a remote GATT Server 348 * @note requires ENABLE_GATT_OVER_CLASSIC 349 * @param con_handle 350 * @return status 351 */ 352 uint8_t gatt_client_classic_disconnect(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 353 354 /** 355 * @brief Setup Enhanced LE Bearer with up to 5 channels on existing LE connection 356 * @param callback for GATT_EVENT_CONNECTED and GATT_EVENT_DISCONNECTED events 357 * @param con_handle 358 * @param num_channels 359 * @param storage_buffer for L2CAP connection 360 * @param storage_size - each channel requires (2 * ATT MTU) + 10 bytes 361 * @return 362 */ 363 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); 364 365 /** 366 * @brief MTU is available after the first query has completed. If status is equal to ERROR_CODE_SUCCESS, it returns the real value, 367 * otherwise the default value ATT_DEFAULT_MTU (see bluetooth.h). 368 * @param con_handle 369 * @param mtu 370 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 371 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 372 * GATT_CLIENT_IN_WRONG_STATE if MTU is not exchanged and MTU auto-exchange is disabled 373 * ERROR_CODE_SUCCESS if query is successfully registered 374 */ 375 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 376 377 /** 378 * @brief Sets whether a MTU Exchange Request shall be automatically send before the 379 * first attribute read request is send. Default is enabled. 380 * @param enabled 381 */ 382 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 383 384 /** 385 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU 386 * when gatt_client_mtu_enable_auto_negotiation is disabled. 387 * @param callback 388 * @param con_handle 389 */ 390 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 391 392 /** 393 * @brief Returns 1 if the GATT client is ready to receive a query. It is used with daemon. 394 * @param con_handle 395 * @return is_ready_status 0 - if no GATT client for con_handle is found, or is not ready, otherwise 1 396 */ 397 int gatt_client_is_ready(hci_con_handle_t con_handle); 398 399 /** 400 * @brief Discovers all primary services. 401 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 402 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 403 * @param callback 404 * @param con_handle 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(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 410 411 /** 412 * @brief Discovers all secondary services. 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 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 418 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 419 * ERROR_CODE_SUCCESS , if query is successfully registered 420 */ 421 uint8_t gatt_client_discover_secondary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 422 423 /** 424 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 425 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 426 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 427 * @param callback 428 * @param con_handle 429 * @param uuid16 430 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 431 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 432 * ERROR_CODE_SUCCESS , if query is successfully registered 433 */ 434 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 435 436 /** 437 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. 438 * For each found service a GATT_EVENT_SERVICE_QUERY_RESULT event will be emitted. 439 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 440 * @param callback 441 * @param con_handle 442 * @param uuid128 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_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 448 449 /** 450 * @brief Finds included services within the specified service. 451 * For each found included service a GATT_EVENT_INCLUDED_SERVICE_QUERY_RESULT event will be emitted. 452 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 453 * Information about included service type (primary/secondary) can be retrieved either by sending 454 * an ATT find information request for the returned start group handle 455 * (returning the handle and the UUID for primary or secondary service) or by comparing the service 456 * to the list of all primary services. 457 * @param callback 458 * @param con_handle 459 * @param service 460 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 461 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 462 * ERROR_CODE_SUCCESS , if query is successfully registered 463 */ 464 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); 465 466 /** 467 * @brief Discovers all characteristics within the specified service. 468 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will be emited. 469 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 470 * @param callback 471 * @param con_handle 472 * @param service 473 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 474 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 475 * ERROR_CODE_SUCCESS , if query is successfully registered 476 */ 477 uint8_t gatt_client_discover_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t * service); 478 479 /** 480 * @brief The following four functions are used to discover all characteristics within 481 * the specified service or handle range, and return those that match the given UUID. 482 * 483 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 484 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 485 * @param callback 486 * @param con_handle 487 * @param start_handle 488 * @param end_handle 489 * @param uuid16 490 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 491 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 492 * ERROR_CODE_SUCCESS , if query is successfully registered 493 */ 494 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); 495 496 /** 497 * @brief The following four functions are used to discover all characteristics within the 498 * specified service or handle range, and return those that match the given UUID. 499 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 500 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 501 * @param callback 502 * @param con_handle 503 * @param start_handle 504 * @param end_handle 505 * @param uuid128 506 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 507 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 508 * ERROR_CODE_SUCCESS , if query is successfully registered 509 */ 510 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); 511 512 /** 513 * @brief The following four functions are used to discover all characteristics within the 514 * specified service or handle range, and return those that match the given UUID. 515 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 516 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 517 * @param callback 518 * @param con_handle 519 * @param service 520 * @param uuid16 521 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 522 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 523 * ERROR_CODE_SUCCESS , if query is successfully registered 524 */ 525 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); 526 527 /** 528 * @brief The following four functions are used to discover all characteristics within the 529 * specified service or handle range, and return those that match the given UUID. 530 * For each found characteristic a GATT_EVENT_CHARACTERISTIC_QUERY_RESULT event will emitted. 531 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 532 * @param callback 533 * @param con_handle 534 * @param service 535 * @param uuid128 536 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 537 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 538 * ERROR_CODE_SUCCESS , if query is successfully registered 539 */ 540 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); 541 542 /** 543 * @brief Discovers attribute handle and UUID of a characteristic descriptor within the specified characteristic. 544 * For each found descriptor a GATT_EVENT_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT event will be emitted. 545 * 546 * The GATT_EVENT_QUERY_COMPLETE event marks the end of discovery. 547 * @param callback 548 * @param con_handle 549 * @param characteristic 550 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 551 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 552 * ERROR_CODE_SUCCESS , if query is successfully registered 553 */ 554 uint8_t gatt_client_discover_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 555 556 /** 557 * @brief Reads the characteristic value using the characteristic's value handle. 558 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 559 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 560 * @param callback 561 * @param con_handle 562 * @param characteristic 563 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 564 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 565 * ERROR_CODE_SUCCESS , if query is successfully registered 566 */ 567 uint8_t gatt_client_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 568 569 /** 570 * @brief Reads the characteristic value using the characteristic's value handle. 571 * If the characteristic value is found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 572 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 573 * @param callback 574 * @param con_handle 575 * @param value_handle 576 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 577 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 578 * ERROR_CODE_SUCCESS , if query is successfully registered 579 */ 580 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); 581 582 /** 583 * @brief Reads the characteric value of all characteristics with the uuid. 584 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 585 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 586 * @param callback 587 * @param con_handle 588 * @param start_handle 589 * @param end_handle 590 * @param uuid16 591 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 592 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 593 * ERROR_CODE_SUCCESS , if query is successfully registered 594 */ 595 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); 596 597 /** 598 * @brief Reads the characteric value of all characteristics with the uuid. 599 * For each characteristic value found a GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event will be emitted. 600 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 601 * @param callback 602 * @param con_handle 603 * @param start_handle 604 * @param end_handle 605 * @param uuid128 606 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 607 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 608 * ERROR_CODE_SUCCESS , if query is successfully registered 609 */ 610 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); 611 612 /** 613 * @brief Reads the long characteristic value using the characteristic's value handle. 614 * The value will be returned in several blobs. 615 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 616 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 617 * @param callback 618 * @param con_handle 619 * @param characteristic 620 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 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_read_long_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t * characteristic); 625 626 /** 627 * @brief Reads the long characteristic value using the characteristic's value handle. 628 * The value will be returned in several blobs. 629 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 630 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 631 * @param callback 632 * @param con_handle 633 * @param value_handle 634 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 635 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 636 * ERROR_CODE_SUCCESS , if query is successfully registered 637 */ 638 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); 639 640 /** 641 * @brief Reads the long characteristic value using the characteristic's value handle. 642 * The value will be returned in several blobs. 643 * For each blob, a GATT_EVENT_LONG_CHARACTERISTIC_VALUE_QUERY_RESULT event with updated value offset will be emitted. 644 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 645 * @param callback 646 * @param con_handle 647 * @param value_handle 648 * @param offset 649 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 650 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 651 * ERROR_CODE_SUCCESS , if query is successfully registered 652 */ 653 uint8_t gatt_client_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); 654 655 /* 656 * @brief Read multiple characteristic values. 657 * The all results are emitted via single GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event, 658 * followed by the GATT_EVENT_QUERY_COMPLETE event, which marks the end of read. 659 * @param callback 660 * @param con_handle 661 * @param num_value_handles 662 * @param value_handles list of handles 663 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 664 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 665 * ERROR_CODE_SUCCESS , if query is successfully registered 666 */ 667 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); 668 669 /* 670 * @brief Read multiple varaible characteristic values. Only supported over LE Enhanced Bearer 671 * The all results are emitted via single GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT event, 672 * followed by the GATT_EVENT_QUERY_COMPLETE event, which marks the end of read. 673 * @param callback 674 * @param con_handle 675 * @param num_value_handles 676 * @param value_handles list of handles 677 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 678 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 679 * ERROR_CODE_SUCCESS , if query is successfully registered 680 */ 681 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); 682 683 /** 684 * @brief Writes the characteristic value using the characteristic's value handle without 685 * an acknowledgment that the write was successfully performed. 686 * @param con_handle 687 * @param value_handle 688 * @param value_length 689 * @param value is copied on success and does not need to be retained 690 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 691 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 692 * BTSTACK_ACL_BUFFERS_FULL , if L2CAP cannot send, there are no free ACL slots 693 * ERROR_CODE_SUCCESS , if query is successfully registered 694 */ 695 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); 696 697 /** 698 * @brief Writes the authenticated characteristic value using the characteristic's value handle 699 * without an acknowledgment that the write was successfully performed. 700 * @note GATT_EVENT_QUERY_COMPLETE is emitted with ATT_ERROR_SUCCESS for success, 701 * or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored. 702 * @param callback 703 * @param con_handle 704 * @param value_handle 705 * @param message_len 706 * @param message is not copied, make sure memory is accessible until write is done 707 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 708 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 709 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 710 * ERROR_CODE_SUCCESS if query is successfully registered 711 */ 712 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); 713 714 /** 715 * @brief Writes the characteristic value using the characteristic's value handle. 716 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 717 * The write is successfully performed, if the event's att_status field is set to 718 * ATT_ERROR_SUCCESS (see bluetooth.h for ATT_ERROR codes). 719 * @param callback 720 * @param con_handle 721 * @param value_handle 722 * @param value_length 723 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 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_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); 730 731 /** 732 * @brief Writes the characteristic value using the characteristic's value 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 value_handle 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_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); 746 747 /** 748 * @brief Writes the characteristic value using the characteristic's value 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 value_handle 754 * @param offset of value 755 * @param value_length 756 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 757 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 758 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 759 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 760 * ERROR_CODE_SUCCESS if query is successfully registered 761 */ 762 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); 763 764 /** 765 * @brief Writes of the long characteristic value using the characteristic's value handle. 766 * It uses server response to validate that the write was correctly received. 767 * The GATT_EVENT_QUERY_COMPLETE EVENT marks the end of write. 768 * 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). 769 * @param callback 770 * @param con_handle 771 * @param value_handle 772 * @param value_length 773 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 774 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 775 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 776 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 777 * ERROR_CODE_SUCCESS if query is successfully registered 778 */ 779 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); 780 781 /** 782 * @brief Reads the characteristic descriptor using its handle. 783 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 784 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 785 * @param callback 786 * @param con_handle 787 * @param descriptor 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_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 794 795 /** 796 * @brief Reads the characteristic descriptor using its handle. 797 * If the characteristic descriptor is found, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 798 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 799 * @param callback 800 * @param con_handle 801 * @param descriptor 802 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 803 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 804 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 805 * ERROR_CODE_SUCCESS if query is successfully registered 806 */ 807 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); 808 809 /** 810 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 811 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 812 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 813 * @param callback 814 * @param con_handle 815 * @param descriptor 816 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 817 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 818 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 819 * ERROR_CODE_SUCCESS if query is successfully registered 820 */ 821 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); 822 823 /** 824 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 825 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 826 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 827 * @param callback 828 * @param con_handle 829 * @param descriptor_handle 830 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 831 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 832 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 833 * ERROR_CODE_SUCCESS if query is successfully registered 834 */ 835 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); 836 837 /** 838 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. 839 * For each blob, a GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT event will be emitted. 840 * The GATT_EVENT_QUERY_COMPLETE event marks the end of read. 841 * @param callback 842 * @param con_handle 843 * @param descriptor_handle 844 * @param offset 845 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 846 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 847 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 848 * ERROR_CODE_SUCCESS if query is successfully registered 849 */ 850 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); 851 852 /** 853 * @brief Writes the characteristic descriptor using its handle. 854 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 855 * 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). 856 * @param callback 857 * @param con_handle 858 * @param descriptor 859 * @param value_length 860 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 861 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 862 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 863 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 864 * ERROR_CODE_SUCCESS if query is successfully registered 865 */ 866 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); 867 868 /** 869 * @brief Writes the characteristic descriptor using its handle. 870 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 871 * 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). 872 * @param callback 873 * @param con_handle 874 * @param descriptor_handle 875 * @param value_length 876 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 877 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 878 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 879 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 880 * ERROR_CODE_SUCCESS if query is successfully registered 881 */ 882 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); 883 884 /** 885 * @brief Writes the characteristic descriptor using its handle. 886 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 887 * 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). 888 * @param callback 889 * @param con_handle 890 * @param descriptor 891 * @param value_length 892 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 893 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 894 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 895 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 896 * ERROR_CODE_SUCCESS if query is successfully registered 897 */ 898 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); 899 900 /** 901 * @brief Writes the characteristic descriptor using its handle. 902 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 903 * 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). 904 * @param callback 905 * @param con_handle 906 * @param descriptor_handle 907 * @param value_length 908 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 909 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 910 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 911 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 912 * ERROR_CODE_SUCCESS if query is successfully registered 913 */ 914 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); 915 916 /** 917 * @brief Writes the characteristic descriptor using its handle. 918 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 919 * 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). 920 * @param callback 921 * @param con_handle 922 * @param descriptor_handle 923 * @param offset of value 924 * @param value_length 925 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 926 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 927 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 928 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 929 * ERROR_CODE_SUCCESS if query is successfully registered 930 */ 931 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); 932 933 /** 934 * @brief Writes the client characteristic configuration of the specified characteristic. 935 * It is used to subscribe for notifications or indications of the characteristic value. 936 * For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION 937 * resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 938 * The GATT_EVENT_QUERY_COMPLETE event marks the end of write. 939 * 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). 940 * @param callback 941 * @param con_handle 942 * @param characteristic 943 * @param configuration GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION, GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 944 * @return status ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if no HCI connection for con_handle is found 945 * BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle could be allocated 946 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 947 * GATT_CLIENT_CHARACTERISTIC_NOTIFICATION_NOT_SUPPORTED if configuring notification, but characteristic has no notification property set 948 * GATT_CLIENT_CHARACTERISTIC_INDICATION_NOT_SUPPORTED if configuring indication, but characteristic has no indication property set 949 * ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if configuration is invalid 950 * ERROR_CODE_SUCCESS if query is successfully registered 951 */ 952 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); 953 954 /** 955 * @brief Register for changes to the Service Changed and Database Hash Characteristics of the remote GATT Service 956 * * 957 * When configured, GATT_EVENT_QUERY_COMPLETE event is emitted 958 * If supported, the Database Hash is read as well 959 * 960 * Requires ENABLE_GATT_CLIENT_SERVICE_CHANGED 961 * 962 * @param callback 963 */ 964 void gatt_client_add_service_changed_handler(btstack_packet_callback_registration_t * callback); 965 966 /** 967 * @brief Remove callback for service changes 968 * 969 * Requires ENABLE_GATT_CLIENT_SERVICE_CHANGED 970 * 971 * @param callback 972 */ 973 void gatt_client_remove_service_changed_handler(btstack_packet_callback_registration_t * callback); 974 975 /** 976 * @brief Register for notifications and indications of a characteristic enabled by 977 * the gatt_client_write_client_characteristic_configuration function. 978 * @param notification struct used to store registration 979 * @param callback 980 * @param con_handle or GATT_CLIENT_ANY_CONNECTION to receive updates from all connected devices 981 * @param characteristic or NULL to receive updates for all characteristics 982 */ 983 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); 984 985 /** 986 * @brief Stop listening to characteristic value updates registered with 987 * the gatt_client_listen_for_characteristic_value_updates function. 988 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 989 */ 990 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 991 992 /** 993 * @brief Transactional write. It can be called as many times as it is needed to write the characteristics within the same transaction. 994 * Call the gatt_client_execute_write function to commit the transaction. 995 * @param callback 996 * @param con_handle 997 * @param attribute_handle 998 * @param offset of value 999 * @param value_length 1000 * @param value is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 1001 */ 1002 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); 1003 1004 /** 1005 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 1006 * @param callback 1007 * @param con_handle 1008 * @return status 1009 */ 1010 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 1011 1012 /** 1013 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 1014 * @param callback 1015 * @param con_handle 1016 * @return status 1017 */ 1018 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 1019 1020 /** 1021 * @brief Request callback when regular gatt query can be sent 1022 * @note callback might happen during call to this function 1023 * @param callback_registration to point to callback function and context information 1024 * @param con_handle 1025 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 1026 */ 1027 uint8_t gatt_client_request_to_send_gatt_query(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 1028 1029 /** 1030 * @brief Remove queued callback for regular gatt queries, to be used on disconnect for example 1031 * @param callback_registration 1032 * @param con_handle 1033 * @return ERROR_CODE_SUCCESS if ok 1034 */ 1035 uint8_t gatt_client_remove_gatt_query(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 1036 1037 /** 1038 * @brief Request callback when writing characteristic value without response is possible 1039 * @note callback might happen during call to this function 1040 * @param callback_registration to point to callback function and context information 1041 * @param con_handle 1042 * @return ERROR_CODE_SUCCESS if ok, ERROR_CODE_UNKNOWN_CONNECTION_IDENTIFIER if handle unknown, and ERROR_CODE_COMMAND_DISALLOWED if callback already registered 1043 */ 1044 uint8_t gatt_client_request_to_write_without_response(btstack_context_callback_registration_t * callback_registration, hci_con_handle_t con_handle); 1045 1046 1047 // the following functions are marked as deprecated and will be removed eventually 1048 /** 1049 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees 1050 * a single successful gatt_client_write_value_of_characteristic_without_response call. 1051 * @deprecated please use gatt_client_request_to_write_without_response instead 1052 * @param callback 1053 * @param con_handle 1054 * @return status 1055 */ 1056 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 1057 1058 1059 /* API_END */ 1060 1061 // used by generated btstack_event.c 1062 1063 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t * service); 1064 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 1065 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 1066 1067 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 1068 void gatt_client_att_packet_handler_fuzz(uint8_t packet_type, uint16_t handle, uint8_t *packet, uint16_t size); 1069 uint8_t gatt_client_get_client(hci_con_handle_t con_handle, gatt_client_t ** gatt_client); 1070 #endif 1071 1072 #if defined __cplusplus 1073 } 1074 #endif 1075 1076 #endif 1077