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