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