/** * @file wm_ble_gatt.h * * @brief Bluetooth API * * @author WinnerMicro * * Copyright (c) 2020 Winner Microelectronics Co., Ltd. */ #ifndef WM_BLE_GATT_H #define WM_BLE_GATT_H #include "wm_bt_def.h" /** * @defgroup BT_APIs Bluetooth APIs * @brief Bluetooth related APIs */ /** * @addtogroup BT_APIs * @{ */ /** * @defgroup BLE_GATT_Client_APIs BLE GATT Client APIs * @brief BLE GATT Client APIs */ /** * @addtogroup BLE_GATT_Client_APIs * @{ */ /** * @brief initialize the btif_gatt_client callback function * * @param[in] *p_callback pointer on callback function * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_app_init(tls_ble_callback_t callback); /** * @brief free the tls_ble_callback_t pointer * * @param None * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_app_deinit(void); /** * @brief this function is called to register client application * * @param[in] *uuid pointer on uuid * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_app_register(tls_bt_uuid_t *uuid); /** * @brief this function is called to unregister client application * * @param[in] client_if gatt client access interface * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_app_unregister(uint8_t client_if); /** * @brief this function is called to open an BLE connection to a remote * device or add a background auto connection * * @param[in] client_if gatt client access interface * @param[in] *bd_addr remote device bluetooth device address * @param[in] is_direct direct connection or background auto connection * @param[in] transport specific BLE/BR-EDR/mixed * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_connect(uint8_t client_if, const tls_bt_addr_t *bd_addr, uint8_t is_direct, int transport); /** * @brief this function is called to disconnect with gatt server connection * * @param[in] client_if gatt client access interface * @param[in] *bd_addr remote device bluetooth device address * @param[in] conn_id connection ID to be closed * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_disconnect(uint8_t client_if, const tls_bt_addr_t *bd_addr, int conn_id); /** * @brief start or stop advertisements to listen for incoming connections * * @param[in] client_if gatt client access interface * @param[in] start start: 1; stop 0 * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_listen(uint8_t client_if, uint8_t start); /** * @brief clear the attribute cache for a given device * * @param[in] client_if gatt client access interface * @param[in] *bd_addr remote device address * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_refresh(uint8_t client_if, const tls_bt_addr_t *bd_addr); /** * @brief enumerate all GATT services on a connected device * * @param[in] conn_id connection indicator return value when connected * @param[in] *filter_uuid filter this uuid * * @retval @ref tls_bt_status_t * * @note Optionally, the results can be filtered for a given UUID */ tls_bt_status_t tls_ble_client_search_service(uint16_t conn_id, tls_bt_uuid_t *filter_uuid); /** * @brief write a remote characteristic * * @param[in] conn_id connection indicator return value when connected * @param[in] handle the character attribute handle * @param[in] write_type the type of attribute write operation * @param[in] len length of the value to be written * @param[in] auth_req authentication request * @param[in] *p_value the value to be written * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_write_characteristic(uint16_t conn_id, uint16_t handle, int write_type, int len, int auth_req, char *p_value); /** * @brief read a characteristic on a remote device * * @param[in] conn_id connection indicator return value when connected * @param[in] handle the character attribute handle * @param[in] auth_req authentication request * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_read_characteristic(uint16_t conn_id, uint16_t handle, int auth_req); /** * @brief read the descriptor for a given characteristic * * @param[in] conn_id connection indicator return value when connected * @param[in] handle the character attribute handle * @param[in] auth_req authentication request * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_read_descriptor(uint16_t conn_id, uint16_t handle, int auth_req); /** * @brief write a remote descriptor for a given characteristic * * @param[in] conn_id connection indicator return value when connected * @param[in] handle the character attribute handle * @param[in] write_type the type of attribute write operation * @param[in] len length of the value to be written * @param[in] auth_req authentication request * @param[in] *p_value the value to be written * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_write_descriptor(uint16_t conn_id, uint16_t handle, int write_type, int len, int auth_req, char *p_value); /** * @brief execute a prepared write operation * * @param[in] conn_id connection indicator return value when connected * @param[in] execute execute or cancel * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_execute_write(uint16_t conn_id, int execute); /** * @brief Register to receive notifications or indications for a given * characteristic * * @param[in] client_if gatt client access interface * @param[in] *bd_addr the target server address * @param[in] handle the attribute handle of characteristic * @param[in] conn_id the connection id * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_register_for_notification(int client_if, const tls_bt_addr_t *bd_addr, uint16_t handle, uint16_t conn_id); /** * @brief deregister a previous request for notifications/indications * * @param[in] client_if gatt client access interface * @param[in] *bd_addr the target server address * @param[in] handle the attribute handle of characteristic * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_deregister_for_notification(int client_if, const tls_bt_addr_t *bd_addr, uint16_t handle,uint16_t conn_id); /** * @brief configure the MTU for a given connection * * @param[in] conn_id connection indicator return value when connected * @param[in] mtu the max transmit unit of this connection * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_configure_mtu(uint16_t conn_id, uint16_t mtu); /** * @brief get gatt db content * * @param[in] conn_id connection indicator return value when connected * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_client_get_gatt_db(uint16_t conn_id); /** * @} */ /** * @defgroup BLE_GATT_Server_APIs BLE GATT Server APIs * @brief BLE GATT Server APIs */ /** * @addtogroup BLE_GATT_Server_APIs * @{ */ /** * @brief initialize the btif_gatt_server callback function * * @param[in] *p_callback pointer on callback function * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_app_init(tls_ble_callback_t callback); /******************************************************************************* ** ** Function tls_ble_server_app_deinit ** ** Description free the tls_ble_callback_t pointer ** ** Parameters None ** ** Returns TLS_BT_STATUS_SUCCESS ** TLS_BT_STATUS_DONE ** *******************************************************************************/ tls_bt_status_t tls_ble_server_app_deinit(); /** * @brief this function is called to register server application * * @param[in] *uuid pointer on uuid * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_app_register(tls_bt_uuid_t *uuid); /** * @brief this function is called to unregister server application * * @param[in] server_if assigned after app registering * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_app_unregister(uint8_t server_if); /** * @brief create a new service * * @param[in] server_if the gatt server access interface created by app register * @param[in] inst_id instance identifier of this service * @param[in] primay is primary or not service * @param[in] *uuid the id property of this service * @param[in] num_handles number of handle requested for this service * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_add_service(uint8_t server_if, int inst_id, int primay, tls_bt_uuid_t *uuid, int num_handles); /** * @brief add a characteristic to a service * * @param[in] server_if the gatt server access interface created by app register * @param[in] service_handle the handle of this service assigned when creating a service * @param[in] *uuid the id property of this characteristic * @param[in] properties access properties * @param[in] permission access permission * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_add_characteristic(uint8_t server_if, uint16_t service_handle, tls_bt_uuid_t *uuid, int properties, int permission); /** * @brief add a descriptor to a given service * * @param[in] server_if the gatt server access interface created by app register * @param[in] service_handle the handle of this service assigned when creating a service * @param[in] *uuid the id property of this characteristic * @param[in] permission access permission * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_add_descriptor(uint8_t server_if, uint16_t service_handle, tls_bt_uuid_t *uuid, int permissions); /** * @brief starts a local service * * @param[in] server_if the gatt server access interface created by app register * @param[in] service_handle the handle of this service assigned when creating a service * @param[in] transport tranport type, BLE/BR-EDR/MIXED * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_start_service(uint8_t server_if, uint16_t service_handle, int transport); /** * @brief stop a local service * * @param[in] server_if the gatt server access interface created by app register * @param[in] service_handle the handle of this service assigned when creating a service * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_stop_service(uint8_t server_if, uint16_t service_handle); /** * @brief delete a local service * * @param[in] server_if the gatt server access interface created by app register * @param[in] service_handle the handle of this service assigned when creating a service * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_delete_service(uint8_t server_if, uint16_t service_handle); /** * @brief create a connection to a remote peripheral * * @param[in] server_if the gatt server access interface created by app register * @param[in] *bd_addr the remote device address * @param[in] is_direct true direct connection; false: background auto connection * @param[in] transport tranport type, BLE/BR-EDR/MIXED * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_connect(uint8_t server_if, const tls_bt_addr_t *bd_addr, uint8_t is_direct, int transport); /** * @brief disconnect an established connection or cancel a pending one * * @param[in] server_if the gatt server access interface created by app register * @param[in] *bd_addr the remote device address * @param[in] conn_id connection id create when connection established * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_disconnect(uint8_t server_if, const tls_bt_addr_t *bd_addr, uint16_t conn_id); /** * @brief send value indication to a remote device * * @param[in] server_if the gatt server access interface created by app register * @param[in] attribute_handle the handle of characteristic * @param[in] conn_id connection id create when connection established * @param[in] len the length of value to be sent * @param[in] confirm need the remote device acked after receive the message , normally * Whether a confirmation is required. FALSE sends a GATT notification, * TRUE sends a GATT indication * @param[in] *p_value the value to be written * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_send_indication(uint8_t server_if, uint16_t attribute_handle, uint16_t conn_id, int len, int confirm, char *p_value); /** * @brief send a response to a read/write operation * * @param[in] conn_id connection id create when connection established * @param[in] trans_id the transation identifier * @param[in] status TODO: * @param[in] offset the offset the fragmented value * @param[in] attr_handle the attribute handle * @param[in] auth_req access properties * @param[in] *p_value the value to be written * @param[in] len the length of value to be written * * @retval @ref tls_bt_status_t * * @note None */ tls_bt_status_t tls_ble_server_send_response(uint16_t conn_id, uint32_t trans_id, uint8_t status, int offset, uint16_t attr_handle, int auth_req, uint8_t *p_value, int len); /** * @} */ /** * @} */ #endif /* WM_BLE_GATT_H */