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