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