/*============================================================================
  Copyright (c) 2022 Quectel Wireless Solution, Co., Ltd.  All Rights Reserved.
  Quectel Wireless Solution Proprietary and Confidential.
 =============================================================================*/


#ifndef _QL_BLE_API_H
#define _QL_BLE_API_H


#include "ql_bt.h"



#ifdef __cplusplus
extern "C" {
#endif




/*****************************************************************
* Function: ql_bt_le_connect
*
* Description:
*   Establishes a LE (Low Energy) connection with the specified device.
*   The `type` parameter defines the address type (e.g., public or random).
*
* Parameters:
*   addr            [in]        Address of the target LE device.
*   type            [in]        Address type of the target device (e.g., public, random).
*
* Return:
*   0                            Connection successful.
*   -1                           Failed to connect.
*
*****************************************************************/
int ql_bt_le_connect(struct bt_addr addr, int type);

/*****************************************************************
* Function: ql_bt_le_disconnect
*
* Description:
*	Disconnects the LE connection identified by the given connection handle.
*
* Parameters:
*	con_handle		[in]		Connection handle of the LE connection.
*
* Return:
*	0							 Disconnection successful.
*	-1							 Failed to disconnect.
*
*****************************************************************/
int ql_bt_le_disconnect(unsigned short con_handle);


/*****************************************************************
* Function: ql_le_get_pair_info
*
* Description:
*	Retrieves the pairing information for a specified index.
*
* Parameters:
*	index			[in]		Index for retrieving pairing information.
*
* Return:
*	0							 Pairing information retrieved successfully.
*	-1							 Failed to retrieve pairing information.
*
*****************************************************************/
int ql_le_get_pair_info(int index);


/*****************************************************************
* Function: ql_le_remove_pair_info
*
* Description:
*	Removes pairing information for a specified index.
*
* Parameters:
*	index			[in]		Index for removing pairing information.
*
* Return:
*	0							 Pairing information removed successfully.
*	-1							 Failed to remove pairing information.
*
*****************************************************************/
int ql_le_remove_pair_info(int index);


/*****************************************************************
* Function: ql_bt_le_set_white_list
*
* Description:
*   Adds a device to the LE white list. The `type` parameter defines
*   the address type of the device (e.g., public or random).
*
* Parameters:
*   addr            [in]        Address of the device to add to the white list.
*   type            [in]        Address type of the device (e.g., public, random).
*
* Return:
*   0                            Device added to the white list successfully.
*   -1                           Failed to add device to the white list.
*
*****************************************************************/
int ql_bt_le_set_white_list(struct bt_addr addr, unsigned char type);

/*****************************************************************
* Function: ql_bt_le_remove_white_list
*
* Description:
*   Removes a device from the LE white list. The `type` parameter
*   defines the address type of the device (e.g., public or random).
*   After removal, the device will no longer be included in the
*   whitelist and cannot participate in whitelist-restricted 
*   Bluetooth operations.
*
* Parameters:
*   addr            [in]        Address of the device to remove from the white list.
*   type            [in]        Address type of the device (e.g., public, random).
*
* Return:
*   0                            Device removed from the white list successfully.
*   -1                           Failed to remove device from the white list.
*
*****************************************************************/
int ql_bt_le_remove_white_list(struct bt_addr addr, unsigned char type);


/*****************************************************************
* Function: ql_bt_le_clear_white_list
*
* Description:
*	Clears all devices from the LE white list.
*
* Parameters:
*	None
*
* Return:
*	0							 White list cleared successfully.
*	-1							 Failed to clear the white list.
*
*****************************************************************/
int ql_bt_le_clear_white_list();

/*****************************************************************
* Function: ql_bt_le_set_random_address
*
* Description:
*	Sets the random address for the LE device.
*
* Parameters:
*	addr			[in]		The random address to be set for the device.
*
* Return:
*	0							 Random address set successfully.
*	-1							 Failed to set random address.
*
*****************************************************************/
int ql_bt_le_set_random_address(struct bt_addr addr);

/*****************************************************************
* Function: ql_le_set_adv_mode
*
* Description:
*	Sets the advertising mode for LE (Low Energy) advertising.
*	The mode is defined by the following enum:
*	- `BT_LE_ADV_LEGACY_MODE`: Legacy advertising mode.
*	- `BT_LE_EXTENDED_ADV_LEGACY_MODE`: Extended legacy advertising mode.
*	- `BT_LE_EXTENDED_ADV_AUX_MODE`: Extended auxiliary advertising mode.
*
* Parameters:
*	le_adv_mode 	[in]		Advertising mode to set (one of the enum values).
*								- `BT_LE_ADV_LEGACY_MODE`: Legacy advertising mode.
*								- `BT_LE_EXTENDED_ADV_LEGACY_MODE`: Extended legacy advertising mode.
*								- `BT_LE_EXTENDED_ADV_AUX_MODE`: Extended auxiliary advertising mode.
*
* Return:
*	None
*
*****************************************************************/
void ql_le_set_adv_mode(uint8_t le_adv_mode);

/*****************************************************************
* Function: ql_bt_le_set_adv_parameters
*
* Description:
*	Sets the advertising parameters for LE (Low Energy) advertising.
*
* Parameters:
*	para			[in]		Pointer to the LE advertising parameters structure.
*
* Return:
*	0							 Parameters set successfully.
*	-1							 Failed to set advertising parameters.
*
*****************************************************************/
int ql_bt_le_set_adv_parameters(struct ql_bt_task_le_adv_parameters *para);





/*****************************************************************
* Function: ql_bt_le_create_adv_data
*
* Description:
*	Creates the advertising data for LE (Low Energy) advertising.
*
* Parameters:
*	gap 			[in]		GAP (Generic Access Profile) type.
*	buffer			[in]		Pointer to the buffer where the advertising data is stored.
*	buffer_size 	[in]		Size of the buffer.
*	data			[in]		Pointer to the actual data to be used in advertising.
*	size			[in]		Size of the advertising data.
*
* Return:
*	0							 Advertising data created successfully.
*	-1							 Failed to create advertising data.
*
*****************************************************************/
int ql_bt_le_create_adv_data(int gap, unsigned char *buffer, int buffer_size, unsigned char *data, int size);


/*****************************************************************
* Function: ql_bt_le_set_adv_data
*
* Description:
*	Sets the advertising data for LE (Low Energy) advertising.
*
* Parameters:
*	data			[in]		Pointer to the advertising data.
*	length			[in]		Length of the advertising data.
*
* Return:
*	0							 Advertising data set successfully.
*	-1							 Failed to set advertising data.
*
*****************************************************************/
int ql_bt_le_set_adv_data(unsigned char *data, unsigned char length);



/*****************************************************************
* Function: ql_le_set_scan_response_data
*
* Description:
*	Sets the scan response data for LE (Low Energy) advertising.
*
* Parameters:
*	data			[in]		Pointer to the scan response data.
*	length			[in]		Length of the scan response data.
*
* Return:
*	0							 Scan response data set successfully.
*	-1							 Failed to set scan response data.
*
*****************************************************************/
int ql_le_set_scan_response_data(unsigned char *data, unsigned char length);


/*****************************************************************
* Function: ql_bt_le_set_ext_adv_parameters
*
* Description:
*	Sets the extended advertising parameters for LE (Low Energy).
*
* Parameters:
*	para			[in]		Pointer to the extended advertising parameters structure.
*
* Return:
*	0							 Extended advertising parameters set successfully.
*	-1							 Failed to set extended advertising parameters.
*
*****************************************************************/
int ql_bt_le_set_ext_adv_parameters(struct bt_task_le_ext_adv_parameters *para);



/*****************************************************************
* Function: ql_bt_le_set_adv_set_random_address
*
* Description:
*	Sets a random address for a specific LE advertising set.
*
* Parameters:
*	handle			[in]		Handle of the advertising set.
*	addr			[in]		Random address to be set for the advertising set.
*
* Return:
*	0							 Random address set successfully.
*	-1							 Failed to set random address.
*
*****************************************************************/
int ql_bt_le_set_adv_set_random_address(unsigned char handle, struct bt_addr addr);

/*****************************************************************
* Function: ql_bt_le_set_ext_adv_data
*
* Description:
*	Sets the extended advertising data for LE (Low Energy) advertising.
*
* Parameters:
*	data			[in]		Pointer to the advertising data.
*	length			[in]		Length of the advertising data.
*	handle			[in]		Handle for the advertising set.
*	operation		[in]		Operation to perform (e.g., insert or update).
*	fragment		[in]		Fragmentation behavior for the data.
*
* Return:
*	0							 Advertising data set successfully.
*	-1							 Failed to set extended advertising data.
*
*****************************************************************/
int ql_bt_le_set_ext_adv_data(unsigned char *data, unsigned char length, unsigned char handle, unsigned char operation, unsigned char fragment);


/*****************************************************************
* Function: ql_bt_le_set_ext_scan_response
*
* Description:
*	Sets the extended scan response data for LE (Low Energy) advertising.
*
* Parameters:
*	data			[in]		Pointer to the scan response data.
*	length			[in]		Length of the scan response data.
*	handle			[in]		Handle for the advertising set.
*	operation		[in]		Operation to perform (e.g., insert or update).
*	fragment		[in]		Fragmentation behavior for the data.
*
* Return:
*	0							 Scan response data set successfully.
*	-1							 Failed to set extended scan response data.
*
*****************************************************************/
int ql_bt_le_set_ext_scan_response(unsigned char *data, unsigned char length, unsigned char handle, unsigned char operation, unsigned char fragment);



/*****************************************************************
* Function: ql_bt_le_set_adv_enable
*
* Description:
*	Enables or disables LE (Low Energy) advertising.
*
* Parameters:
*	enable			[in]		1 to enable advertising, 0 to disable advertising.
*
* Return:
*	0							 Advertising enabled or disabled successfully.
*	-1							 Failed to enable or disable advertising.
*
*****************************************************************/
int ql_bt_le_set_adv_enable(int enable);

/*****************************************************************
* Function: ql_ble_set_adv_cfg_enable
*
* Description:
*	Enables or disables the advertising configuration for LE (Low Energy) advertising.
*
* Parameters:
*	params			[in]		Pointer to the advertising parameters structure.
*	enable			[in]		1 to enable advertising configuration, 0 to disable.
*
* Return:
*	0							 Configuration enabled or disabled successfully.
*	-1							 Failed to enable or disable advertising configuration.
*
*****************************************************************/
int ql_ble_set_adv_cfg_enable(struct ql_bt_adv_params* params, int enable);


/*****************************************************************
* Function: ql_bt_le_set_pair_enable
*
* Description:
*	Enables or disables LE (Low Energy) pairing.
*
* Parameters:
*	set_enable		[in]		1 to enable pairing, 0 to disable pairing.
*
* Return:
*	0							 Pairing enabled or disabled successfully.
*	-1							 Failed to enable or disable pairing.
*
*****************************************************************/
int ql_bt_le_set_pair_enable(unsigned char set_enable);


/*****************************************************************
* Function: ql_bt_le_set_default_phy
*
* Description:
*	Sets the default PHY (physical layer) for LE (Low Energy) connections.
*
* Parameters:
*	all_phys		[in]		PHY for all connections (bitmask of supported PHY types).
*	tx_phys 		[in]		PHY to be used for transmitting (e.g., 1M, 2M, Coded).
*	rx_phys 		[in]		PHY to be used for receiving (e.g., 1M, 2M, Coded).
*
* Return:
*	0							 PHY settings applied successfully.
*	-1							 Failed to set PHY.
*
*****************************************************************/
int ql_bt_le_set_default_phy(unsigned char all_phys, unsigned char tx_phys, unsigned char rx_phys);


/*****************************************************************
* Function: ql_bt_le_register_att_service
*
* Description:
*	Registers an ATT (Attribute Protocol) service with read and write callback functions.
*
* Parameters:
*	profile_data	[in]		Pointer to the profile data for the ATT service.
*	profile_data_len [in]		Length of the profile data.
*	read_callback	[in]		Callback function for handling read requests.
*	write_callback	[in]		Callback function for handling write requests.
*
* Return:
*	0							 Service registered successfully.
*	-1							 Failed to register service.
*
*****************************************************************/
int ql_bt_le_register_att_service(unsigned char *profile_data, unsigned short profile_data_len, att_read_callback_t read_callback, att_write_callback_t write_callback);


/*****************************************************************
* Function: ql_le_send_service_change
*
* Description:
*	Sends a service change notification to the connected device.
*
* Parameters:
*	conn_handle 	[in]		Connection handle for the LE connection.
*
* Return:
*	None
*
*****************************************************************/
void ql_le_send_service_change(unsigned short conn_handle);

/*****************************************************************
* Function: ql_appbt_le_notify
*
* Description:
*	Sends a notification to the client for a given LE (Low Energy) characteristic.
*
* Parameters:
*	conn_handle 	[in]		Connection handle of the LE device.
*	att_handle		[in]		Attribute handle for the characteristic.
*	data			[in]		Pointer to the data to be notified.
*	size			[in]		Size of the data to be notified.
*
* Return:
*	0							 Notification sent successfully.
*	-1							 Failed to send notification.
*
*****************************************************************/
int ql_appbt_le_notify(unsigned short conn_handle, unsigned short att_handle, unsigned char *data, int size);


/*****************************************************************
* Function: ql_appbt_le_indicate
*
* Description:
*	Sends an indication to the client for a given LE (Low Energy) characteristic.
*
* Parameters:
*	conn_handle 	[in]		Connection handle of the LE device.
*	att_handle		[in]		Attribute handle for the characteristic.
*	data			[in]		Pointer to the data to be indicated.
*	size			[in]		Size of the data to be indicated.
*
* Return:
*	0							 Indication sent successfully.
*	-1							 Failed to send indication.
*
*****************************************************************/
int ql_appbt_le_indicate(unsigned short conn_handle, unsigned short att_handle, unsigned char *data, int size);


/*****************************************************************
* Function: ql_le_custom_mtu_request
*
* Description:
*	Sends a custom MTU (Maximum Transmission Unit) request to the peer device.
*
* Parameters:
*	conn_handle 	[in]		Connection handle for the LE connection.
*	mtu 			[in]		The requested MTU size.
*
* Return:
*	0							 MTU request sent successfully.
*	-1							 Failed to send MTU request.
*
*****************************************************************/
int ql_le_custom_mtu_request(unsigned short conn_handle, unsigned short mtu);


/*****************************************************************
* Function: ql_bt_le_scan
*
* Description:
*	Starts LE (Low Energy) scanning for nearby devices with the specified parameters.
*
* Parameters:
*	type			[in]		Scan type (e.g., passive or active).
*	interval		[in]		Scan interval (in units of 0.625 ms).
*	window			[in]		Scan window (in units of 0.625 ms).
*	own_address_type [in]		Address type for the local device.
*	handle			[in]		Callback function to handle scan events.
*
* Return:
*	0							 Scanning started successfully.
*	-1							 Failed to start scanning.
*
*****************************************************************/
int ql_bt_le_scan(unsigned char type, unsigned short int interval, unsigned short int window, unsigned char own_address_type, le_scan_event_handle_t handle);


/*****************************************************************
* Function: ql_bt_le_scan_with_filter
*
* Description:
*	Starts LE scanning for nearby devices with the specified parameters and a filter.
*
* Parameters:
*	type			[in]		Scan type (e.g., passive or active).
*	interval		[in]		Scan interval (in units of 0.625 ms).
*	window			[in]		Scan window (in units of 0.625 ms).
*	own_address_type [in]		Address type for the local device.
*	filter			[in]		Scan filter for device discovery (e.g., specific devices).
*	handle			[in]		Callback function to handle scan events.
*
* Return:
*	0							 Scanning with filter started successfully.
*	-1							 Failed to start scanning with filter.
*
*****************************************************************/
int ql_bt_le_scan_with_filter(unsigned char type, unsigned short int interval, unsigned short int window, unsigned char own_address_type, unsigned char filter, le_scan_event_handle_t handle);


/*****************************************************************
* Function: ql_bt_le_scan_stop
*
* Description:
*	Stops the ongoing LE (Low Energy) scanning process.
*
* Parameters:
*	None
*
* Return:
*	0							 Scanning stopped successfully.
*	-1							 Failed to stop scanning.
*
*****************************************************************/
int ql_bt_le_scan_stop(void);

/*****************************************************************
* Function: ql_le_custom_gatt_scan_start
*
* Description:
*	Starts a custom GATT (Generic Attribute Profile) scan for a specific LE (Low Energy) connection.
*
* Parameters:
*	conn_handle 	[in]		Connection handle for the LE connection.
*
* Return:
*	0							 Scan started successfully.
*	-1							 Failed to start scan.
*
*****************************************************************/
int ql_le_custom_gatt_scan_start(unsigned short conn_handle);


/*****************************************************************
* Function: ql_le_custom_write_command
*
* Description:
*	Sends a write command to a specific attribute handle on the LE connection.
*	The write command does not require an acknowledgment.
*
* Parameters:
*	conn_handle 	[in]		Connection handle for the LE connection.
*	att_handle		[in]		Attribute handle to write to.
*	data			[in]		Pointer to the data to be written.
*	size			[in]		Size of the data.
*
* Return:
*	0							 Write command sent successfully.
*	-1							 Failed to send write command.
*
*****************************************************************/
int ql_le_custom_write_command(unsigned short conn_handle, unsigned short att_handle, unsigned char *data, unsigned short size);


/*****************************************************************
* Function: ql_le_custom_write_request
*
* Description:
*	Sends a write request to a specific attribute handle on the LE connection.
*	This request requires an acknowledgment from the peer device.
*
* Parameters:
*	conn_handle 	[in]		Connection handle for the LE connection.
*	att_handle		[in]		Attribute handle to write to.
*	data			[in]		Pointer to the data to be written.
*	size			[in]		Size of the data.
*
* Return:
*	0							 Write request sent successfully.
*	-1							 Failed to send write request.
*
*****************************************************************/
int ql_le_custom_write_request(unsigned short conn_handle, unsigned short att_handle, unsigned char *data, unsigned short size);


/*****************************************************************
* Function: ql_le_custom_read_request
*
* Description:
*	Sends a read request for a specific attribute handle on the LE connection.
*	The request will retrieve the attribute value from the peer device.
*
* Parameters:
*	conn_handle 	[in]		Connection handle for the LE connection.
*	att_handle		[in]		Attribute handle to read from.
*
* Return:
*	0							 Read request sent successfully.
*	-1							 Failed to send read request.
*
*****************************************************************/
int ql_le_custom_read_request(unsigned short conn_handle, unsigned short att_handle);


/*****************************************************************
* Function: ql_le_custom_connection_parameter_update_request
*
* Description:
*	Sends a connection parameter update request for an LE connection.
*	This request allows updating parameters like connection interval, slave latency, and supervision timeout.
*
* Parameters:
*	conn_handle 	[in]		Connection handle for the LE connection.
*	conn_interval	[in]		New connection interval to request.
*	slave_latency	[in]		New slave latency to request.
*	supervision_timeout [in]	New supervision timeout to request.
*
* Return:
*	0							 Connection parameter update request sent successfully.
*	-1							 Failed to send connection parameter update request.
*
*****************************************************************/
int ql_le_custom_connection_parameter_update_request(unsigned short conn_handle, unsigned short conn_interval, unsigned short slave_latency, unsigned short supervision_timeout);



#ifdef __cplusplus
} /*"C" */
#endif

#endif