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