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 #ifdef ENABLE_GATT_CLIENT_PAIRING 191 uint8_t security_counter; 192 uint8_t wait_for_pairing_complete; 193 uint8_t pending_error_code; 194 #endif 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 MTU is available after the first query has completed. If status is equal to 0, it returns the real value, otherwise the default value of 23. 236 * @param con_handle 237 * @param mtu 238 */ 239 240 uint8_t gatt_client_get_mtu(hci_con_handle_t con_handle, uint16_t * mtu); 241 242 /** 243 * @brief Sets whether a MTU Exchange Request shall be automatically send before the first attribute read request is send. Default is enabled. 244 * @param enabled 245 */ 246 void gatt_client_mtu_enable_auto_negotiation(uint8_t enabled); 247 248 /** 249 * @brief Sends a MTU Exchange Request, this allows for the client to exchange MTU when gatt_client_mtu_enable_auto_negotiation is disabled. 250 * @param callback 251 * @param con_handle 252 */ 253 void gatt_client_send_mtu_negotiation(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 254 255 /** 256 * @brief Returns if the GATT client is ready to receive a query. It is used with daemon. 257 * @param con_handle 258 */ 259 int gatt_client_is_ready(hci_con_handle_t con_handle); 260 261 /** 262 * @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. 263 * @param callback 264 * @param con_handle 265 */ 266 uint8_t gatt_client_discover_primary_services(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 267 268 /** 269 * @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. 270 * @param callback 271 * @param con_handle 272 * @param uuid16 273 */ 274 uint8_t gatt_client_discover_primary_services_by_uuid16(btstack_packet_handler_t callback, hci_con_handle_t con_handle, uint16_t uuid16); 275 276 /** 277 * @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. 278 * @param callback 279 * @param con_handle 280 * @param uuid128 281 */ 282 uint8_t gatt_client_discover_primary_services_by_uuid128(btstack_packet_handler_t callback, hci_con_handle_t con_handle, const uint8_t * uuid128); 283 284 /** 285 * @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. 286 * @param callback 287 * @param con_handle 288 * @param service 289 */ 290 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); 291 292 /** 293 * @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. 294 * @param callback 295 * @param con_handle 296 * @param service 297 */ 298 uint8_t gatt_client_discover_characteristics_for_service(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_service_t *service); 299 300 /** 301 * @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. 302 * @param callback 303 * @param con_handle 304 * @param start_handle 305 * @param end_handle 306 * @param uuid16 307 */ 308 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); 309 310 /** 311 * @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. 312 * @param callback 313 * @param con_handle 314 * @param start_handle 315 * @param end_handle 316 * @param uuid128 317 */ 318 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); 319 320 /** 321 * @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. 322 * @param callback 323 * @param con_handle 324 * @param service 325 * @param uuid16 326 */ 327 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); 328 329 /** 330 * @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. 331 * @param callback 332 * @param con_handle 333 * @param service 334 * @param uuid128 335 */ 336 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); 337 338 /** 339 * @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. 340 * @param callback 341 * @param con_handle 342 * @param characteristic 343 */ 344 uint8_t gatt_client_discover_characteristic_descriptors(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t *characteristic); 345 346 /** 347 * @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. 348 * @param callback 349 * @param con_handle 350 * @param characteristic 351 */ 352 uint8_t gatt_client_read_value_of_characteristic(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_t *characteristic); 353 354 /** 355 * @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. 356 * @param callback 357 * @param con_handle 358 * @param characteristic_value_handle 359 */ 360 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); 361 362 /** 363 * @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. 364 * @param callback 365 * @param con_handle 366 * @param start_handle 367 * @param end_handle 368 * @param uuid16 369 */ 370 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); 371 372 /** 373 * @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. 374 * @param callback 375 * @param con_handle 376 * @param start_handle 377 * @param end_handle 378 * @param uuid128 379 */ 380 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); 381 382 /** 383 * @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. 384 * @param callback 385 * @param con_handle 386 * @param characteristic 387 */ 388 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); 389 390 /** 391 * @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. 392 * @param callback 393 * @param con_handle 394 * @param characteristic_value_handle 395 */ 396 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); 397 398 /** 399 * @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. 400 * @param callback 401 * @param con_handle 402 * @param characteristic_value_handle 403 * @param offset 404 */ 405 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); 406 407 /* 408 * @brief Read multiple characteristic values 409 * @param callback 410 * @param con_handle 411 * @param num_value_handles 412 * @param value_handles list of handles 413 */ 414 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); 415 416 /** 417 * @brief Writes the characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 418 * @param con_handle 419 * @param characteristic_value_handle 420 * @param length of data 421 * @param data is not copied, make sure memory is accessible until write is done 422 */ 423 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); 424 425 /** 426 * @brief Writes the authenticated characteristic value using the characteristic's value handle without an acknowledgment that the write was successfully performed. 427 * @note GATT_EVENT_QUERY_COMPLETE is emitted with 0 for success or ATT_ERROR_BONDING_INFORMATION_MISSING if there is no bonding information stored 428 * @param callback 429 * @param con_handle 430 * @param value_handle 431 * @param message_len 432 * @param message is not copied, make sure memory is accessible until write is done 433 */ 434 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); 435 436 /** 437 * @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 status field is set to 0. 438 * @param callback 439 * @param con_handle 440 * @param characteristic_value_handle 441 * @param length of data 442 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 443 */ 444 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); 445 446 /** 447 * @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 status field is set to 0. 448 * @param callback 449 * @param con_handle 450 * @param characteristic_value_handle 451 * @param length of data 452 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 453 */ 454 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); 455 456 /** 457 * @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 status field is set to 0. 458 * @param callback 459 * @param con_handle 460 * @param characteristic_value_handle 461 * @param offset of value 462 * @param length of data 463 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 464 */ 465 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); 466 467 /** 468 * @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 status field is set to 0. 469 * @param callback 470 * @param con_handle 471 * @param characteristic_value_handle 472 * @param length of data 473 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 474 */ 475 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); 476 477 /** 478 * @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. 479 * @param callback 480 * @param con_handle 481 * @param descriptor 482 */ 483 uint8_t gatt_client_read_characteristic_descriptor(btstack_packet_handler_t callback, hci_con_handle_t con_handle, gatt_client_characteristic_descriptor_t * descriptor); 484 485 /** 486 * @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. 487 * @param callback 488 * @param con_handle 489 * @param descriptor 490 */ 491 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); 492 493 /** 494 * @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. 495 * @param callback 496 * @param con_handle 497 * @param descriptor_handle 498 */ 499 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); 500 501 /** 502 * @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. 503 * @param callback 504 * @param con_handle 505 * @param descriptor_handle 506 */ 507 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); 508 509 /** 510 * @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. 511 * @param callback 512 * @param con_handle 513 * @param descriptor_handle 514 * @param offset 515 */ 516 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); 517 518 /** 519 * @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 status field is set to 0. 520 * @param callback 521 * @param con_handle 522 * @param descriptor 523 * @param length of data 524 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 525 */ 526 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); 527 528 /** 529 * @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 status field is set to 0. 530 * @param callback 531 * @param con_handle 532 * @param descriptor_handle 533 * @param length of data 534 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 535 */ 536 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); 537 538 /** 539 * @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 status field is set to 0. 540 * @param callback 541 * @param con_handle 542 * @param descriptor 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 */ 546 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); 547 548 /** 549 * @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 status field is set to 0. 550 * @param callback 551 * @param con_handle 552 * @param descriptor_handle 553 * @param length of data 554 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 555 */ 556 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); 557 558 /** 559 * @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 status field is set to 0. 560 * @param callback 561 * @param con_handle 562 * @param descriptor_handle 563 * @param offset of value 564 * @param length of data 565 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 566 */ 567 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); 568 569 /** 570 * @brief Writes the client characteristic configuration of the specified characteristic. It is used to subscribe for notifications or indications of the characteristic value. For notifications or indications specify: GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_NOTIFICATION resp. GATT_CLIENT_CHARACTERISTICS_CONFIGURATION_INDICATION as configuration value. 571 * @param callback 572 * @param con_handle 573 * @param characteristic 574 * @param configuration 575 */ 576 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); 577 578 /** 579 * @brief Register for notifications and indications of a characteristic enabled by gatt_client_write_client_characteristic_configuration 580 * @param notification struct used to store registration 581 * @param callback 582 * @param con_handle 583 * @param characteristic 584 */ 585 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); 586 587 /** 588 * @brief Stop listening to characteristic value updates registered with gatt_client_listen_for_characteristic_value_updates 589 * @param notification struct used in gatt_client_listen_for_characteristic_value_updates 590 */ 591 void gatt_client_stop_listening_for_characteristic_value_updates(gatt_client_notification_t * notification); 592 593 /** 594 * @brief Requests GATT_EVENT_CAN_WRITE_WITHOUT_RESPONSE that guarantees a single successful gatt_client_write_value_of_characteristic_without_response 595 * @param callback 596 * @param con_handle 597 * @returns status 598 */ 599 uint8_t gatt_client_request_can_write_without_response_event(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 600 601 /** 602 * @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. 603 * @param callback 604 * @param con_handle 605 * @param attribute_handle 606 * @param offset of value 607 * @param length of data 608 * @param data is not copied, make sure memory is accessible until write is done, i.e. GATT_EVENT_QUERY_COMPLETE is received 609 */ 610 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); 611 612 /** 613 * @brief Commit transactional write. GATT_EVENT_QUERY_COMPLETE is received. 614 * @param callback 615 * @param con_handle 616 */ 617 uint8_t gatt_client_execute_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 618 619 /** 620 * @brief Abort transactional write. GATT_EVENT_QUERY_COMPLETE is received. 621 * @param callback 622 * @param con_handle 623 */ 624 uint8_t gatt_client_cancel_write(btstack_packet_handler_t callback, hci_con_handle_t con_handle); 625 626 /* API_END */ 627 628 // used by generated btstack_event.c 629 630 void gatt_client_deserialize_service(const uint8_t *packet, int offset, gatt_client_service_t *service); 631 void gatt_client_deserialize_characteristic(const uint8_t * packet, int offset, gatt_client_characteristic_t * characteristic); 632 void gatt_client_deserialize_characteristic_descriptor(const uint8_t * packet, int offset, gatt_client_characteristic_descriptor_t * descriptor); 633 634 #if defined __cplusplus 635 } 636 #endif 637 638 #endif 639