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