1 /* 2 * Copyright (c) 2022 Winner Microelectronics Co., Ltd. All rights reserved. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @file wm_ble_gatt.h 18 * 19 * @brief Bluetooth API 20 * 21 * @author WinnerMicro 22 * 23 * Copyright (c) 2020 Winner Microelectronics Co., Ltd. 24 */ 25 #ifndef WM_BLE_GATT_H 26 #define WM_BLE_GATT_H 27 28 #include "wm_bt_def.h" 29 30 /** 31 * @defgroup BT_APIs Bluetooth APIs 32 * @brief Bluetooth related APIs 33 */ 34 35 /** 36 * @addtogroup BT_APIs 37 * @{ 38 */ 39 40 /** 41 * @defgroup BLE_GATT_Client_APIs BLE GATT Client APIs 42 * @brief BLE GATT Client APIs 43 */ 44 45 /** 46 * @addtogroup BLE_GATT_Client_APIs 47 * @{ 48 */ 49 50 /** 51 * @brief initialize the btif_gatt_client callback function 52 * 53 * @param[in] *p_callback pointer on callback function 54 * 55 * @retval @ref tls_bt_status_t 56 * 57 * @note None 58 */ 59 tls_bt_status_t tls_ble_client_app_init(tls_ble_callback_t callback); 60 61 /** 62 * @brief free the tls_ble_callback_t pointer 63 * 64 * @param None 65 * 66 * @retval @ref tls_bt_status_t 67 * 68 * @note None 69 */ 70 tls_bt_status_t tls_ble_client_app_deinit(void); 71 72 /** 73 * @brief this function is called to register client application 74 * 75 * @param[in] *uuid pointer on uuid 76 * 77 * @retval @ref tls_bt_status_t 78 * 79 * @note None 80 */ 81 tls_bt_status_t tls_ble_client_app_register(tls_bt_uuid_t *uuid); 82 83 /** 84 * @brief this function is called to unregister client application 85 * 86 * @param[in] client_if gatt client access interface 87 * 88 * @retval @ref tls_bt_status_t 89 * 90 * @note None 91 */ 92 tls_bt_status_t tls_ble_client_app_unregister(uint8_t client_if); 93 94 /** 95 * @brief this function is called to open an BLE connection to a remote 96 * device or add a background auto connection 97 * 98 * @param[in] client_if gatt client access interface 99 * @param[in] *bd_addr remote device bluetooth device address 100 * @param[in] is_direct direct connection or background auto connection 101 * @param[in] transport specific BLE/BR-EDR/mixed 102 * 103 * @retval @ref tls_bt_status_t 104 * 105 * @note None 106 */ 107 tls_bt_status_t tls_ble_client_connect(uint8_t client_if, const tls_bt_addr_t *bd_addr, 108 uint8_t is_direct, int transport); 109 110 /** 111 * @brief this function is called to disconnect with gatt server connection 112 * 113 * @param[in] client_if gatt client access interface 114 * @param[in] *bd_addr remote device bluetooth device address 115 * @param[in] conn_id connection ID to be closed 116 * 117 * @retval @ref tls_bt_status_t 118 * 119 * @note None 120 */ 121 tls_bt_status_t tls_ble_client_disconnect(uint8_t client_if, const tls_bt_addr_t *bd_addr, int conn_id); 122 123 /** 124 * @brief start or stop advertisements to listen for incoming connections 125 * 126 * @param[in] client_if gatt client access interface 127 * @param[in] start start: 1; stop 0 128 * 129 * @retval @ref tls_bt_status_t 130 * 131 * @note None 132 */ 133 tls_bt_status_t tls_ble_client_listen(uint8_t client_if, uint8_t start); 134 135 /** 136 * @brief clear the attribute cache for a given device 137 * 138 * @param[in] client_if gatt client access interface 139 * @param[in] *bd_addr remote device address 140 * 141 * @retval @ref tls_bt_status_t 142 * 143 * @note None 144 */ 145 tls_bt_status_t tls_ble_client_refresh(uint8_t client_if, const tls_bt_addr_t *bd_addr); 146 147 /** 148 * @brief enumerate all GATT services on a connected device 149 * 150 * @param[in] conn_id connection indicator return value when connected 151 * @param[in] *filter_uuid filter this uuid 152 * 153 * @retval @ref tls_bt_status_t 154 * 155 * @note Optionally, the results can be filtered for a given UUID 156 */ 157 tls_bt_status_t tls_ble_client_search_service(uint16_t conn_id, tls_bt_uuid_t *filter_uuid); 158 159 /** 160 * @brief write a remote characteristic 161 * 162 * @param[in] conn_id connection indicator return value when connected 163 * @param[in] handle the character attribute handle 164 * @param[in] write_type the type of attribute write operation 165 * @param[in] len length of the value to be written 166 * @param[in] auth_req authentication request 167 * @param[in] *p_value the value to be written 168 * 169 * @retval @ref tls_bt_status_t 170 * 171 * @note None 172 */ 173 tls_bt_status_t tls_ble_client_write_characteristic(uint16_t conn_id, uint16_t handle, 174 int write_type, int len, int auth_req, char *p_value); 175 176 /** 177 * @brief read a characteristic on a remote device 178 * 179 * @param[in] conn_id connection indicator return value when connected 180 * @param[in] handle the character attribute handle 181 * @param[in] auth_req authentication request 182 * 183 * @retval @ref tls_bt_status_t 184 * 185 * @note None 186 */ 187 tls_bt_status_t tls_ble_client_read_characteristic(uint16_t conn_id, uint16_t handle, int auth_req); 188 189 /** 190 * @brief read the descriptor for a given characteristic 191 * 192 * @param[in] conn_id connection indicator return value when connected 193 * @param[in] handle the character attribute handle 194 * @param[in] auth_req authentication request 195 * 196 * @retval @ref tls_bt_status_t 197 * 198 * @note None 199 */ 200 tls_bt_status_t tls_ble_client_read_descriptor(uint16_t conn_id, uint16_t handle, int auth_req); 201 202 /** 203 * @brief write a remote descriptor for a given characteristic 204 * 205 * @param[in] conn_id connection indicator return value when connected 206 * @param[in] handle the character attribute handle 207 * @param[in] write_type the type of attribute write operation 208 * @param[in] len length of the value to be written 209 * @param[in] auth_req authentication request 210 * @param[in] *p_value the value to be written 211 * 212 * @retval @ref tls_bt_status_t 213 * 214 * @note None 215 */ 216 tls_bt_status_t tls_ble_client_write_descriptor(uint16_t conn_id, uint16_t handle, 217 int write_type, int len, int auth_req, char *p_value); 218 219 /** 220 * @brief execute a prepared write operation 221 * 222 * @param[in] conn_id connection indicator return value when connected 223 * @param[in] execute execute or cancel 224 * 225 * @retval @ref tls_bt_status_t 226 * 227 * @note None 228 */ 229 tls_bt_status_t tls_ble_client_execute_write(uint16_t conn_id, int execute); 230 231 /** 232 * @brief Register to receive notifications or indications for a given 233 * characteristic 234 * 235 * @param[in] client_if gatt client access interface 236 * @param[in] *bd_addr the target server address 237 * @param[in] handle the attribute handle of characteristic 238 * @param[in] conn_id the connection id 239 * 240 * @retval @ref tls_bt_status_t 241 * 242 * @note None 243 */ 244 tls_bt_status_t tls_ble_client_register_for_notification(int client_if, const tls_bt_addr_t *bd_addr, 245 uint16_t handle, uint16_t conn_id); 246 247 /** 248 * @brief deregister a previous request for notifications/indications 249 * 250 * @param[in] client_if gatt client access interface 251 * @param[in] *bd_addr the target server address 252 * @param[in] handle the attribute handle of characteristic 253 * 254 * @retval @ref tls_bt_status_t 255 * 256 * @note None 257 */ 258 tls_bt_status_t tls_ble_client_deregister_for_notification(int client_if, const tls_bt_addr_t *bd_addr, 259 uint16_t handle, uint16_t conn_id); 260 261 /** 262 * @brief configure the MTU for a given connection 263 * 264 * @param[in] conn_id connection indicator return value when connected 265 * @param[in] mtu the max transmit unit of this connection 266 * 267 * @retval @ref tls_bt_status_t 268 * 269 * @note None 270 */ 271 tls_bt_status_t tls_ble_client_configure_mtu(uint16_t conn_id, uint16_t mtu); 272 273 /** 274 * @brief get gatt db content 275 * 276 * @param[in] conn_id connection indicator return value when connected 277 * 278 * @retval @ref tls_bt_status_t 279 * 280 * @note None 281 */ 282 tls_bt_status_t tls_ble_client_get_gatt_db(uint16_t conn_id); 283 284 /** 285 * @} 286 */ 287 288 /** 289 * @defgroup BLE_GATT_Server_APIs BLE GATT Server APIs 290 * @brief BLE GATT Server APIs 291 */ 292 293 /** 294 * @addtogroup BLE_GATT_Server_APIs 295 * @{ 296 */ 297 298 /** 299 * @brief initialize the btif_gatt_server callback function 300 * 301 * @param[in] *p_callback pointer on callback function 302 * 303 * @retval @ref tls_bt_status_t 304 * 305 * @note None 306 */ 307 tls_bt_status_t tls_ble_server_app_init(tls_ble_callback_t callback); 308 309 /******************************************************************************* 310 ** 311 ** Function tls_ble_server_app_deinit 312 ** 313 ** Description free the tls_ble_callback_t pointer 314 ** 315 ** Parameters None 316 ** 317 ** Returns TLS_BT_STATUS_SUCCESS 318 ** TLS_BT_STATUS_DONE 319 ** 320 *******************************************************************************/ 321 tls_bt_status_t tls_ble_server_app_deinit(void); 322 323 /** 324 * @brief this function is called to register server application 325 * 326 * @param[in] *uuid pointer on uuid 327 * 328 * @retval @ref tls_bt_status_t 329 * 330 * @note None 331 */ 332 tls_bt_status_t tls_ble_server_app_register(tls_bt_uuid_t *uuid); 333 334 /** 335 * @brief this function is called to unregister server application 336 * 337 * @param[in] server_if assigned after app registering 338 * 339 * @retval @ref tls_bt_status_t 340 * 341 * @note None 342 */ 343 tls_bt_status_t tls_ble_server_app_unregister(uint8_t server_if); 344 345 /** 346 * @brief create a new service 347 * 348 * @param[in] server_if the gatt server access interface created by app register 349 * @param[in] inst_id instance identifier of this service 350 * @param[in] primay is primary or not service 351 * @param[in] *uuid the id property of this service 352 * @param[in] num_handles number of handle requested for this service 353 * 354 * @retval @ref tls_bt_status_t 355 * 356 * @note None 357 */ 358 tls_bt_status_t tls_ble_server_add_service(uint8_t server_if, int inst_id, int primay, 359 tls_bt_uuid_t *uuid, int num_handles); 360 361 /** 362 * @brief add a characteristic to a service 363 * 364 * @param[in] server_if the gatt server access interface created by app register 365 * @param[in] service_handle the handle of this service assigned when creating a service 366 * @param[in] *uuid the id property of this characteristic 367 * @param[in] properties access properties 368 * @param[in] permission access permission 369 * 370 * @retval @ref tls_bt_status_t 371 * 372 * @note None 373 */ 374 tls_bt_status_t tls_ble_server_add_characteristic(uint8_t server_if, uint16_t service_handle, 375 tls_bt_uuid_t *uuid, int properties, int permission); 376 377 /** 378 * @brief add a descriptor to a given service 379 * 380 * @param[in] server_if the gatt server access interface created by app register 381 * @param[in] service_handle the handle of this service assigned when creating a service 382 * @param[in] *uuid the id property of this characteristic 383 * @param[in] permission access permission 384 * 385 * @retval @ref tls_bt_status_t 386 * 387 * @note None 388 */ 389 tls_bt_status_t tls_ble_server_add_descriptor(uint8_t server_if, uint16_t service_handle, 390 tls_bt_uuid_t *uuid, int permissions); 391 392 /** 393 * @brief starts a local service 394 * 395 * @param[in] server_if the gatt server access interface created by app register 396 * @param[in] service_handle the handle of this service assigned when creating a service 397 * @param[in] transport tranport type, BLE/BR-EDR/MIXED 398 * 399 * @retval @ref tls_bt_status_t 400 * 401 * @note None 402 */ 403 tls_bt_status_t tls_ble_server_start_service(uint8_t server_if, uint16_t service_handle, int transport); 404 405 /** 406 * @brief stop a local service 407 * 408 * @param[in] server_if the gatt server access interface created by app register 409 * @param[in] service_handle the handle of this service assigned when creating a service 410 * 411 * @retval @ref tls_bt_status_t 412 * 413 * @note None 414 */ 415 tls_bt_status_t tls_ble_server_stop_service(uint8_t server_if, uint16_t service_handle); 416 417 /** 418 * @brief delete a local service 419 * 420 * @param[in] server_if the gatt server access interface created by app register 421 * @param[in] service_handle the handle of this service assigned when creating a service 422 * 423 * @retval @ref tls_bt_status_t 424 * 425 * @note None 426 */ 427 tls_bt_status_t tls_ble_server_delete_service(uint8_t server_if, uint16_t service_handle); 428 429 /** 430 * @brief create a connection to a remote peripheral 431 * 432 * @param[in] server_if the gatt server access interface created by app register 433 * @param[in] *bd_addr the remote device address 434 * @param[in] is_direct true direct connection; false: background auto connection 435 * @param[in] transport tranport type, BLE/BR-EDR/MIXED 436 * 437 * @retval @ref tls_bt_status_t 438 * 439 * @note None 440 */ 441 tls_bt_status_t tls_ble_server_connect(uint8_t server_if, const tls_bt_addr_t *bd_addr, 442 uint8_t is_direct, int transport); 443 444 /** 445 * @brief disconnect an established connection or cancel a pending one 446 * 447 * @param[in] server_if the gatt server access interface created by app register 448 * @param[in] *bd_addr the remote device address 449 * @param[in] conn_id connection id create when connection established 450 * 451 * @retval @ref tls_bt_status_t 452 * 453 * @note None 454 */ 455 tls_bt_status_t tls_ble_server_disconnect(uint8_t server_if, const tls_bt_addr_t *bd_addr, uint16_t conn_id); 456 457 /** 458 * @brief send value indication to a remote device 459 * 460 * @param[in] server_if the gatt server access interface created by app register 461 * @param[in] attribute_handle the handle of characteristic 462 * @param[in] conn_id connection id create when connection established 463 * @param[in] len the length of value to be sent 464 * @param[in] confirm need the remote device acked after receive the message , normally 465 * Whether a confirmation is required. FALSE sends a GATT notification, 466 * TRUE sends a GATT indication 467 * @param[in] *p_value the value to be written 468 * 469 * @retval @ref tls_bt_status_t 470 * 471 * @note None 472 */ 473 tls_bt_status_t tls_ble_server_send_indication(uint8_t server_if, uint16_t attribute_handle, 474 uint16_t conn_id, int len, int confirm, 475 char *p_value); 476 477 /** 478 * @brief send a response to a read/write operation 479 * 480 * @param[in] conn_id connection id create when connection established 481 * @param[in] trans_id the transation identifier 482 * @param[in] status 483 * @param[in] offset the offset the fragmented value 484 * @param[in] attr_handle the attribute handle 485 * @param[in] auth_req access properties 486 * @param[in] *p_value the value to be written 487 * @param[in] len the length of value to be written 488 * 489 * @retval @ref tls_bt_status_t 490 * 491 * @note None 492 */ 493 tls_bt_status_t tls_ble_server_send_response(uint16_t conn_id, uint32_t trans_id, uint8_t status, 494 int offset, uint16_t attr_handle, int auth_req, 495 uint8_t *p_value, int len); 496 497 /** 498 * @} 499 */ 500 501 /** 502 * @} 503 */ 504 505 #endif /* WM_BLE_GATT_H */ 506 507