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