From: wangmengyang Date: Mon, 26 Dec 2016 14:02:40 +0000 (+0800) Subject: component/bt: modify comment formats for API headers X-Git-Tag: v2.1-rc1~196^2~52 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=9b6247a50702af6ffd9cf5076933f170a47e1c5c;p=esp-idf component/bt: modify comment formats for API headers --- diff --git a/components/bt/bluedroid/api/include/esp_a2dp_api.h b/components/bt/bluedroid/api/include/esp_a2dp_api.h index 7e26a91bb2..5a9c992862 100644 --- a/components/bt/bluedroid/api/include/esp_a2dp_api.h +++ b/components/bt/bluedroid/api/include/esp_a2dp_api.h @@ -4,39 +4,55 @@ #include "esp_err.h" #include "esp_bt_defs.h" -/* Media codec types */ -#define ESP_A2D_MCT_SBC (0) -#define ESP_A2D_MCT_M12 (0x01) -#define ESP_A2D_MCT_M24 (0x02) -#define ESP_A2D_MCT_ATRAC (0x04) +/// Media codec types supported by A2DP +#define ESP_A2D_MCT_SBC (0) /*!< SBC */ +#define ESP_A2D_MCT_M12 (0x01) /*!< MPEG-1, 2 Audio */ +#define ESP_A2D_MCT_M24 (0x02) /*!< MPEG-2, 4 AAC */ +#define ESP_A2D_MCT_ATRAC (0x04) /*!< ATRAC family */ #define ESP_A2D_MCT_NON_A2DP (0xff) typedef uint8_t esp_a2d_mct_t; -/* codec specific information element */ -#define ESP_A2D_CIE_LEN_SBC (4) -#define ESP_A2D_CIE_LEN_M12 (4) -#define ESP_A2D_CIE_LEN_M24 (6) -#define ESP_A2D_CIE_LEN_ATRAC (7) +/** + * @brief Codec specific information for different codec types + */ +/** + * @brief SBC codec specific information + */ typedef struct { +#define ESP_A2D_CIE_LEN_SBC (4) uint8_t oct[ESP_A2D_CIE_LEN_SBC]; } esp_a2d_cie_sbc_t; +/** + * @brief MPEG-1,2 Audio codec specific information + */ typedef struct { +#define ESP_A2D_CIE_LEN_M12 (4) uint8_t oct[ESP_A2D_CIE_LEN_M12]; } esp_a2d_cie_m12_t; +/** + * @brief MPEG-2,4 AAC codec specific information + */ typedef struct { +#define ESP_A2D_CIE_LEN_M24 (6) uint8_t oct[ESP_A2D_CIE_LEN_M24]; } esp_a2d_cie_m24_t; +/** + * @brief ATRAC family codec specific information + */ typedef struct { +#define ESP_A2D_CIE_LEN_ATRAC (7) uint8_t oct[ESP_A2D_CIE_LEN_ATRAC]; } esp_a2d_cie_atrac_t; -/* media codec capabilities */ +/** + * @brief A2DP media codec capabilities union + */ typedef struct { - esp_a2d_mct_t type; /* A2DP media codec type*/ + esp_a2d_mct_t type; /*!< A2DP media codec type */ union { esp_a2d_cie_sbc_t sbc; esp_a2d_cie_m12_t m12; @@ -45,7 +61,7 @@ typedef struct { } cie; } esp_a2d_mcc_t; -/* Bluetooth A2DP connection states */ +/// Bluetooth A2DP connection states typedef enum { ESP_A2D_CONNECTION_STATE_DISCONNECTED = 0, ESP_A2D_CONNECTION_STATE_CONNECTING, @@ -53,19 +69,21 @@ typedef enum { ESP_A2D_CONNECTION_STATE_DISCONNECTING } esp_a2d_connection_state_t; -/* Bluetooth A2DP datapath states */ +/// Bluetooth A2DP datapath states typedef enum { ESP_A2D_AUDIO_STATE_REMOTE_SUSPEND = 0, ESP_A2D_AUDIO_STATE_STOPPED, ESP_A2D_AUDIO_STATE_STARTED, } esp_a2d_audio_state_t; +/// A2DP callback events typedef enum { - ESP_A2D_CONNECTION_STATE_EVT = 0, /*!< connection state changed */ - ESP_A2D_AUDIO_STATE_EVT = 1, /*!< audio stream state changed */ + ESP_A2D_CONNECTION_STATE_EVT = 0, /*!< connection state changed event */ + ESP_A2D_AUDIO_STATE_EVT = 1, /*!< audio stream transmission state changed event */ ESP_A2D_AUDIO_CFG_EVT = 2 /*!< audio codec configuration received */ } esp_a2d_cb_event_t; +/// A2DP state callback parameters typedef union { /*< ESP_A2D_CONNECTION_STATE_EVT */ struct a2d_conn_stat_param { @@ -82,31 +100,77 @@ typedef union { /*< ESP_A2D_AUDIO_CFG_EVT */ struct a2d_audio_cfg_param { esp_bd_addr_t remote_bda; - esp_a2d_mcc_t mcc; + esp_a2d_mcc_t mcc; /*!< A2DP media codec capability information */ } audio_cfg; } esp_a2d_cb_param_t; -typedef void (* esp_a2d_data_cb_t)(uint8_t *buf, uint32_t len); - /** - * NOTE: - * A2DP data path is handled via below function sets, between the Audio HAL - * and the Bluetooth stack. + * @brief A2DP profile data callback function, data is ou + * + * @param[in] buf: data received and decoded to PCM format, buf points to a static memory + * and can be overwritten in later times + * @param[in] len: size(in bytes) in buf + * */ +typedef void (* esp_a2d_data_cb_t)(const uint8_t *buf, uint32_t len); + /** - * Represents the A2DP sink interface. + * @brief This function is called to register application callbacks + * with A2DP module; callbacks will provide the upstream events + * (type esp_a2d_cb_event_t) and paramters(type esp_a2d_cb_param_t) + * + * @param[in] callback: A2DP sink event callback function + * + * @return + * - ESP_OK: success + * */ esp_err_t esp_a2d_register_callback(esp_profile_cb_t callback); + +/** + * @brief This function is called to register A2DP sink data output function + * currently only supports SBC codec, and the output data is PCM format + * + * @param[in] callback: A2DP data callback function + * + * @return + * - ESP_OK: success + * + */ esp_err_t esp_a2d_register_data_callback(esp_a2d_data_cb_t cb); -esp_err_t esp_a2d_sink_init(void); -esp_err_t esp_a2d_sink_connect(esp_bd_addr_t remote_bda); +/** + * + * @brief This function is called to initialize the bluetooth A2DP sink module + * + * @return + * - ESP_OK: success + * - ESP_FAIL: others + * + */ +esp_err_t esp_a2d_sink_init(void); -esp_err_t esp_a2d_sink_disconnect(esp_bd_addr_t remote_bda); +/** + * + * @brief This function is called to deinit and free the resources for A2DP sink module + * + */ void esp_a2d_sink_deinit(void); + +/** + * + * @brief This function is called to disconnect with the remote bluetooth device + * + * @return + * - ESP_OK: disconnect request is sent to lower layer + * - ESP_FAIL: others + * + */ +esp_err_t esp_a2d_sink_disconnect(esp_bd_addr_t remote_bda); + #endif /* __ESP_A2DP_API_H__ */ diff --git a/components/bt/bluedroid/api/include/esp_bt_stack_manager.h b/components/bt/bluedroid/api/include/esp_bt_stack_manager.h index 33045b4e0c..7d8d224f2f 100644 --- a/components/bt/bluedroid/api/include/esp_bt_stack_manager.h +++ b/components/bt/bluedroid/api/include/esp_bt_stack_manager.h @@ -1,14 +1,77 @@ +// Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at + +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + #ifndef __ESP_BT_STACK_MANAGER_H__ #define __ESP_BT_STACK_MANAGER_H__ #include "esp_err.h" +#ifdef __cplusplus +extern "C" { +#endif + +/** + * + * @brief This function is called to initialize the bluetooth stack + * + * @return + * - ESP_OK: success + * - ESP_ERR_INVALID_STATE: if already initialized + * - ESP_FAIL: others + * + */ esp_err_t esp_bt_init_stack(void); + +/** + * + * @brief Deinit and free the resource for bluetooth + * + * @return + * - ESP_OK: success + * - ESP_ERR_INVALID_STATE: if not initailized yet + * + */ esp_err_t esp_bt_deinit_stack(void); + +/** + * + * @brief Enable bluetooth, must after esp_bt_init_stack() + * + * @return + * - ESP_OK: success + * - ESP_ERR_INVALID_STATE: if not initialized yet or already enabled + * - ESP_FAIL: others + * + */ esp_err_t esp_bt_enable_stack(void); + +/** + * @brief Disable bluetooth, must prior to esp_deinit_stack() + * + * @return + * - ESP_OK: success + * - ESP_ERR_INVALID_STATE: if not initialized yet or already enabled + * - ESP_FAIL: others + * + */ esp_err_t esp_bt_disable_stack(void); +#ifdef __cplusplus +} +#endif + #endif /* __ESP_BT_STACK_MANAGER_H__ */ diff --git a/components/bt/bluedroid/api/include/esp_gap_bt_api.h b/components/bt/bluedroid/api/include/esp_gap_bt_api.h index 00fd87e90c..393d33a1d0 100644 --- a/components/bt/bluedroid/api/include/esp_gap_bt_api.h +++ b/components/bt/bluedroid/api/include/esp_gap_bt_api.h @@ -16,18 +16,45 @@ #define __ESP_GAP_BT_API_H__ #include - #include "esp_err.h" #include "esp_bt_defs.h" +#ifdef __cplusplus +extern "C" { +#endif + +/// Discoverability and Connectability mode typedef enum { - BT_SCAN_MODE_NONE = 0, - BT_SCAN_MODE_CONNECTABLE, - BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE + BT_SCAN_MODE_NONE = 0, /*!< Neither discoverable nor connectable */ + BT_SCAN_MODE_CONNECTABLE, /*!< Connectable but not discoverable */ + BT_SCAN_MODE_CONNECTABLE_DISCOVERABLE /*!< both discoverable and connectaable */ } bt_scan_mode_t; +/** + * @brief Set discoverability and connectability mode for legacy bluetooth + * + * @param[in] mode: one of the enums of bt_scan_mode_t + * + * @return + * - ESP_OK : Succeed + * - ESP_ERR_INVALID_ARG: if argument invalid + */ esp_err_t esp_bt_gap_set_scan_mode(bt_scan_mode_t mode); + +/** + * @brief Set bluetooth device name + * + * @param[in] name: device name to be set, will be truncated if more than 32 characters + * + * @return + * - ESP_OK : Succeed + * - ESP_ERR_INVALID_ARG: if name is NULL pointer or empty string + */ esp_err_t esp_bt_gap_set_device_name(const char *name); +#ifdef __cplusplus +} +#endif + #endif /* __ESP_GAP_BT_API_H__ */ diff --git a/components/bt/bluedroid/btif/btif_media_task.c b/components/bt/bluedroid/btif/btif_media_task.c index f7b552cf1f..c2ab0bc6cd 100644 --- a/components/bt/bluedroid/btif/btif_media_task.c +++ b/components/bt/bluedroid/btif/btif_media_task.c @@ -823,7 +823,7 @@ static void btif_media_task_handle_inc_media(tBT_SBC_HDR *p_msg) // LOG_ERROR("pre-send: %d\n", availPcmBytes); // UIPC_Send(UIPC_CH_ID_AV_AUDIO, 0, (UINT8 *)pcmData, (2 * sizeof(pcmData) - availPcmBytes)); - BTIF_A2D_DATA_CB_TO_APP((uint8_t *)pcmData, (2 * sizeof(pcmData) - availPcmBytes)); + BTIF_A2D_DATA_CB_TO_APP((const uint8_t *)pcmData, (2 * sizeof(pcmData) - availPcmBytes)); } #endif diff --git a/components/bt/bluedroid/btif/stack_manager.c b/components/bt/bluedroid/btif/stack_manager.c index f44a707cf9..d3df7ea8bd 100644 --- a/components/bt/bluedroid/btif/stack_manager.c +++ b/components/bt/bluedroid/btif/stack_manager.c @@ -75,6 +75,11 @@ static bt_status_t event_start_up_stack(void) static bt_status_t event_shut_down_stack(void) { + if (!stack_is_initialized) { + LOG_DEBUG("%s stack not initialized yet.\n", __func__); + return BT_STATUS_NOT_READY; + } + if (!stack_is_running) { LOG_DEBUG("%s stack is already brought down.\n", __func__); return BT_STATUS_DONE; @@ -152,7 +157,9 @@ esp_err_t esp_bt_disable_stack(void) status = event_shut_down_stack(); switch (status) { case BT_STATUS_SUCCESS: return ESP_OK; - case BT_STATUS_DONE: return ESP_ERR_INVALID_STATE; + case BT_STATUS_NOT_READY: + case BT_STATUS_DONE: + return ESP_ERR_INVALID_STATE; default: return ESP_FAIL; } }