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 MATTHIAS 24 * RINGWALD 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 #ifndef btstack_gatt_client_h 40 #define btstack_gatt_client_h 41 42 #include "hci.h" 43 44 #if defined __cplusplus 45 extern "C" { 46 #endif 47 48 typedef enum { 49 P_READY, 50 P_W2_SEND_SERVICE_QUERY, 51 P_W4_SERVICE_QUERY_RESULT, 52 P_W2_SEND_SERVICE_WITH_UUID_QUERY, 53 P_W4_SERVICE_WITH_UUID_RESULT, 54 55 P_W2_SEND_ALL_CHARACTERISTICS_OF_SERVICE_QUERY, 56 P_W4_ALL_CHARACTERISTICS_OF_SERVICE_QUERY_RESULT, 57 P_W2_SEND_CHARACTERISTIC_WITH_UUID_QUERY, 58 P_W4_CHARACTERISTIC_WITH_UUID_QUERY_RESULT, 59 60 P_W2_SEND_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY, 61 P_W4_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT, 62 63 P_W2_SEND_INCLUDED_SERVICE_QUERY, 64 P_W4_INCLUDED_SERVICE_QUERY_RESULT, 65 P_W2_SEND_INCLUDED_SERVICE_WITH_UUID_QUERY, 66 P_W4_INCLUDED_SERVICE_UUID_WITH_QUERY_RESULT, 67 68 P_W2_SEND_READ_CHARACTERISTIC_VALUE_QUERY, 69 P_W4_READ_CHARACTERISTIC_VALUE_RESULT, 70 71 P_W2_SEND_READ_BLOB_QUERY, 72 P_W4_READ_BLOB_RESULT, 73 74 P_W2_SEND_READ_BY_TYPE_REQUEST, 75 P_W4_READ_BY_TYPE_RESPONSE, 76 77 P_W2_SEND_READ_MULTIPLE_REQUEST, 78 P_W4_READ_MULTIPLE_RESPONSE, 79 80 P_W2_SEND_WRITE_CHARACTERISTIC_VALUE, 81 P_W4_WRITE_CHARACTERISTIC_VALUE_RESULT, 82 83 P_W2_PREPARE_WRITE, 84 P_W4_PREPARE_WRITE_RESULT, 85 P_W2_PREPARE_RELIABLE_WRITE, 86 P_W4_PREPARE_RELIABLE_WRITE_RESULT, 87 88 P_W2_EXECUTE_PREPARED_WRITE, 89 P_W4_EXECUTE_PREPARED_WRITE_RESULT, 90 P_W2_CANCEL_PREPARED_WRITE, 91 P_W4_CANCEL_PREPARED_WRITE_RESULT, 92 P_W2_CANCEL_PREPARED_WRITE_DATA_MISMATCH, 93 P_W4_CANCEL_PREPARED_WRITE_DATA_MISMATCH_RESULT, 94 95 #ifdef ENABLE_GATT_FIND_INFORMATION_FOR_CCC_DISCOVERY 96 P_W2_SEND_FIND_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 97 P_W4_FIND_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 98 #else 99 P_W2_SEND_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY, 100 P_W4_READ_CLIENT_CHARACTERISTIC_CONFIGURATION_QUERY_RESULT, 101 #endif 102 P_W2_WRITE_CLIENT_CHARACTERISTIC_CONFIGURATION, 103 P_W4_CLIENT_CHARACTERISTIC_CONFIGURATION_RESULT, 104 105 P_W2_SEND_READ_CHARACTERISTIC_DESCRIPTOR_QUERY, 106 P_W4_READ_CHARACTERISTIC_DESCRIPTOR_RESULT, 107 108 P_W2_SEND_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_QUERY, 109 P_W4_READ_BLOB_CHARACTERISTIC_DESCRIPTOR_RESULT, 110 111 P_W2_SEND_WRITE_CHARACTERISTIC_DESCRIPTOR, 112 P_W4_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 113 114 // all long writes use this 115 P_W2_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR, 116 P_W4_PREPARE_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 117 P_W2_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR, 118 P_W4_EXECUTE_PREPARED_WRITE_CHARACTERISTIC_DESCRIPTOR_RESULT, 119 120 // gatt reliable write API use this (manual version of the above) 121 P_W2_PREPARE_WRITE_SINGLE, 122 P_W4_PREPARE_WRITE_SINGLE_RESULT, 123 124 P_W4_IDENTITY_RESOLVING, 125 P_W4_CMAC_READY, 126 P_W4_CMAC_RESULT, 127 P_W2_SEND_SIGNED_WRITE, 128 P_W4_SEND_SINGED_WRITE_DONE, 129 } gatt_client_state_t; 130 131 132 typedef enum{ 133 SEND_MTU_EXCHANGE, 134 SENT_MTU_EXCHANGE, 135 MTU_EXCHANGED, 136 MTU_AUTO_EXCHANGE_DISABLED 137 } gatt_client_mtu_t; 138 139 typedef struct gatt_client{ 140 btstack_linked_item_t item; 141 // TODO: rename gatt_client_state -> state 142 gatt_client_state_t gatt_client_state; 143 144 // user callback 145 btstack_packet_handler_t callback; 146 147 // can write without response callback 148 btstack_packet_handler_t write_without_response_callback; 149 150 hci_con_handle_t con_handle; 151 152 uint8_t address_type; 153 bd_addr_t address; 154 155 uint16_t mtu; 156 gatt_client_mtu_t mtu_state; 157 158 uint16_t uuid16; 159 uint8_t uuid128[16]; 160 161 uint16_t start_group_handle; 162 uint16_t end_group_handle; 163 164 uint16_t query_start_handle; 165 uint16_t query_end_handle; 166 167 uint8_t characteristic_properties; 168 uint16_t characteristic_start_handle; 169 170 uint16_t attribute_handle; 171 uint16_t attribute_offset; 172 uint16_t attribute_length; 173 uint8_t* attribute_value; 174 175 // read multiple characteristic values 176 uint16_t read_multiple_handle_count; 177 uint16_t * read_multiple_handles; 178 179 uint16_t client_characteristic_configuration_handle; 180 uint8_t client_characteristic_configuration_value[2]; 181 182 uint8_t filter_with_uuid; 183 uint8_t send_confirmation; 184 185 int le_device_index; 186 uint8_t cmac[8]; 187 188 btstack_timer_source_t gc_timeout; 189 190 uint8_t security_counter; 191 uint8_t wait_for_pairing_complete; 192 uint8_t pending_error_code; 193 194 #ifdef ENABLE_LE_PROACTIVE_AUTHENTICATION 195 bool reencryption_active; 196 uint8_t reencryption_result; 197 #endif 198 199 gap_security_level_t security_level; 200 201 } gatt_client_t; 202 203 typedef struct gatt_client_notification { 204 btstack_linked_item_t item; 205 btstack_packet_handler_t callback; 206 hci_con_handle_t con_handle; 207 uint16_t attribute_handle; 208 } gatt_client_notification_t; 209 210 /* API_START */ 211 212 typedef struct { 213 uint16_t start_group_handle; 214 uint16_t end_group_handle; 215 uint16_t uuid16; 216 uint8_t uuid128[16]; 217 } gatt_client_service_t; 218 219 typedef struct { 220 uint16_t start_handle; 221 uint16_t value_handle; 222 uint16_t end_handle; 223 uint16_t properties; 224 uint16_t uuid16; 225 uint8_t uuid128[16]; 226 } gatt_client_characteristic_t; 227 228 typedef struct { 229 uint16_t handle; 230 uint16_t uuid16; 231 uint8_t uuid128[16]; 232 } gatt_client_characteristic_descriptor_t; 233 234 /** 235 * @brief Set up GATT client. 236 */ 237 void gatt_client_init(void); 238 239 /** 240 * @brief Set minimum required security level for GATT Client 241 * @note The Bluetooth specification makes the GATT Server responsible to check for security. 242 * This allows an attacker to spoof existing devices with GATT Servers, but skip the authentication part 243 * If your application is exchanging sensitive data from a remote device, you would need to manually check 244 * the security level before sending/receive such data. This function allows to have the GATT Client post-pone 245 * any exchange until the required security level is established. 246 * @pram level, default LEVEL_0 (no encryption required) 247 */ 248 void gatt_client_set_required_security_level(gap_security_level_t level); 249 250 /** 251 * @brief MTU is available after the first query has completed. If status is equal to ERROR_CODE_SUCCESS, it returns the real value, otherwise the default value ATT_DEFAULT_MTU (see bluetooth.h). 252 * @param con_handle 253 * @param mtu 254 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 255 * GATT_CLIENT_IN_WRONG_STATE if MTU is not exchanged and MTU auto-exchange is disabled 256 * ERROR_CODE_SUCCESS if query is successfully registered 257 */ 258 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 259 260 /** 261 * @brief Sets whether a MTU Exchange Request shall be automatically send before the first attribute read request is send. Default is enabled. 262 * @param enabled 263 */ 264 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 265 266 /** 267 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU when gatt_client_mtu_enable_auto_negotiation is disabled. 268 * @param callback 269 * @param con_handle 270 */ 271 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 272 273 /** 274 * @brief Returns if the GATT client is ready to receive a query. It is used with daemon. 275 * @param con_handle 276 * @return is_ready_status 0 - if no GATT client for con_handle is found, or is not ready, otherwise 1 277 */ 278 int gatt_client_is_ready(hci_con_handle_t con_handle); 279 280 /** 281 * @brief Discovers all primary services. For each found service, an le_service_event_t with type set to GATT_EVENT_SERVICE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t, with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 282 * @param callback 283 * @param con_handle 284 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 285 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 286 * ERROR_CODE_SUCCESS , if query is successfully registered 287 */ 288 uint8_t gatt_client_discover_primary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 289 290 /** 291 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. For each found service, an le_service_event_t with type set to GATT_EVENT_SERVICE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t, with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 292 * @param callback 293 * @param con_handle 294 * @param uuid16 295 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 296 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 297 * ERROR_CODE_SUCCESS , if query is successfully registered 298 */ 299 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 300 301 /** 302 * @brief Discovers a specific primary service given its UUID. This service may exist multiple times. For each found service, an le_service_event_t with type set to GATT_EVENT_SERVICE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t, with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 303 * @param callback 304 * @param con_handle 305 * @param uuid128 306 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 307 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 308 * ERROR_CODE_SUCCESS , if query is successfully registered 309 */ 310 uint8_t gatt_client_discover_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 311 312 /** 313 * @brief Finds included services within the specified service. For each found included service, an le_service_event_t with type set to GATT_EVENT_INCLUDED_SERVICE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. Information about included service type (primary/secondary) can be retrieved either by sending an ATT find information request for the returned start group handle (returning the handle and the UUID for primary or secondary service) or by comparing the service to the list of all primary services. 314 * @param callback 315 * @param con_handle 316 * @param service 317 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 318 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 319 * ERROR_CODE_SUCCESS , if query is successfully registered 320 */ 321 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); 322 323 /** 324 * @brief Discovers all characteristics within the specified service. For each found characteristic, an le_characteristics_event_t with type set to GATT_EVENT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 325 * @param callback 326 * @param con_handle 327 * @param service 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_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t *service); 333 334 /** 335 * @brief The following four functions are used to discover all characteristics within the specified service or handle range, and return those that match the given UUID. For each found characteristic, an le_characteristic_event_t with type set to GATT_EVENT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 336 * @param callback 337 * @param con_handle 338 * @param start_handle 339 * @param end_handle 340 * @param uuid16 341 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 342 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 343 * ERROR_CODE_SUCCESS , if query is successfully registered 344 */ 345 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); 346 347 /** 348 * @brief The following four functions are used to discover all characteristics within the specified service or handle range, and return those that match the given UUID. For each found characteristic, an le_characteristic_event_t with type set to GATT_EVENT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 349 * @param callback 350 * @param con_handle 351 * @param start_handle 352 * @param end_handle 353 * @param uuid128 354 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 355 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 356 * ERROR_CODE_SUCCESS , if query is successfully registered 357 */ 358 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, uint8_t * uuid128); 359 360 /** 361 * @brief The following four functions are used to discover all characteristics within the specified service or handle range, and return those that match the given UUID. For each found characteristic, an le_characteristic_event_t with type set to GATT_EVENT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 362 * @param callback 363 * @param con_handle 364 * @param service 365 * @param uuid16 366 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 367 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 368 * ERROR_CODE_SUCCESS , if query is successfully registered 369 */ 370 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); 371 372 /** 373 * @brief The following four functions are used to discover all characteristics within the specified service or handle range, and return those that match the given UUID. For each found characteristic, an le_characteristic_event_t with type set to GATT_EVENT_CHARACTERISTIC_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 374 * @param callback 375 * @param con_handle 376 * @param service 377 * @param uuid128 378 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 379 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 380 * ERROR_CODE_SUCCESS , if query is successfully registered 381 */ 382 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, uint8_t * uuid128); 383 384 /** 385 * @brief Discovers attribute handle and UUID of a characteristic descriptor within the specified characteristic. For each found descriptor, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_ALL_CHARACTERISTIC_DESCRIPTORS_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of discovery. 386 * @param callback 387 * @param con_handle 388 * @param characteristic 389 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 390 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 391 * ERROR_CODE_SUCCESS , if query is successfully registered 392 */ 393 uint8_t gatt_client_discover_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t *characteristic); 394 395 /** 396 * @brief Reads the characteristic value using the characteristic's value handle. If the characteristic value is found, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 397 * @param callback 398 * @param con_handle 399 * @param characteristic 400 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 401 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 402 * ERROR_CODE_SUCCESS , if query is successfully registered 403 */ 404 uint8_t gatt_client_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t *characteristic); 405 406 /** 407 * @brief Reads the characteristic value using the characteristic's value handle. If the characteristic value is found, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 408 * @param callback 409 * @param con_handle 410 * @param characteristic_value_handle 411 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 412 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 413 * ERROR_CODE_SUCCESS , if query is successfully registered 414 */ 415 uint8_t gatt_client_read_value_of_characteristic_using_value_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t characteristic_value_handle); 416 417 /** 418 * @brief Reads the characteric value of all characteristics with the uuid. For each found, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 419 * @param callback 420 * @param con_handle 421 * @param start_handle 422 * @param end_handle 423 * @param uuid16 424 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 425 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 426 * ERROR_CODE_SUCCESS , if query is successfully registered 427 */ 428 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); 429 430 /** 431 * @brief Reads the characteric value of all characteristics with the uuid. For each found, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 432 * @param callback 433 * @param con_handle 434 * @param start_handle 435 * @param end_handle 436 * @param uuid128 437 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 438 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 439 * ERROR_CODE_SUCCESS , if query is successfully registered 440 */ 441 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, uint8_t * uuid128); 442 443 /** 444 * @brief Reads the long characteristic value using the characteristic's value handle. The value will be returned in several blobs. For each blob, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT and updated value offset will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, mark 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_long_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 long characteristic value using the characteristic's value handle. The value will be returned in several blobs. For each blob, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT and updated value offset will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, mark the end of read. 456 * @param callback 457 * @param con_handle 458 * @param characteristic_value_handle 459 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 460 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 461 * ERROR_CODE_SUCCESS , if query is successfully registered 462 */ 463 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 characteristic_value_handle); 464 465 /** 466 * @brief Reads the long characteristic value using the characteristic's value handle. The value will be returned in several blobs. For each blob, an le_characteristic_value_event_t with type set to GATT_EVENT_CHARACTERISTIC_VALUE_QUERY_RESULT and updated value offset will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, mark the end of read. 467 * @param callback 468 * @param con_handle 469 * @param characteristic_value_handle 470 * @param offset 471 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 472 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 473 * ERROR_CODE_SUCCESS , if query is successfully registered 474 */ 475 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 characteristic_value_handle, uint16_t offset); 476 477 /* 478 * @brief Read multiple characteristic values 479 * @param callback 480 * @param con_handle 481 * @param num_value_handles 482 * @param value_handles list of handles 483 */ 484 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); 485 486 /** 487 * @brief Writes the characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 488 * @param con_handle 489 * @param characteristic_value_handle 490 * @param length of data 491 * @param data is not copied, make sure memory is accessible until write is done 492 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 493 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 494 * BTSTACK_ACL_BUFFERS_FULL , if L2CAP cannot send, there are no free ACL slots 495 * ERROR_CODE_SUCCESS , if query is successfully registered 496 */ 497 uint8_t gatt_client_write_value_of_characteristic_without_response(hci_con_handle_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 498 499 /** 500 * @brief Writes the authenticated characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 501 * @note GATT_EVENT_QUERY_COMPLETE is emitted with 0 for success or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored 502 * @param callback 503 * @param con_handle 504 * @param value_handle 505 * @param message_len 506 * @param message is not copied, make sure memory is accessible until write is done 507 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 508 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 509 * ERROR_CODE_SUCCESS if query is successfully registered 510 */ 511 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); 512 513 /** 514 * @brief Writes the characteristic value using the characteristic's value handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 515 * @param callback 516 * @param con_handle 517 * @param characteristic_value_handle 518 * @param length of data 519 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 520 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 521 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 522 * ERROR_CODE_SUCCESS if query is successfully registered 523 */ 524 uint8_t gatt_client_write_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 525 526 /** 527 * @brief Writes the characteristic value using the characteristic's value handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 528 * @param callback 529 * @param con_handle 530 * @param characteristic_value_handle 531 * @param length of data 532 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 533 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 534 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 535 * ERROR_CODE_SUCCESS if query is successfully registered 536 */ 537 uint8_t gatt_client_write_long_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 538 539 /** 540 * @brief Writes the characteristic value using the characteristic's value handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 541 * @param callback 542 * @param con_handle 543 * @param characteristic_value_handle 544 * @param offset of value 545 * @param length of data 546 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 547 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 548 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 549 * ERROR_CODE_SUCCESS if query is successfully registered 550 */ 551 uint8_t gatt_client_write_long_value_of_characteristic_with_offset(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t characteristic_value_handle, uint16_t offset, uint16_t length, uint8_t * data); 552 553 /** 554 * @brief Writes of the long characteristic value using the characteristic's value handle. It uses server response to validate that the write was correctly received. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE marks the end of write. 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). 555 * @param callback 556 * @param con_handle 557 * @param characteristic_value_handle 558 * @param length of data 559 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 560 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 561 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 562 * ERROR_CODE_SUCCESS if query is successfully registered 563 */ 564 uint8_t gatt_client_reliable_write_long_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t characteristic_value_handle, uint16_t length, uint8_t * data); 565 566 /** 567 * @brief Reads the characteristic descriptor using its handle. If the characteristic descriptor is found, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 568 * @param callback 569 * @param con_handle 570 * @param descriptor 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_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 576 577 /** 578 * @brief Reads the characteristic descriptor using its handle. If the characteristic descriptor is found, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 579 * @param callback 580 * @param con_handle 581 * @param descriptor 582 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 583 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 584 * ERROR_CODE_SUCCESS if query is successfully registered 585 */ 586 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); 587 588 /** 589 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. For each blob, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 590 * @param callback 591 * @param con_handle 592 * @param descriptor_handle 593 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 594 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 595 * ERROR_CODE_SUCCESS if query is successfully registered 596 */ 597 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); 598 599 /** 600 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. For each blob, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 601 * @param callback 602 * @param con_handle 603 * @param descriptor_handle 604 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 605 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 606 * ERROR_CODE_SUCCESS if query is successfully registered 607 */ 608 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); 609 610 /** 611 * @brief Reads the long characteristic descriptor using its handle. It will be returned in several blobs. For each blob, an le_characteristic_descriptor_event_t with type set to GATT_EVENT_CHARACTERISTIC_DESCRIPTOR_QUERY_RESULT will be generated and passed to the registered callback. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of read. 612 * @param callback 613 * @param con_handle 614 * @param descriptor_handle 615 * @param offset 616 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 617 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 618 * ERROR_CODE_SUCCESS if query is successfully registered 619 */ 620 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); 621 622 /** 623 * @brief Writes the characteristic descriptor using its handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 624 * @param callback 625 * @param con_handle 626 * @param descriptor 627 * @param length of data 628 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 629 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 630 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 631 * ERROR_CODE_SUCCESS if query is successfully registered 632 */ 633 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 length, uint8_t * data); 634 635 /** 636 * @brief Writes the characteristic descriptor using its handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 637 * @param callback 638 * @param con_handle 639 * @param descriptor_handle 640 * @param length of data 641 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 642 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 643 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 644 * ERROR_CODE_SUCCESS if query is successfully registered 645 */ 646 uint8_t gatt_client_write_characteristic_descriptor_using_descriptor_handle(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t descriptor_handle, uint16_t length, uint8_t * data); 647 648 /** 649 * @brief Writes the characteristic descriptor using its handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 650 * @param callback 651 * @param con_handle 652 * @param descriptor 653 * @param length of data 654 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 655 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 656 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 657 * ERROR_CODE_SUCCESS if query is successfully registered 658 */ 659 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 length, uint8_t * data); 660 661 /** 662 * @brief Writes the characteristic descriptor using its handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 663 * @param callback 664 * @param con_handle 665 * @param descriptor_handle 666 * @param length of data 667 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 668 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 669 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 670 * ERROR_CODE_SUCCESS if query is successfully registered 671 */ 672 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 length, uint8_t * data); 673 674 /** 675 * @brief Writes the characteristic descriptor using its handle. The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. 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). 676 * @param callback 677 * @param con_handle 678 * @param descriptor_handle 679 * @param offset of value 680 * @param length of data 681 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 682 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 683 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 684 * ERROR_CODE_SUCCESS if query is successfully registered 685 */ 686 uint8_t gatt_client_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 length, uint8_t * data); 687 688 /** 689 * @brief Writes the client characteristic configuration of the specified characteristic. It is used to subscribe for notifications or indications of the characteristic value. 690 * For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 691 * The gatt_complete_event_t with type set to GATT_EVENT_QUERY_COMPLETE, marks the end of write. The write is successfully performed, if the event's att_status field is set to ATT_ERROR_SUCCESS 692 * (see bluetooth.h for ATT_ERROR codes). 693 * @param callback 694 * @param con_handle 695 * @param characteristic 696 * @param configuration GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION, GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 697 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 698 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 699 * GATT_CLIENT_CHARACTERISTIC_NOTIFICATION_NOT_SUPPORTED if configuring notification, but characteristic has no notification property set 700 * GATT_CLIENT_CHARACTERISTIC_INDICATION_NOT_SUPPORTED if configuring indication, but characteristic has no indication property set 701 * ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if configuration is invalid 702 * ERROR_CODE_SUCCESS if query is successfully registered 703 */ 704 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); 705 706 /** 707 * @brief Register for notifications and indications of a characteristic enabled by gatt_client_write_client_characteristic_configuration 708 * @param notification struct used to store registration 709 * @param callback 710 * @param con_handle or GATT_CLIENT_ANY_CONNECTION to receive updates from all connected devices 711 * @param characteristic or NULL to receive updates for all characteristics 712 */ 713 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); 714 715 /** 716 * @brief Stop listening to characteristic value updates registered with gatt_client_listen_for_characteristic_value_updates 717 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 718 */ 719 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 720 721 /** 722 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees a single successful gatt_client_write_value_of_characteristic_without_response 723 * @param callback 724 * @param con_handle 725 * @returns status 726 */ 727 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 728 729 /** 730 * @brief Transactional write. It can be called as many times as it is needed to write the characteristics within the same transaction. Call gatt_client_execute_write to commit the transaction. 731 * @param callback 732 * @param con_handle 733 * @param attribute_handle 734 * @param offset of value 735 * @param length of data 736 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 737 */ 738 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 length, uint8_t * data); 739 740 /** 741 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 742 * @param callback 743 * @param con_handle 744 */ 745 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 746 747 /** 748 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 749 * @param callback 750 * @param con_handle 751 */ 752 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 753 754 /* API_END */ 755 756 // used by generated btstack_event.c 757 758 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t *service); 759 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 760 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 761 762 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 763 void gatt_client_att_packet_handler_fuzz(uint8_t packet_type, uint16_t handle, uint8_t *packet, uint16_t size); 764 #endif 765 766 #if defined __cplusplus 767 } 768 #endif 769 770 #endif 771