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