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