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