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