From: Tian Hao Date: Thu, 1 Dec 2016 10:58:54 +0000 (+0800) Subject: component/bt : cleanup the function comment as doxygen type X-Git-Tag: v1.0~2^2~4 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c6ec70b67bcbf89418e37dfabb45bffd03038136;p=esp-idf component/bt : cleanup the function comment as doxygen type --- diff --git a/components/bt/bluedroid/api/include/esp_blufi_api.h b/components/bt/bluedroid/api/include/esp_blufi_api.h index 7954e805e0..92b88e0e28 100644 --- a/components/bt/bluedroid/api/include/esp_blufi_api.h +++ b/components/bt/bluedroid/api/include/esp_blufi_api.h @@ -27,16 +27,19 @@ #define ESP_BLUFI_EVENT_DEINIT_FINISH 1 #define ESP_BLUFI_EVENT_RECV_DATA 2 +/// BLUFI config status typedef enum { ESP_BLUFI_CONFIG_OK = 0, ESP_BLUFI_CONFIG_FAILED, } esp_blufi_config_state_t; +/// BLUFI init status typedef enum { ESP_BLUFI_INIT_OK = 0, ESP_BLUFI_INIT_FAILED = 0, } esp_blufi_init_state_t; +/// BLUFI deinit status typedef enum { ESP_BLUFI_DEINIT_OK = 0, ESP_BLUFI_DEINIT_FAILED = 0, @@ -69,52 +72,52 @@ typedef union { } recv_data; /*!< Blufi callback param of ESP_BLUFI_EVENT_RECV_DATA */ } esp_blufi_cb_param_t; -/******************************************************************************* -** -** @function esp_blufi_register_callback -** -** @brief This function is called to receive blufi callback event -** -** @param[in] callback: callback function -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_blufi_register_callback + * + * @brief This function is called to receive blufi callback event + * + * @param[in] callback: callback function + * + * @return ESP_OK - success, other - failed + * + */ esp_err_t esp_blufi_register_callback(esp_profile_cb_t callback); -/******************************************************************************* -** -** @function esp_blufi_send_config_state -** -** @brief This function is called to send config state to phone -** -** @param[in] state: blufi config OK or not -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_blufi_send_config_state + * + * @brief This function is called to send config state to phone + * + * @param[in] state: blufi config OK or not + * + * @return ESP_OK - success, other - failed + * + */ esp_err_t esp_blufi_send_config_state(esp_blufi_config_state_t state); -/******************************************************************************* -** -** @function esp_blufi_profile_init -** -** @brief This function is called to initialize blufi_profile -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_blufi_profile_init + * + * @brief This function is called to initialize blufi_profile + * + * @return ESP_OK - success, other - failed + * + */ esp_err_t esp_blufi_profile_init(void); -/******************************************************************************* -** -** @function esp_blufi_profile_deinit -** -** @brief This function is called to de-initialize blufi_profile -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/* + * + * @function esp_blufi_profile_deinit + * + * @brief This function is called to de-initialize blufi_profile + * + * @return ESP_OK - success, other - failed + * + */ esp_err_t esp_blufi_profile_deinit(void); diff --git a/components/bt/bluedroid/api/include/esp_bt_defs.h b/components/bt/bluedroid/api/include/esp_bt_defs.h index 6d5c65ebe8..a19d89e856 100644 --- a/components/bt/bluedroid/api/include/esp_bt_defs.h +++ b/components/bt/bluedroid/api/include/esp_bt_defs.h @@ -18,7 +18,7 @@ #include #include -/* Status Return Value */ +/// Status Return Value typedef enum { ESP_BT_STATUS_SUCCESS = 0, /* Successful operation. */ ESP_BT_STATUS_FAILURE = 1, /* Generic failure. */ @@ -28,12 +28,16 @@ typedef enum { ESP_BT_STATUS_WRONG_MODE = 5, } esp_bt_status_t; +/// Default GATT interface id #define ESP_DEFAULT_GATT_IF 0xff +/// Default BLE connection param, if the value doesn't be overwritten #define ESP_BLE_CONN_PARAM_UNDEF 0xffff /* use this value when a specific value not to be overwritten */ +/// Check the param is valid or not #define ESP_BLE_IS_VALID_PARAM(x, min, max) (((x) >= (min) && (x) <= (max)) || ((x) == ESP_BLE_CONN_PARAM_UNDEF)) +/// UUID type typedef struct { #define ESP_UUID_LEN_16 2 #define ESP_UUID_LEN_32 4 @@ -46,14 +50,18 @@ typedef struct { } uuid; /*!< UUID */ } __attribute__((packed)) esp_bt_uuid_t; +/// Bluetooth device type typedef enum { ESP_BT_DEVICE_TYPE_BREDR = 0x01, ESP_BT_DEVICE_TYPE_BLE = 0x02, ESP_BT_DEVICE_TYPE_DUMO = 0x03, } esp_bt_dev_type_t; +/// Bluetooth address length #define ESP_BD_ADDR_LEN 6 -typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN]; /*!< Bluetooth device address */ + +/// Bluetooth device address +typedef uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN]; /// Own BD address source of the device typedef enum { @@ -71,6 +79,7 @@ typedef enum { BD_ADDR_PROVIDED_RECON, } esp_bd_addr_type_t; +/// BLE device address type typedef enum { BLE_ADDR_TYPE_PUBLIC = 0x00, BLE_ADDR_TYPE_RANDOM = 0x01, @@ -78,9 +87,16 @@ typedef enum { BLE_ADDR_TYPE_RPA_RANDOM = 0x03, } esp_ble_addr_type_t; +/// Minimum of the application id #define ESP_APP_ID_MIN 0x0000 +/// Maximum of the application id #define ESP_APP_ID_MAX 0x7fff +/** + * @brief Each profile callback function type + * @param event : Event type + * @param param : Point to callback parameter, currently is union type + */ typedef void (* esp_profile_cb_t)(uint32_t event, void *param); #endif ///__ESP_BT_DEFS_H__ diff --git a/components/bt/bluedroid/api/include/esp_bt_main.h b/components/bt/bluedroid/api/include/esp_bt_main.h index dd7ec7116d..8e83f28e90 100644 --- a/components/bt/bluedroid/api/include/esp_bt_main.h +++ b/components/bt/bluedroid/api/include/esp_bt_main.h @@ -18,12 +18,44 @@ #include "btc_main.h" #include "esp_err.h" +/** + * @function esp_enable_bluetooth + * + * @brief Enable bluetooth, must after esp_init_bluetooth() + * + * @return - ESP_OK : Succeed + * - Other : Failed + */ esp_err_t esp_enable_bluetooth(void); +/** + * @function esp_disable_bluetooth + * + * @brief Disable bluetooth, must prior to esp_deinit_bluetooth() + * + * @return - ESP_OK : Succeed + * - Other : Failed + */ esp_err_t esp_disable_bluetooth(void); +/** + * @function esp_init_bluetooth + * + * @brief Init and alloc the resource for bluetooth, must be prior to every bluetooth stuff + * + * @return - ESP_OK : Succeed + * - Other : Failed + */ esp_err_t esp_init_bluetooth(void); +/** + * @function esp_deinit_bluetooth + * + * @brief Deinit and free the resource for bluetooth, must be after every bluetooth stuff + * + * @return - ESP_OK : Succeed + * - Other : Failed + */ esp_err_t esp_deinit_bluetooth(void); diff --git a/components/bt/bluedroid/api/include/esp_gap_ble_api.h b/components/bt/bluedroid/api/include/esp_gap_ble_api.h index 58f5977ae3..3643b3f5fd 100644 --- a/components/bt/bluedroid/api/include/esp_gap_ble_api.h +++ b/components/bt/bluedroid/api/include/esp_gap_ble_api.h @@ -21,42 +21,45 @@ #include "esp_err.h" #include "esp_bt_defs.h" -#define ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT 0 -#define ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT 1 -#define ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT 2 -#define ESP_GAP_BLE_SCAN_RESULT_EVT 3 +/// GAP BLE callback event type +typedef enum { + ESP_GAP_BLE_ADV_DATA_SET_COMPLETE_EVT = 0, /*!< When advertising data set complete, the event comes */ + ESP_GAP_BLE_SCAN_RSP_DATA_SET_COMPLETE_EVT , /*!< When scan response data set complete, the event comes */ + ESP_GAP_BLE_SCAN_PARAM_SET_COMPLETE_EVT, /*!< When scan parameters set complete, the event comes */ + ESP_GAP_BLE_SCAN_RESULT_EVT, /*!< When one scan result ready, the event comes each time */ +}esp_gap_ble_cb_event_t; +/// Advertising data maximum length #define ESP_BLE_ADV_DATA_LEN_MAX 31 -/****************** define the adv type macro***************************************/ -#define ESP_BLE_AD_TYPE_FLAG 0x01 -#define ESP_BLE_AD_TYPE_16SRV_PART 0x02 -#define ESP_BLE_AD_TYPE_16SRV_CMPL 0x03 -#define ESP_BLE_AD_TYPE_32SRV_PART 0x04 -#define ESP_BLE_AD_TYPE_32SRV_CMPL 0x05 -#define ESP_BLE_AD_TYPE_128SRV_PART 0x06 -#define ESP_BLE_AD_TYPE_128SRV_CMPL 0x07 -#define ESP_BLE_AD_TYPE_NAME_SHORT 0x08 -#define ESP_BLE_AD_TYPE_NAME_CMPL 0x09 -#define ESP_BLE_AD_TYPE_TX_PWR 0x0A -#define ESP_BLE_AD_TYPE_DEV_CLASS 0x0D -#define ESP_BLE_AD_TYPE_SM_TK 0x10 -#define ESP_BLE_AD_TYPE_SM_OOB_FLAG 0x11 -#define ESP_BLE_AD_TYPE_INT_RANGE 0x12 -#define ESP_BLE_AD_TYPE_SOL_SRV_UUID 0x14 -#define ESP_BLE_AD_TYPE_128SOL_SRV_UUID 0x15 -#define ESP_BLE_AD_TYPE_SERVICE_DATA 0x16 -#define ESP_BLE_AD_TYPE_PUBLIC_TARGET 0x17 -#define ESP_BLE_AD_TYPE_RANDOM_TARGET 0x18 -#define ESP_BLE_AD_TYPE_APPEARANCE 0x19 -#define ESP_BLE_AD_TYPE_ADV_INT 0x1A -#define ESP_BLE_AD_TYPE_32SOL_SRV_UUID 0x1B -#define ESP_BLE_AD_TYPE_32SERVICE_DATA 0x1C -#define ESP_BLE_AD_TYPE_128SERVICE_DATA 0x1D -#define ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE 0xFF - - -typedef uint32_t esp_gap_ble_event_t; +/// The type of advertising data(not adv_type) +typedef enum { + ESP_BLE_AD_TYPE_FLAG = 0x01, + ESP_BLE_AD_TYPE_16SRV_PART = 0x02, + ESP_BLE_AD_TYPE_16SRV_CMPL = 0x03, + ESP_BLE_AD_TYPE_32SRV_PART = 0x04, + ESP_BLE_AD_TYPE_32SRV_CMPL = 0x05, + ESP_BLE_AD_TYPE_128SRV_PART = 0x06, + ESP_BLE_AD_TYPE_128SRV_CMPL = 0x07, + ESP_BLE_AD_TYPE_NAME_SHORT = 0x08, + ESP_BLE_AD_TYPE_NAME_CMPL = 0x09, + ESP_BLE_AD_TYPE_TX_PWR = 0x0A, + ESP_BLE_AD_TYPE_DEV_CLASS = 0x0D, + ESP_BLE_AD_TYPE_SM_TK = 0x10, + ESP_BLE_AD_TYPE_SM_OOB_FLAG = 0x11, + ESP_BLE_AD_TYPE_INT_RANGE = 0x12, + ESP_BLE_AD_TYPE_SOL_SRV_UUID = 0x14, + ESP_BLE_AD_TYPE_128SOL_SRV_UUID = 0x15, + ESP_BLE_AD_TYPE_SERVICE_DATA = 0x16, + ESP_BLE_AD_TYPE_PUBLIC_TARGET = 0x17, + ESP_BLE_AD_TYPE_RANDOM_TARGET = 0x18, + ESP_BLE_AD_TYPE_APPEARANCE = 0x19, + ESP_BLE_AD_TYPE_ADV_INT = 0x1A, + ESP_BLE_AD_TYPE_32SOL_SRV_UUID = 0x1B, + ESP_BLE_AD_TYPE_32SERVICE_DATA = 0x1C, + ESP_BLE_AD_TYPE_128SERVICE_DATA = 0x1D, + ESP_BLE_AD_MANUFACTURER_SPECIFIC_TYPE = 0xFF, +} esp_ble_adv_data_type; /// Advertising mode typedef enum { @@ -189,17 +192,15 @@ typedef struct { Time Range: 100 msec to 32 seconds */ } esp_ble_conn_update_params_t; -typedef void (*esp_gap_ble_cb_t)(esp_gap_ble_event_t event, void *param); - +/// Sub Event of ESP_GAP_BLE_SCAN_RESULT_EVT typedef enum { - /* Search callback events */ - ESP_GAP_SEARCH_INQ_RES_EVT = 0, /* Inquiry result for a peer device. */ - ESP_GAP_SEARCH_INQ_CMPL_EVT = 1, /* Inquiry complete. */ - ESP_GAP_SEARCH_DISC_RES_EVT = 2, /* Discovery result for a peer device. */ - ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3, /* Discovery result for BLE GATT based service on a peer device. */ - ESP_GAP_SEARCH_DISC_CMPL_EVT = 4, /* Discovery complete. */ - ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5, /* Discovery complete. */ - ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6, /* Search cancelled */ + ESP_GAP_SEARCH_INQ_RES_EVT = 0, /*!< Inquiry result for a peer device. */ + ESP_GAP_SEARCH_INQ_CMPL_EVT = 1, /*!< Inquiry complete. */ + ESP_GAP_SEARCH_DISC_RES_EVT = 2, /*!< Discovery result for a peer device. */ + ESP_GAP_SEARCH_DISC_BLE_RES_EVT = 3, /*!< Discovery result for BLE GATT based service on a peer device. */ + ESP_GAP_SEARCH_DISC_CMPL_EVT = 4, /*!< Discovery complete. */ + ESP_GAP_SEARCH_DI_DISC_CMPL_EVT = 5, /*!< Discovery complete. */ + ESP_GAP_SEARCH_SEARCH_CANCEL_CMPL_EVT = 6, /*!< Search cancelled */ } esp_gap_search_evt_t; /** @@ -239,192 +240,189 @@ typedef union { } scan_rst; /*!< Event parameter of ESP_GAP_BLE_SCAN_RESULT_EVT */ } esp_ble_gap_cb_param_t; -/******************************************************************************* -** -** @function esp_ble_gap_register_callback -** -** @brief This function is called to occur gap event, such as scan result -** -** @param[in] callback: callback function -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ - +/** + * @function esp_ble_gap_register_callback + * + * @brief This function is called to occur gap event, such as scan result + * + * @param[in] callback: callback function + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_register_callback(esp_profile_cb_t callback); -/******************************************************************************* -** -** @function esp_ble_gap_config_adv_data -** -** @brief This function is called to override the BTA default ADV parameters. -** -** @param[in] adv_data: Pointer to User defined ADV data structure. This -** memory space can not be freed until callback of config_adv_data -** is received. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_config_adv_data + * + * @brief This function is called to override the BTA default ADV parameters. + * + * @param[in] adv_data: Pointer to User defined ADV data structure. This + * memory space can not be freed until callback of config_adv_data + * is received. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_config_adv_data (esp_ble_adv_data_t *adv_data); -/******************************************************************************* -** -** @function esp_ble_gap_set_scan_params -** -** @brief This function is called to set scan parameters -** -** @param[in] esp_ble_scan_params: Pointer to User defined scan_params data structure. This -** memory space can not be freed until callback of set_scan_params -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_set_scan_params + * + * @brief This function is called to set scan parameters + * + * @param[in] esp_ble_scan_params: Pointer to User defined scan_params data structure. This + * memory space can not be freed until callback of set_scan_params + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_set_scan_params(esp_ble_scan_params_t *scan_params); -/******************************************************************************* -** -** @function esp_ble_gap_start_scanning -** -** @brief This procedure keep the device scanning the peer device which advertising on the air -** -** @param[in] duration: Keeping the scanning time, the unit is second. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_start_scanning + * + * @brief This procedure keep the device scanning the peer device which advertising on the air + * + * @param[in] duration: Keeping the scanning time, the unit is second. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_start_scanning(uint32_t duration); -/******************************************************************************* -** -** @function esp_ble_gap_stop_scanning -** -** @brief This function call to stop the device scanning the peer device which advertising on the air -** @param void -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_stop_scanning + * + * @brief This function call to stop the device scanning the peer device which advertising on the air + * @param void + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_stop_scanning(void); -/******************************************************************************* -** -** @function esp_ble_gap_start_advertising -** -** @brief This function is called to start advertising. -** -** @param[in] esp_ble_adv_params_all_t: pointer to User defined adv_params data structure. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_start_advertising + * + * @brief This function is called to start advertising. + * + * @param[in] esp_ble_adv_params_all_t: pointer to User defined adv_params data structure. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_start_advertising (esp_ble_adv_params_t *adv_params); -/******************************************************************************* -** -** @function esp_gap_ble_stop_advertising -** -** @brief This function is called to stop advertising. -** -** @param None -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_gap_ble_stop_advertising + * + * @brief This function is called to stop advertising. + * + * @param None + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_stop_advertising(void); -/******************************************************************************* -** -** @function esp_ble_update_conn_params -** -** @brief Update connection parameters, can only be used when connection is up. -** -** @param[in] param - connection update parameters -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_update_conn_params + * + * @brief Update connection parameters, can only be used when connection is up. + * + * @param[in] param - connection update parameters + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_update_conn_params(esp_ble_conn_update_params_t *params); -/******************************************************************************* -** -** @function esp_ble_gap_set_pkt_data_len -** -** @brief This function is to set maximum LE data packet size -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_set_pkt_data_len + * + * @brief This function is to set maximum LE data packet size + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_set_pkt_data_len(esp_bd_addr_t remote_device, uint16_t tx_data_length); -/******************************************************************************* -** -** @function esp_ble_gap_set_rand_addr -** -** @brief This function set the random address for the application -** -** @param[in] rand_addr: the random address which should be setting -** -** @return ESP_OK - success, other - failed -** -** -*******************************************************************************/ +/** + * @function esp_ble_gap_set_rand_addr + * + * @brief This function set the random address for the application + * + * @param[in] rand_addr: the random address which should be setting + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_set_rand_addr(esp_bd_addr_t rand_addr); -/******************************************************************************* -** -** @function esp_ble_gap_config_local_privacy -** -** @brief Enable/disable privacy on the local device -** -** @param[in] privacy_enable - enable/disable privacy on remote device. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_config_local_privacy + * + * @brief Enable/disable privacy on the local device + * + * @param[in] privacy_enable - enable/disable privacy on remote device. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_config_local_privacy (bool privacy_enable); -/******************************************************************************* -** -** @function esp_ble_gap_set_device_name -** -** @brief Set device name to the local device -** -** @param[in] name - device name. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * @function esp_ble_gap_set_device_name + * + * @brief Set device name to the local device + * + * @param[in] name - device name. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gap_set_device_name(const char *name); -/******************************************************************************* -** -** @function esp_ble_resolve_adv_data -** -** @brief This function is called to get ADV data for a specific type. -** -** @param[in] adv_data - pointer of ADV data which to be resolved -** @param[in] type - finding ADV data type -** @param[out] length - return the length of ADV data not including type -** -** @return pointer of ADV data -** -*******************************************************************************/ +/** + * @function esp_ble_resolve_adv_data + * + * @brief This function is called to get ADV data for a specific type. + * + * @param[in] adv_data - pointer of ADV data which to be resolved + * @param[in] type - finding ADV data type + * @param[out] length - return the length of ADV data not including type + * + * @return pointer of ADV data + * + */ uint8_t *esp_ble_resolve_adv_data(uint8_t *adv_data, uint8_t type, uint8_t *p_length); #endif /* __ESP_GAP_BLE_API_H__ */ diff --git a/components/bt/bluedroid/api/include/esp_gatt_defs.h b/components/bt/bluedroid/api/include/esp_gatt_defs.h index c4a16e00e0..c9091c428f 100644 --- a/components/bt/bluedroid/api/include/esp_gatt_defs.h +++ b/components/bt/bluedroid/api/include/esp_gatt_defs.h @@ -17,9 +17,11 @@ #include "esp_bt_defs.h" -/* attribute request data from the client */ -#define ESP_GATT_PREP_WRITE_CANCEL 0x00 -#define ESP_GATT_PREP_WRITE_EXEC 0x01 +/// Attribute write data type from the client +typedef enum { + ESP_GATT_PREP_WRITE_CANCEL = 0x00, /*!< Prepare write cancel */ + ESP_GATT_PREP_WRITE_EXEC = 0x01, /*!< Prepare write execute */ +} esp_gatt_prep_write_type; /** * @brief GATT success code and error codes @@ -144,6 +146,7 @@ typedef enum { ESP_GATT_CHAR_PROP_BIT_EXT_PROP = (1 << 7), /* 0x80 */ } esp_gatt_char_prop_t; +/// GATT maximum attribute length #define ESP_GATT_MAX_ATTR_LEN 600 //as same as GATT_MAX_ATTR_LEN /// Gatt attribute value @@ -169,6 +172,6 @@ typedef enum { ESP_GATT_WRITE_TYPE_RSP, /*!< Gatt write attribute need remote response */ } esp_gatt_write_type_t; -typedef uint32_t esp_gatt_if_t; /* Gatt interface type, different application on GATT client use different gatt_if */ +typedef uint32_t esp_gatt_if_t; /*!< Gatt interface type, different application on GATT client use different gatt_if */ #endif /* __ESP_GATT_DEFS_H__ */ diff --git a/components/bt/bluedroid/api/include/esp_gattc_api.h b/components/bt/bluedroid/api/include/esp_gattc_api.h old mode 100644 new mode 100755 index f7328df504..710af99ba1 --- a/components/bt/bluedroid/api/include/esp_gattc_api.h +++ b/components/bt/bluedroid/api/include/esp_gattc_api.h @@ -20,50 +20,53 @@ #include "esp_gatt_defs.h" #include "esp_err.h" -/* Client callback function events */ -#define ESP_GATTC_REG_EVT 0 /* GATT client is registered. */ -#define ESP_GATTC_UNREG_EVT 1 /* GATT client unregistered event */ -#define ESP_GATTC_OPEN_EVT 2 /* GATTC open request status event */ -#define ESP_GATTC_READ_CHAR_EVT 3 /* GATT read characteristic event */ -#define ESP_GATTC_WRITE_CHAR_EVT 4 /* GATT write characteristic or char descriptor event */ -#define ESP_GATTC_CLOSE_EVT 5 /* GATTC close request status event */ -#define ESP_GATTC_SEARCH_CMPL_EVT 6 /* GATT discovery complete event */ -#define ESP_GATTC_SEARCH_RES_EVT 7 /* GATT discovery result event */ -#define ESP_GATTC_READ_DESCR_EVT 8 /* GATT read characteristic descriptor event */ -#define ESP_GATTC_WRITE_DESCR_EVT 9 /* GATT write characteristic descriptor event */ -#define ESP_GATTC_NOTIFY_EVT 10 /* GATT attribute notification event */ -#define ESP_GATTC_PREP_WRITE_EVT 11 /* GATT prepare write event */ -#define ESP_GATTC_EXEC_EVT 12 /* execute write complete event */ -#define ESP_GATTC_ACL_EVT 13 /* ACL up event */ -#define ESP_GATTC_CANCEL_OPEN_EVT 14 /* cancel open event */ -#define ESP_GATTC_SRVC_CHG_EVT 15 /* service change event */ -#define ESP_GATTC_ENC_CMPL_CB_EVT 17 /* encryption complete callback event */ -#define ESP_GATTC_CFG_MTU_EVT 18 /* configure MTU complete event */ -#define ESP_GATTC_ADV_DATA_EVT 19 /* ADV data event */ -#define ESP_GATTC_MULT_ADV_ENB_EVT 20 /* Enable Multi ADV event */ -#define ESP_GATTC_MULT_ADV_UPD_EVT 21 /* Update parameter event */ -#define ESP_GATTC_MULT_ADV_DATA_EVT 22 /* Multi ADV data event */ -#define ESP_GATTC_MULT_ADV_DIS_EVT 23 /* Disable Multi ADV event */ -#define ESP_GATTC_CONGEST_EVT 24 /* Congestion event */ -#define ESP_GATTC_BTH_SCAN_ENB_EVT 25 /* Enable batch scan event */ -#define ESP_GATTC_BTH_SCAN_CFG_EVT 26 /* Config storage event */ -#define ESP_GATTC_BTH_SCAN_RD_EVT 27 /* Batch scan reports read event */ -#define ESP_GATTC_BTH_SCAN_THR_EVT 28 /* Batch scan threshold event */ -#define ESP_GATTC_BTH_SCAN_PARAM_EVT 29 /* Batch scan param event */ -#define ESP_GATTC_BTH_SCAN_DIS_EVT 30 /* Disable batch scan event */ -#define ESP_GATTC_SCAN_FLT_CFG_EVT 31 /* Scan filter config event */ -#define ESP_GATTC_SCAN_FLT_PARAM_EVT 32 /* Param filter event */ -#define ESP_GATTC_SCAN_FLT_STATUS_EVT 33 /* Filter status event */ -#define ESP_GATTC_ADV_VSC_EVT 34 /* ADV VSC event */ - -#define ESP_GATTC_GET_CHAR_EVT 35 /* get characteristic event */ -#define ESP_GATTC_GET_DESCR_EVT 36 /* get characteristic descriptor event */ -#define ESP_GATTC_GET_INCL_SRVC_EVT 37 /* get included service event */ -#define ESP_GATTC_REG_FOR_NOTIFY_EVT 38 /* register for notification event */ -#define ESP_GATTC_UNREG_FOR_NOTIFY_EVT 39 /* unregister for notification event */ - - +/// GATT Client callback function events +typedef enum { + ESP_GATTC_REG_EVT = 0, /*!> when GATT client is registered */ + ESP_GATTC_UNREG_EVT, /*!> when GATT client is unregistered */ + ESP_GATTC_OPEN_EVT, /*!> when GATT connection is set up */ + ESP_GATTC_READ_CHAR_EVT, /*!> when GATT characteristic is read */ + ESP_GATTC_WRITE_CHAR_EVT, /*!> when GATT characteristic write operation completes */ + ESP_GATTC_CLOSE_EVT, /*!> when GATT connection is closed */ + ESP_GATTC_SEARCH_CMPL_EVT, /*!> when GATT service discovery is completed */ + ESP_GATTC_SEARCH_RES_EVT, /*!> when GATT service discovery result is got */ + ESP_GATTC_READ_DESCR_EVT, /*!> when GATT characteristic descriptor read completes */ + ESP_GATTC_WRITE_DESCR_EVT, /*!> when GATT characteristic descriptor write completes */ + ESP_GATTC_NOTIFY_EVT, /*!> when GATT notification or indication arrives */ + ESP_GATTC_PREP_WRITE_EVT, /*!> when GATT prepare-write operation conpletes */ + ESP_GATTC_EXEC_EVT, /*!> when write execution completes */ + ESP_GATTC_ACL_EVT, /*!> when ACL connection is up */ + ESP_GATTC_CANCEL_OPEN_EVT, /*!> when GATT client ongoing connection is cancelled */ + ESP_GATTC_SRVC_CHG_EVT, /*!> when "service changed" occurs */ + ESP_GATTC_ENC_CMPL_CB_EVT, /*!> when encryption procedure completes */ + ESP_GATTC_CFG_MTU_EVT, /*!> when configuration of MTU completes */ + ESP_GATTC_ADV_DATA_EVT, /*!> when advertising of data */ + ESP_GATTC_MULT_ADV_ENB_EVT, /*!> when multi-advertising is enabled */ + ESP_GATTC_MULT_ADV_UPD_EVT, /*!> when multi-advertising parameters are updated */ + ESP_GATTC_MULT_ADV_DATA_EVT, /*!> when multi-advertising data arrives */ + ESP_GATTC_MULT_ADV_DIS_EVT, /*!> when multi-advertising is disabled */ + ESP_GATTC_CONGEST_EVT, /*!> when GATT connection congestion comes */ + ESP_GATTC_BTH_SCAN_ENB_EVT, /*!> when batch scan is enabled */ + ESP_GATTC_BTH_SCAN_CFG_EVT, /*!> when batch scan storage is configured */ + ESP_GATTC_BTH_SCAN_RD_EVT, /*!> when Batch scan read event is reported */ + ESP_GATTC_BTH_SCAN_THR_EVT, /*!> when Batch scan threshold is set */ + ESP_GATTC_BTH_SCAN_PARAM_EVT, /*!> when Batch scan parameters are set */ + ESP_GATTC_BTH_SCAN_DIS_EVT, /*!> when Batch scan is disabled */ + ESP_GATTC_SCAN_FLT_CFG_EVT, /*!> when Scan filter configuration completes */ + ESP_GATTC_SCAN_FLT_PARAM_EVT, /*!> when Scan filter parameters are set */ + ESP_GATTC_SCAN_FLT_STATUS_EVT, /*!> when Scan filter status is reported */ + ESP_GATTC_ADV_VSC_EVT, /*!> when ADV VSC event is reported*/ + ESP_GATTC_GET_CHAR_EVT, /*!> when characteristic is got from GATT server */ + ESP_GATTC_GET_DESCR_EVT, /*!> when charcteristic descriptor is got from GATT server */ + ESP_GATTC_GET_INCL_SRVC_EVT, /*!> when included service is got from GATT server */ + ESP_GATTC_REG_FOR_NOTIFY_EVT, /*!> when registration for notification of a service completes */ + ESP_GATTC_UNREG_FOR_NOTIFY_EVT /*!> when unregistration for notification of a service completes */ +} esp_gattc_cb_event_t; + +/// Maximum Transmission Unit used in GATT #define ESP_GATT_DEF_BLE_MTU_SIZE 23 + +/// Maximum Transmission Unit allowed in GATT #define ESP_GATT_MAX_MTU_SIZE 517 /** @@ -242,215 +245,222 @@ typedef union { } esp_ble_gattc_cb_param_t; /*!< GATT client callback parameter union type */ -/******************************************************************************* -** -** @function esp_ble_gattc_app_register_callback -** -** @brief This function is called to register application callbacks -** with GATTC module. -** -** @param[in] callback : pointer to the application callback function. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_app_register_callback + * + * @brief This function is called to register application callbacks + * with GATTC module. + * + * @param[in] callback : pointer to the application callback function. + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_register_callback(esp_profile_cb_t callback); - -/******************************************************************************* -** -** @function esp_ble_gattc_app_register -** -** @brief This function is called to register application callbacks -** with GATTC module. -** -** @param[in] app_id : Application Identify (UUID), for different application -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_app_register + * + * @brief This function is called to register application callbacks + * with GATTC module. + * + * @param[in] app_id : Application Identify (UUID), for different application + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_app_register(uint16_t app_id); -/******************************************************************************* -** -** @function esp_ble_gattc_app_unregister -** -** @brief This function is called to unregister an application -** from GATTC module. -** -** @param[in] gatt_if : app identifier. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_app_unregister + * + * @brief This function is called to unregister an application + * from GATTC module. + * + * @param[in] gatt_if : app identifier. + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gatt_if); -/******************************************************************************* -** -** @function esp_ble_gattc_conn -** -** @brief Open a direct connection or add a background auto connection -** -** @param[in] gatt_if: application identity. -** @param[in] remote_bda: remote device bluetooth device address. -** @param[in] is_direct: direct connection or background auto connection -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_conn + * + * @brief Open a direct connection or add a background auto connection + * + * @param[in] gatt_if: application identity. + * @param[in] remote_bda: remote device bluetooth device address. + * @param[in] is_direct: direct connection or background auto connection + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_open(esp_gatt_if_t gatt_if, esp_bd_addr_t remote_bda, bool is_direct); -/******************************************************************************* -** -** @function esp_ble_gattc_close -** -** @brief Close a connection to a GATT server. -** -** @param[in] conn_id: connection ID to be closed. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ -esp_err_t esp_ble_gattc_close (uint16_t conn_id); +/** + * + * @function esp_ble_gattc_close + * + * @brief Close a connection to a GATT server. + * + * @param[in] conn_id: connection ID to be closed. + * + * @return - ESP_OK: success + * - other: failed + * + */ +esp_err_t esp_ble_gattc_close (uint16_t conn_id); -/******************************************************************************* -** -** @function esp_ble_gattc_config_mtu -** -** @brief Configure the MTU size in the GATT channel. This can be done -** only once per connection. -** -** @param[in] conn_id: connection ID. -** mtu: desired MTU size to use. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_config_mtu + * + * @brief Configure the MTU size in the GATT channel. This can be done + * only once per connection. + * + * @param[in] conn_id: connection ID. + * mtu: desired MTU size to use. + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_config_mtu (uint16_t conn_id, uint16_t mtu); -/******************************************************************************* -** -** @function esp_ble_gattc_search_service -** -** @brief This function is called to request a GATT service discovery -** on a GATT server. This function report service search result -** by a callback event, and followed by a service search complete -** event. -** -** @param[in] conn_id: connection ID. -** @param[in] filter_uuid: a UUID of the service application is interested in. -** If Null, discover for all services. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_search_service + * + * @brief This function is called to request a GATT service discovery + * on a GATT server. This function report service search result + * by a callback event, and followed by a service search complete + * event. + * + * @param[in] conn_id: connection ID. + * @param[in] filter_uuid: a UUID of the service application is interested in. + * If Null, discover for all services. + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_search_service(uint16_t conn_id, esp_bt_uuid_t *filter_uuid); -/**************************************************************************************************** -** -** @function esp_ble_gattc_get_characteristic -** -** @brief This function is called to find the first characteristic of the -** service on the given server. -** -** @param[in] conn_id: connection ID which identify the server. -** -** @param[in] srvc_id: service ID -** -** @param[in] start_char_id: the start characteristic ID -** -** @return ESP_OK - success, other - failed -** -*****************************************************************************************************/ - +/** + * + * @function esp_ble_gattc_get_characteristic + * + * @brief This function is called to find the first characteristic of the + * service on the given server. + * + * @param[in] conn_id: connection ID which identify the server. + * + * @param[in] srvc_id: service ID + * + * @param[in] start_char_id: the start characteristic ID + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_get_characteristic(uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *start_char_id); -/**************************************************************************************************** -** -** @function esp_ble_gattc_get_descriptor -** -** @brief This function is called to find the descriptor of the -** service on the given server. -** -** @param[in] conn_id: connection ID which identify the server. -** @param[in] srvc_id: the service ID of which the characteristic is belonged to. -** @param[in] char_id: Characteristic ID, if NULL find the first available -** characteristic. -** @param[in] start_descr_id: the start descriptor id -** -** @return ESP_OK - success, other - failed -** -*****************************************************************************************************/ + +/** + * + * @function esp_ble_gattc_get_descriptor + * + * @brief This function is called to find the descriptor of the + * service on the given server. + * + * @param[in] conn_id: connection ID which identify the server. + * @param[in] srvc_id: the service ID of which the characteristic is belonged to. + * @param[in] char_id: Characteristic ID, if NULL find the first available + * characteristic. + * @param[in] start_descr_id: the start descriptor id + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_get_descriptor(uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, esp_gatt_id_t *start_descr_id); -/**************************************************************************************************** -** -** @function esp_ble_gattc_get_include_service -** -** @brief This function is called to find the first characteristic of the -** service on the given server. -** -** @param[in] conn_id: connection ID which identify the server. -** @param[in] srvc_id: the service ID of which the characteristic is belonged to. -** @param[in] start_incl_srvc_id: the start include service id -** -** @return ESP_OK - success, other - failed -** -*****************************************************************************************************/ - - +/** + * + * @function esp_ble_gattc_get_include_service + * + * @brief This function is called to find the first characteristic of the + * service on the given server. + * + * @param[in] conn_id: connection ID which identify the server. + * @param[in] srvc_id: the service ID of which the characteristic is belonged to. + * @param[in] start_incl_srvc_id: the start include service id + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_get_included_service(uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_srvc_id_t *start_incl_srvc_id); - -/******************************************************************************* -** -** @function esp_ble_gattc_read_char -** -** @brief This function is called to read a service's characteristics of -** the given characteriistic ID -** -** @param[in] conn_id : connection ID. -** @param[in] srvc_id : service ID. -** @param[in] char_id : characteristic ID to read. -** @param[in] auth_req : authenticate request type -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_read_char + * + * @brief This function is called to read a service's characteristics of + * the given characteriistic ID + * + * @param[in] conn_id : connection ID. + * @param[in] srvc_id : service ID. + * @param[in] char_id : characteristic ID to read. + * @param[in] auth_req : authenticate request type + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_read_char (uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, esp_gatt_auth_req_t auth_req); - -/******************************************************************************* -** -** @function esp_ble_gattc_read_char_descr -** -** @brief This function is called to read a characteristics descriptor. -** -** @param[in] conn_id : connection ID. -** @param[in] srvc_id : service ID. -** @param[in] descr_id : characteristic descriptor ID to read. -** @param[in] auth_req : authenticate request type -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_read_char_descr + * + * @brief This function is called to read a characteristics descriptor. + * + * @param[in] conn_id : connection ID. + * @param[in] srvc_id : service ID. + * @param[in] descr_id : characteristic descriptor ID to read. + * @param[in] auth_req : authenticate request type + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_read_char_descr (uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, @@ -458,23 +468,25 @@ esp_err_t esp_ble_gattc_read_char_descr (uint16_t conn_id, esp_gatt_auth_req_t auth_req); -/******************************************************************************* -** -** @function esp_ble_gattc_write_char -** -** @brief This function is called to write characteristic value. -** -** @param[in] conn_id : connection ID. -** @param[in] srvc_id : service ID. -** @param[in] char_id : characteristic ID to write. -** @param[in] value_len: length of the value to be written. -** @param[in] value : the value to be written. -** @param[in] write_type : the type of attribute write operation. -** @param[in] auth_req : authentication request. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_write_char + * + * @brief This function is called to write characteristic value. + * + * @param[in] conn_id : connection ID. + * @param[in] srvc_id : service ID. + * @param[in] char_id : characteristic ID to write. + * @param[in] value_len: length of the value to be written. + * @param[in] value : the value to be written. + * @param[in] write_type : the type of attribute write operation. + * @param[in] auth_req : authentication request. + * + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_write_char( uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, @@ -484,25 +496,26 @@ esp_err_t esp_ble_gattc_write_char( uint16_t conn_id, esp_gatt_auth_req_t auth_req); -/******************************************************************************* -** -** @function esp_ble_gattc_write_char_descr -** -** @brief This function is called to write characteristic descriptor value. -** -** @param[in] conn_id : connection ID -** @param[in] srvc_id : service ID. -** @param[in] char_id : characteristic ID. -** @param[in] descr_id : characteristic descriptor ID to write. -** @param[in] value_len: length of the value to be written. -** @param[in] value : the value to be written. -** @param[in] write_type : the type of attribute write operation. -** @param[in] auth_req : authentication request. -** -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_write_char_descr + * + * @brief This function is called to write characteristic descriptor value. + * + * @param[in] conn_id : connection ID + * @param[in] srvc_id : service ID. + * @param[in] char_id : characteristic ID. + * @param[in] descr_id : characteristic descriptor ID to write. + * @param[in] value_len: length of the value to be written. + * @param[in] value : the value to be written. + * @param[in] write_type : the type of attribute write operation. + * @param[in] auth_req : authentication request. + * + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_write_char_descr (uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, @@ -513,23 +526,23 @@ esp_err_t esp_ble_gattc_write_char_descr (uint16_t conn_id, esp_gatt_auth_req_t auth_req); - -/******************************************************************************* -** -** @function esp_ble_gattc_prepare_write -** -** @brief This function is called to prepare write a characteristic value. -** -** @param[in] conn_id : connection ID. -** @param[in] char_id : GATT characteristic ID of the service. -** @param[in] offset : offset of the write value. -** @param[in] value_len: length of the value to be written. -** @param[in] value : the value to be written. -** @param[in] auth_req : authentication request. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_prepare_write + * + * @brief This function is called to prepare write a characteristic value. + * + * @param[in] conn_id : connection ID. + * @param[in] char_id : GATT characteristic ID of the service. + * @param[in] offset : offset of the write value. + * @param[in] value_len: length of the value to be written. + * @param[in] value : the value to be written. + * @param[in] auth_req : authentication request. + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_prepare_write(uint16_t conn_id, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id, @@ -538,56 +551,60 @@ esp_err_t esp_ble_gattc_prepare_write(uint16_t conn_id, uint8_t *value, esp_gatt_auth_req_t auth_req); -/******************************************************************************* -** -** @function esp_ble_gattc_execute_write -** -** @brief This function is called to execute write a prepare write sequence. -** -** @param[in] conn_id : connection ID. -** @param[in] is_execute : execute or cancel. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_execute_write + * + * @brief This function is called to execute write a prepare write sequence. + * + * @param[in] conn_id : connection ID. + * @param[in] is_execute : execute or cancel. + * + * @return - ESP_OK: success + * - other: failed + * + */ esp_err_t esp_ble_gattc_execute_write (uint16_t conn_id, bool is_execute); -/******************************************************************************* -** -** @function esp_ble_gattc_register_for_notify -** -** @brief This function is called to register for notification of a service. -** -** @param[in] gatt_if : gatt interface id. -** @param[in] bda : target GATT server. -** @param[in] srvc_id : pointer to GATT service ID. -** @param[in] char_id : pointer to GATT characteristic ID. -** -** @return OK if registration succeed, otherwise failed. -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_register_for_notify + * + * @brief This function is called to register for notification of a service. + * + * @param[in] gatt_if : gatt interface id. + * @param[in] bda : target GATT server. + * @param[in] srvc_id : pointer to GATT service ID. + * @param[in] char_id : pointer to GATT characteristic ID. + * + * + * @return - ESP_OK: registration succeeds + * - other: failed + * + */ esp_gatt_status_t esp_ble_gattc_register_for_notify (esp_gatt_if_t gatt_if, esp_bd_addr_t server_bda, esp_gatt_srvc_id_t *srvc_id, esp_gatt_id_t *char_id); - -/******************************************************************************* -** -** @function esp_ble_gattc_unregister_ntf -** -** @brief This function is called to de-register for notification of a service. -** -** @param[in] gatt_if : gatt interface id. -** @param[in] bda : target GATT server. -** @param[in] srvc_id : pointer to GATT service ID. -** @param[in] char_id : pointer to GATT characteristic ID. -** -** @return OK if unregister succeed, otherwise failed. -** -*******************************************************************************/ +/** + * + * @function esp_ble_gattc_unregister_ntf + * + * @brief This function is called to de-register for notification of a service. + * + * @param[in] gatt_if : gatt interface id. + * @param[in] bda : target GATT server. + * @param[in] srvc_id : pointer to GATT service ID. + * @param[in] char_id : pointer to GATT characteristic ID. + * + * + * @return - ESP_OK: unregister succeeds + * - other: failed + * + */ esp_gatt_status_t esp_ble_gattc_unregister_for_notify (esp_gatt_if_t gatt_if, esp_bd_addr_t server_bda, esp_gatt_srvc_id_t *srvc_id, diff --git a/components/bt/bluedroid/api/include/esp_gatts_api.h b/components/bt/bluedroid/api/include/esp_gatts_api.h index 157c25c5d5..1492df96a2 100644 --- a/components/bt/bluedroid/api/include/esp_gatts_api.h +++ b/components/bt/bluedroid/api/include/esp_gatts_api.h @@ -21,31 +21,32 @@ #include "bta_gatt_api.h" #include "esp_err.h" -/* GATT Server Data Structure */ -/* Server callback function events */ -#define ESP_GATTS_REG_EVT 0 -#define ESP_GATTS_READ_EVT 1 -#define ESP_GATTS_WRITE_EVT 2 -#define ESP_GATTS_EXEC_WRITE_EVT 3 -#define ESP_GATTS_MTU_EVT 4 -#define ESP_GATTS_CONF_EVT 5 -#define ESP_GATTS_UNREG_EVT 6 -#define ESP_GATTS_CREATE_EVT 7 -#define ESP_GATTS_ADD_INCL_SRVC_EVT 8 -#define ESP_GATTS_ADD_CHAR_EVT 9 -#define ESP_GATTS_ADD_CHAR_DESCR_EVT 10 -#define ESP_GATTS_DELETE_EVT 11 -#define ESP_GATTS_START_EVT 12 -#define ESP_GATTS_STOP_EVT 13 -#define ESP_GATTS_CONNECT_EVT 14 -#define ESP_GATTS_DISCONNECT_EVT 15 -#define ESP_GATTS_OPEN_EVT 16 -#define ESP_GATTS_CANCEL_OPEN_EVT 17 -#define ESP_GATTS_CLOSE_EVT 18 -#define ESP_GATTS_LISTEN_EVT 19 -#define ESP_GATTS_CONGEST_EVT 20 -/* following is extra event */ -#define ESP_GATTS_RESPONSE_EVT 21 +/// GATT Server callback function events +typedef enum { + ESP_GATTS_REG_EVT = 0, /*!< When register application id, the event comes */ + ESP_GATTS_READ_EVT = 1, /*!< When gatt client request read operation, the event comes */ + ESP_GATTS_WRITE_EVT = 2, /*!< When gatt client request write operation, the event comes */ + ESP_GATTS_EXEC_WRITE_EVT = 3, /*!< When gatt client request execute write, the event comes */ + ESP_GATTS_MTU_EVT = 4, /*!< When set mtu complete, the event comes */ + ESP_GATTS_CONF_EVT = 5, /*!< When receive confirm, the event comes */ + ESP_GATTS_UNREG_EVT = 6, /*!< When unregister application id, the event comes */ + ESP_GATTS_CREATE_EVT = 7, /*!< When create service complete, the event comes */ + ESP_GATTS_ADD_INCL_SRVC_EVT = 8, /*!< When add included service complete, the event comes */ + ESP_GATTS_ADD_CHAR_EVT = 9, /*!< When add characteristic complete, the event comes */ + ESP_GATTS_ADD_CHAR_DESCR_EVT = 10, /*!< When add descriptor complete, the event comes */ + ESP_GATTS_DELETE_EVT = 11, /*!< When delete service complete, the event comes */ + ESP_GATTS_START_EVT = 12, /*!< When start service complete, the event comes */ + ESP_GATTS_STOP_EVT = 13, /*!< When stop service complete, the event comes */ + ESP_GATTS_CONNECT_EVT = 14, /*!< When gatt client connect, the event comes */ + ESP_GATTS_DISCONNECT_EVT = 15, /*!< When gatt client disconnect, the event comes */ + ESP_GATTS_OPEN_EVT = 16, /*!< When connect to peer, the event comes */ + ESP_GATTS_CANCEL_OPEN_EVT = 17, /*!< When disconnect from peer, the event comes */ + ESP_GATTS_CLOSE_EVT = 18, /*!< When gatt server close, the event comes */ + ESP_GATTS_LISTEN_EVT = 19, /*!< When gatt listen to be connected the event comes */ + ESP_GATTS_CONGEST_EVT = 20, /*!< When congest happen, the event comes */ + /* following is extra event */ + ESP_GATTS_RESPONSE_EVT = 21, /*!< When gatt send response complete, the event comes */ +} esp_gatts_cb_event_t; /** * @brief Gatt server callback parameters union @@ -237,243 +238,255 @@ typedef union { } rsp; /*!< Gatt server callback param of ESP_GATTS_RESPONSE_EVT */ } esp_ble_gatts_cb_param_t; -/******************************************************************************* -** -** @function esp_ble_gatts_register_callback -** -** @brief This function is called to register application callbacks -** with BTA GATTS module. -** -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_register_callback + * + * @brief This function is called to register application callbacks + * with BTA GATTS module. + * + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_register_callback(esp_profile_cb_t callback); -/******************************************************************************* -** -** @function esp_ble_gatts_app_register -** -** @brief This function is called to register application identifier -** -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_app_register + * + * @brief This function is called to register application identifier + * + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_app_register(uint16_t app_id); -/******************************************************************************* -** -** @function esp_ble_gatts_app_unregister -** -** @brief unregister with GATT Server. -** -** @param[in] gatt_if: gatt interface id. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_app_unregister + * + * @brief unregister with GATT Server. + * + * @param[in] gatt_if: gatt interface id. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatt_if); -/******************************************************************************* -** -** @function esp_ble_gatts_create_service -** -** @brief Create a service. When service creation is done, a callback -** event BTA_GATTS_CREATE_SRVC_EVT is called to report status -** and service ID to the profile. The service ID obtained in -** the callback function needs to be used when adding included -** service and characteristics/descriptors into the service. -** -** @param[in] gatt_if: gatt interface ID -** @param[in] service_id: service ID. -** @param[in] num_handle: number of handle requested for this service. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_create_service + * + * @brief Create a service. When service creation is done, a callback + * event BTA_GATTS_CREATE_SRVC_EVT is called to report status + * and service ID to the profile. The service ID obtained in + * the callback function needs to be used when adding included + * service and characteristics/descriptors into the service. + * + * @param[in] gatt_if: gatt interface ID + * @param[in] service_id: service ID. + * @param[in] num_handle: number of handle requested for this service. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatt_if, esp_gatt_srvc_id_t *service_id, uint16_t num_handle); -/******************************************************************************* -** -** @function esp_ble_gatts_add_included_service -** -** @brief This function is called to add an included service. After included -** service is included, a callback event BTA_GATTS_ADD_INCL_SRVC_EVT -** is reported the included service ID. -** -** @param[in] service_handle: service handle to which this included service is to -** be added. -** @param[in] included_service_handle: the service ID to be included. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_add_included_service + * + * @brief This function is called to add an included service. After included + * service is included, a callback event BTA_GATTS_ADD_INCL_SRVC_EVT + * is reported the included service ID. + * + * @param[in] service_handle: service handle to which this included service is to + * be added. + * @param[in] included_service_handle: the service ID to be included. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle); -/******************************************************************************* -** -** @function esp_ble_gatts_add_char -** -** @brief This function is called to add a characteristic into a service. -** -** @param[in] service_handle: service handle to which this included service is to -** be added. -** @param[in] char_uuid : Characteristic UUID. -** @param[in] perm : Characteristic value declaration attribute permission. -** @param[in] property : Characteristic Properties -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_add_char + * + * @brief This function is called to add a characteristic into a service. + * + * @param[in] service_handle: service handle to which this included service is to + * be added. + * @param[in] char_uuid : Characteristic UUID. + * @param[in] perm : Characteristic value declaration attribute permission. + * @param[in] property : Characteristic Properties + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_add_char(uint16_t service_handle, esp_bt_uuid_t *char_uuid, esp_gatt_perm_t perm, esp_gatt_char_prop_t property); - - -/******************************************************************************* -** -** @function esp_ble_gatts_add_char_descr -** -** @brief This function is called to add characteristic descriptor. When -** it's done, a callback event BTA_GATTS_ADD_DESCR_EVT is called -** to report the status and an ID number for this descriptor. -** -** @param[in] service_handle: service handle to which this characteristic descriptor is to -** be added. -** @param[in] perm: descriptor access permission. -** @param[in] descr_uuid: descriptor UUID. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_add_char_descr + * + * @brief This function is called to add characteristic descriptor. When + * it's done, a callback event BTA_GATTS_ADD_DESCR_EVT is called + * to report the status and an ID number for this descriptor. + * + * @param[in] service_handle: service handle to which this characteristic descriptor is to + * be added. + * @param[in] perm: descriptor access permission. + * @param[in] descr_uuid: descriptor UUID. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_add_char_descr (uint16_t service_handle, esp_bt_uuid_t *descr_uuid, esp_gatt_perm_t perm); -/******************************************************************************* -** -** @function esp_ble_gatts_delete_service -** -** @brief This function is called to delete a service. When this is done, -** a callback event BTA_GATTS_DELETE_EVT is report with the status. -** -** @param[in] service_handled: service_handle to be deleted. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_delete_service + * + * @brief This function is called to delete a service. When this is done, + * a callback event BTA_GATTS_DELETE_EVT is report with the status. + * + * @param[in] service_handled: service_handle to be deleted. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle); -/******************************************************************************* -** -** @function esp_ble_gatts_start_service -** -** @brief This function is called to start a service. -** -** @param[in] service_handle: the service handle to be started. -** @param[in] sup_transport: supported transport. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_start_service + * + * @brief This function is called to start a service. + * + * @param[in] service_handle: the service handle to be started. + * @param[in] sup_transport: supported transport. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_start_service(uint16_t service_handle); -/******************************************************************************* -** -** @function esp_ble_gatts_stop_service -** -** @brief This function is called to stop a service. -** -** @param[in] service_handle - service to be topped. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_stop_service + * + * @brief This function is called to stop a service. + * + * @param[in] service_handle - service to be topped. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle); -/******************************************************************************* -** -** @function esp_ble_gatts_send_indicate -** -** @brief This function is called to read a characteristics descriptor. -** -** @param[in] conn_id - connection id to indicate. -** @param[in] attribute_handle - attribute handle to indicate. -** @param[in] value_len - indicate value length. -** @param[in] value: value to indicate. -** @param[in] need_confirm - if this indication expects a confirmation or not. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_send_indicate + * + * @brief This function is called to read a characteristics descriptor. + * + * @param[in] conn_id - connection id to indicate. + * @param[in] attribute_handle - attribute handle to indicate. + * @param[in] value_len - indicate value length. + * @param[in] value: value to indicate. + * @param[in] need_confirm - if this indication expects a confirmation or not. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_send_indicate(uint16_t conn_id, uint16_t attr_handle, uint16_t value_len, uint8_t *value, bool need_confirm); -/******************************************************************************* -** -** @function esp_ble_gatts_send_rsp -** -** @brief This function is called to send a response to a request. -** -** @param[in] conn_id - connection identifier. -** @param[in] trans_id - transfer id -** @param[in] status - response status -** @param[in] rsp - response data. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_send_rsp + * + * @brief This function is called to send a response to a request. + * + * @param[in] conn_id - connection identifier. + * @param[in] trans_id - transfer id + * @param[in] status - response status + * @param[in] rsp - response data. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_send_response(uint16_t conn_id, uint32_t trans_id, esp_gatt_status_t status, esp_gatt_rsp_t *rsp); -/******************************************************************************* -** -** @function esp_ble_gatts_open -** -** @brief Open a direct open connection or add a background auto connection -** -** @param[in] gatt_if: application ID. -** @param[in] remote_bda: remote device bluetooth device address. -** @param[in] is_direct: direct connection or background auto connection -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_open + * + * @brief Open a direct open connection or add a background auto connection + * + * @param[in] gatt_if: application ID. + * @param[in] remote_bda: remote device bluetooth device address. + * @param[in] is_direct: direct connection or background auto connection + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatt_if, esp_bd_addr_t remote_bda, bool is_direct); -/******************************************************************************* -** -** @function esp_ble_gatts_close -** -** @brief Close a connection a remote device. -** -** @param[in] conn_id: connection ID to be closed. -** -** @return ESP_OK - success, other - failed -** -*******************************************************************************/ +/** + * + * @function esp_ble_gatts_close + * + * @brief Close a connection a remote device. + * + * @param[in] conn_id: connection ID to be closed. + * + * @return - ESP_OK : success + * - other : failed + * + */ esp_err_t esp_ble_gatts_close(uint16_t conn_id);