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