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 } gatt_client_t; 200 201 typedef struct gatt_client_notification { 202 btstack_linked_item_t item; 203 btstack_packet_handler_t callback; 204 hci_con_handle_t con_handle; 205 uint16_t attribute_handle; 206 } gatt_client_notification_t; 207 208 /* API_START */ 209 210 typedef struct { 211 uint16_t start_group_handle; 212 uint16_t end_group_handle; 213 uint16_t uuid16; 214 uint8_t uuid128[16]; 215 } gatt_client_service_t; 216 217 typedef struct { 218 uint16_t start_handle; 219 uint16_t value_handle; 220 uint16_t end_handle; 221 uint16_t properties; 222 uint16_t uuid16; 223 uint8_t uuid128[16]; 224 } gatt_client_characteristic_t; 225 226 typedef struct { 227 uint16_t handle; 228 uint16_t uuid16; 229 uint8_t uuid128[16]; 230 } gatt_client_characteristic_descriptor_t; 231 232 /** 233 * @brief Set up GATT client. 234 */ 235 void gatt_client_init(void); 236 237 /** 238 * @brief Set minimum required security level for GATT Client 239 * @note The Bluetooth specification makes the GATT Server responsible to check for security. 240 * This allows an attacker to spoof existing devices with GATT Servers, but skip the authentication part 241 * If your application is exchanging sensitive data from a remote device, you would need to manually check 242 * the security level before sending/receive such data. This function allows to have the GATT Client post-pone 243 * any exchange until the required security level is established. 244 * @pram level, default LEVEL_0 (no encryption required) 245 */ 246 void gatt_client_set_required_security_level(gap_security_level_t level); 247 248 /** 249 * @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). 250 * @param con_handle 251 * @param mtu 252 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 253 * GATT_CLIENT_IN_WRONG_STATE if MTU is not exchanged and MTU auto-exchange is disabled 254 * ERROR_CODE_SUCCESS if query is successfully registered 255 */ 256 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 257 258 /** 259 * @brief Sets whether a MTU Exchange Request shall be automatically send before the first attribute read request is send. Default is enabled. 260 * @param enabled 261 */ 262 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 263 264 /** 265 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU when gatt_client_mtu_enable_auto_negotiation is disabled. 266 * @param callback 267 * @param con_handle 268 */ 269 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 270 271 /** 272 * @brief Returns if the GATT client is ready to receive a query. It is used with daemon. 273 * @param con_handle 274 * @return is_ready_status 0 - if no GATT client for con_handle is found, or is not ready, otherwise 1 275 */ 276 int gatt_client_is_ready(hci_con_handle_t con_handle); 277 278 /** 279 * @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. 280 * @param callback 281 * @param con_handle 282 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 283 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 284 * ERROR_CODE_SUCCESS , if query is successfully registered 285 */ 286 uint8_t gatt_client_discover_primary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 287 288 /** 289 * @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. 290 * @param callback 291 * @param con_handle 292 * @param uuid16 293 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 294 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 295 * ERROR_CODE_SUCCESS , if query is successfully registered 296 */ 297 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 298 299 /** 300 * @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. 301 * @param callback 302 * @param con_handle 303 * @param uuid128 304 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 305 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 306 * ERROR_CODE_SUCCESS , if query is successfully registered 307 */ 308 uint8_t gatt_client_discover_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 309 310 /** 311 * @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. 312 * @param callback 313 * @param con_handle 314 * @param service 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_find_included_services_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t *service); 320 321 /** 322 * @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. 323 * @param callback 324 * @param con_handle 325 * @param service 326 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 327 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 328 * ERROR_CODE_SUCCESS , if query is successfully registered 329 */ 330 uint8_t gatt_client_discover_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t *service); 331 332 /** 333 * @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. 334 * @param callback 335 * @param con_handle 336 * @param start_handle 337 * @param end_handle 338 * @param uuid16 339 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 340 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 341 * ERROR_CODE_SUCCESS , if query is successfully registered 342 */ 343 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); 344 345 /** 346 * @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. 347 * @param callback 348 * @param con_handle 349 * @param start_handle 350 * @param end_handle 351 * @param uuid128 352 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 353 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 354 * ERROR_CODE_SUCCESS , if query is successfully registered 355 */ 356 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); 357 358 /** 359 * @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. 360 * @param callback 361 * @param con_handle 362 * @param service 363 * @param uuid16 364 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 365 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 366 * ERROR_CODE_SUCCESS , if query is successfully registered 367 */ 368 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); 369 370 /** 371 * @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. 372 * @param callback 373 * @param con_handle 374 * @param service 375 * @param uuid128 376 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 377 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 378 * ERROR_CODE_SUCCESS , if query is successfully registered 379 */ 380 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); 381 382 /** 383 * @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. 384 * @param callback 385 * @param con_handle 386 * @param characteristic 387 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 388 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 389 * ERROR_CODE_SUCCESS , if query is successfully registered 390 */ 391 uint8_t gatt_client_discover_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t *characteristic); 392 393 /** 394 * @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. 395 * @param callback 396 * @param con_handle 397 * @param characteristic 398 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 399 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 400 * ERROR_CODE_SUCCESS , if query is successfully registered 401 */ 402 uint8_t gatt_client_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t *characteristic); 403 404 /** 405 * @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. 406 * @param callback 407 * @param con_handle 408 * @param characteristic_value_handle 409 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 410 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 411 * ERROR_CODE_SUCCESS , if query is successfully registered 412 */ 413 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); 414 415 /** 416 * @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. 417 * @param callback 418 * @param con_handle 419 * @param start_handle 420 * @param end_handle 421 * @param uuid16 422 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 423 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 424 * ERROR_CODE_SUCCESS , if query is successfully registered 425 */ 426 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); 427 428 /** 429 * @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. 430 * @param callback 431 * @param con_handle 432 * @param start_handle 433 * @param end_handle 434 * @param uuid128 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_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); 440 441 /** 442 * @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. 443 * @param callback 444 * @param con_handle 445 * @param characteristic 446 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 447 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 448 * ERROR_CODE_SUCCESS , if query is successfully registered 449 */ 450 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); 451 452 /** 453 * @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. 454 * @param callback 455 * @param con_handle 456 * @param characteristic_value_handle 457 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 458 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 459 * ERROR_CODE_SUCCESS , if query is successfully registered 460 */ 461 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); 462 463 /** 464 * @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. 465 * @param callback 466 * @param con_handle 467 * @param characteristic_value_handle 468 * @param offset 469 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 470 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 471 * ERROR_CODE_SUCCESS , if query is successfully registered 472 */ 473 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); 474 475 /* 476 * @brief Read multiple characteristic values 477 * @param callback 478 * @param con_handle 479 * @param num_value_handles 480 * @param value_handles list of handles 481 */ 482 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); 483 484 /** 485 * @brief Writes the characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 486 * @param con_handle 487 * @param characteristic_value_handle 488 * @param length of data 489 * @param data is not copied, make sure memory is accessible until write is done 490 * @return status BTSTACK_MEMORY_ALLOC_FAILED, if no GATT client for con_handle is found 491 * GATT_CLIENT_IN_WRONG_STATE , if GATT client is not ready 492 * BTSTACK_ACL_BUFFERS_FULL , if L2CAP cannot send, there are no free ACL slots 493 * ERROR_CODE_SUCCESS , if query is successfully registered 494 */ 495 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); 496 497 /** 498 * @brief Writes the authenticated characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 499 * @note GATT_EVENT_QUERY_COMPLETE is emitted with 0 for success or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored 500 * @param callback 501 * @param con_handle 502 * @param value_handle 503 * @param message_len 504 * @param message is not copied, make sure memory is accessible until write is done 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_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); 510 511 /** 512 * @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). 513 * @param callback 514 * @param con_handle 515 * @param characteristic_value_handle 516 * @param length of data 517 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 518 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 519 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 520 * ERROR_CODE_SUCCESS if query is successfully registered 521 */ 522 uint8_t gatt_client_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); 523 524 /** 525 * @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). 526 * @param callback 527 * @param con_handle 528 * @param characteristic_value_handle 529 * @param length of data 530 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 531 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 532 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 533 * ERROR_CODE_SUCCESS if query is successfully registered 534 */ 535 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); 536 537 /** 538 * @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). 539 * @param callback 540 * @param con_handle 541 * @param characteristic_value_handle 542 * @param offset of value 543 * @param length of data 544 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 545 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 546 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 547 * ERROR_CODE_SUCCESS if query is successfully registered 548 */ 549 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); 550 551 /** 552 * @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). 553 * @param callback 554 * @param con_handle 555 * @param characteristic_value_handle 556 * @param length of data 557 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 558 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 559 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 560 * ERROR_CODE_SUCCESS if query is successfully registered 561 */ 562 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); 563 564 /** 565 * @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. 566 * @param callback 567 * @param con_handle 568 * @param descriptor 569 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 570 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 571 * ERROR_CODE_SUCCESS if query is successfully registered 572 */ 573 uint8_t gatt_client_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 574 575 /** 576 * @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. 577 * @param callback 578 * @param con_handle 579 * @param descriptor 580 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 581 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 582 * ERROR_CODE_SUCCESS if query is successfully registered 583 */ 584 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); 585 586 /** 587 * @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. 588 * @param callback 589 * @param con_handle 590 * @param descriptor_handle 591 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 592 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 593 * ERROR_CODE_SUCCESS if query is successfully registered 594 */ 595 uint8_t gatt_client_read_long_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 596 597 /** 598 * @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. 599 * @param callback 600 * @param con_handle 601 * @param descriptor_handle 602 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 603 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 604 * ERROR_CODE_SUCCESS if query is successfully registered 605 */ 606 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); 607 608 /** 609 * @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. 610 * @param callback 611 * @param con_handle 612 * @param descriptor_handle 613 * @param offset 614 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 615 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 616 * ERROR_CODE_SUCCESS if query is successfully registered 617 */ 618 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); 619 620 /** 621 * @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). 622 * @param callback 623 * @param con_handle 624 * @param descriptor 625 * @param length of data 626 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 627 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 628 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 629 * ERROR_CODE_SUCCESS if query is successfully registered 630 */ 631 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); 632 633 /** 634 * @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). 635 * @param callback 636 * @param con_handle 637 * @param descriptor_handle 638 * @param length of data 639 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 640 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 641 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 642 * ERROR_CODE_SUCCESS if query is successfully registered 643 */ 644 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); 645 646 /** 647 * @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). 648 * @param callback 649 * @param con_handle 650 * @param descriptor 651 * @param length of data 652 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 653 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 654 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 655 * ERROR_CODE_SUCCESS if query is successfully registered 656 */ 657 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); 658 659 /** 660 * @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). 661 * @param callback 662 * @param con_handle 663 * @param descriptor_handle 664 * @param length of data 665 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 666 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 667 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 668 * ERROR_CODE_SUCCESS if query is successfully registered 669 */ 670 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); 671 672 /** 673 * @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). 674 * @param callback 675 * @param con_handle 676 * @param descriptor_handle 677 * @param offset of value 678 * @param length of data 679 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 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_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); 685 686 /** 687 * @brief Writes the client characteristic configuration of the specified characteristic. It is used to subscribe for notifications or indications of the characteristic value. 688 * For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 689 * 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 690 * (see bluetooth.h for ATT_ERROR codes). 691 * @param callback 692 * @param con_handle 693 * @param characteristic 694 * @param configuration GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION, GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION 695 * @return status BTSTACK_MEMORY_ALLOC_FAILED if no GATT client for con_handle is found 696 * GATT_CLIENT_IN_WRONG_STATE if GATT client is not ready 697 * GATT_CLIENT_CHARACTERISTIC_NOTIFICATION_NOT_SUPPORTED if configuring notification, but characteristic has no notification property set 698 * GATT_CLIENT_CHARACTERISTIC_INDICATION_NOT_SUPPORTED if configuring indication, but characteristic has no indication property set 699 * ERROR_CODE_UNSUPPORTED_FEATURE_OR_PARAMETER_VALUE if configuration is invalid 700 * ERROR_CODE_SUCCESS if query is successfully registered 701 */ 702 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); 703 704 /** 705 * @brief Register for notifications and indications of a characteristic enabled by gatt_client_write_client_characteristic_configuration 706 * @param notification struct used to store registration 707 * @param callback 708 * @param con_handle or GATT_CLIENT_ANY_CONNECTION to receive updates from all connected devices 709 * @param characteristic or NULL to receive updates for all characteristics 710 */ 711 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); 712 713 /** 714 * @brief Stop listening to characteristic value updates registered with gatt_client_listen_for_characteristic_value_updates 715 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 716 */ 717 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 718 719 /** 720 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees a single successful gatt_client_write_value_of_characteristic_without_response 721 * @param callback 722 * @param con_handle 723 * @returns status 724 */ 725 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 726 727 /** 728 * @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. 729 * @param callback 730 * @param con_handle 731 * @param attribute_handle 732 * @param offset of value 733 * @param length of data 734 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 735 */ 736 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); 737 738 /** 739 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 740 * @param callback 741 * @param con_handle 742 */ 743 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 744 745 /** 746 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 747 * @param callback 748 * @param con_handle 749 */ 750 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 751 752 /* API_END */ 753 754 // used by generated btstack_event.c 755 756 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t *service); 757 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 758 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 759 760 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION 761 void gatt_client_att_packet_handler_fuzz(uint8_t packet_type, uint16_t handle, uint8_t *packet, uint16_t size); 762 #endif 763 764 #if defined __cplusplus 765 } 766 #endif 767 768 #endif 769