From f17d6bde64b9504c76198f8bcc97de6fb5ad0002 Mon Sep 17 00:00:00 2001 From: jiachanglin Date: Tue, 14 Jun 2022 06:44:55 +0000 Subject: [PATCH] fix: Modified about Add WLAN HDI zh-CN and en review Signed-off-by: jiachanglin --- zh-cn/device_api/hdi/wlan/wifi_hal.h | 69 +++++++++--------- .../device_api/hdi/wlan/wifi_hal_ap_feature.h | 24 +++---- .../hdi/wlan/wifi_hal_base_feature.h | 70 ++++++++----------- .../hdi/wlan/wifi_hal_sta_feature.h | 20 +++--- 4 files changed, 87 insertions(+), 96 deletions(-) diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal.h b/zh-cn/device_api/hdi/wlan/wifi_hal.h index ef4f1ac3..6c624f6e 100644 --- a/zh-cn/device_api/hdi/wlan/wifi_hal.h +++ b/zh-cn/device_api/hdi/wlan/wifi_hal.h @@ -17,7 +17,7 @@ * @addtogroup WLAN * @{ * - * @brief WLAN可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * @brief WLAN模块向上层WLAN服务提供了统一接口。 * * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 * @@ -29,7 +29,7 @@ /** * @file wifi_hal.h * - * @brief 提供给wifi service的WLAN基本能力接口。 + * @brief 提供给WLAN服务的WLAN基本能力接口。 * * @since 1.0 * @version 1.0 @@ -50,9 +50,9 @@ extern "C" { /** * @brief 定义IWiFi回调函数的原型，监听异步事件。 * - * @param event 回调传入的事件类型标识 - * @param data 回调传入的数据 - * @param ifName 网卡名字 + * @param event 输入参数，回调传入的事件类型标识。 + * @param data 输入参数，回调传入的数据。 + * @param ifName 输入参数，网卡名称。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -63,7 +63,7 @@ extern "C" { typedef int32_t (*CallbackFunc)(uint32_t event, void *data, const char *ifName); /** - * @brief HAL对wifi service提供的基本能力。 + * @brief HAL对WLAN服务提供的基本能力。 * * 用于创建HAL与驱动的通道，创建/获取/销毁WLAN特性等。 * @@ -73,9 +73,9 @@ typedef int32_t (*CallbackFunc)(uint32_t event, void *data, const char *ifName); */ struct IWiFi { /** - * @brief 创建HAL和驱动之间的通道及获取驱动网卡信息。 + * @brief 创建HAL和驱动之间的通道及获取驱动网卡信息，该函数调用在创建IWiFi实体后进行。 * - * @param iwifi IWiFi对象{@link IWiFi} + * @param iwifi 输入参数，IWiFi对象。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -86,9 +86,9 @@ struct IWiFi { int32_t (*start)(struct IWiFi *iwifi); /** - * @brief 销毁通道。 + * @brief 销毁HAL和驱动之间的通道，该函数调用在销毁IWiFi实体前进行。 * - * @param iwifi IWiFi对象{@link IWiFi} + * @param iwifi 输入参数，IWiFi对象。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -102,8 +102,8 @@ struct IWiFi { * @brief 获取该设备支持的WLAN特性（不考虑当前的使用状态）。 * * - * @param supType 保存当前设备支持的特性 - * @param size supType数组的长度 + * @param supType 输出参数，保存当前设备支持的特性。 + * @param size 输入参数，supType数组的长度。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -117,8 +117,8 @@ struct IWiFi { * @brief 获取多网卡共存情况。 * * - * @param combo 基于芯片的能力保存当前所有支持的多网卡共存情况（比如支持AP，STA，P2P等不同组合的共存） - * @param size combo数组的长度 + * @param combo 输出参数，基于芯片的能力保存当前所有支持的多网卡共存情况（比如支持AP，STA，P2P等不同组合的共存）。 + * @param size 输入参数，combo数组的长度。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -131,8 +131,8 @@ struct IWiFi { /** * @brief 根据输入类型创建对应的特性{@link IWiFiBaseFeature}。 * - * @param type 创建的feature类型 - * @param ifeature 获取创建的feature对象 + * @param type 输入参数，创建的feature类型。 + * @param ifeature 输出参数，获取创建的feature对象。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -145,8 +145,8 @@ struct IWiFi { /** * @brief 通过网络接口名字获取对应的特性。 * - * @param ifName 网络接口的名字 - * @param ifeature 获取该网络接口名字的feature对象 + * @param ifName 输入参数，网卡名称。 + * @param ifeature 输出参数，获取该网络接口名字的feature对象。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -159,8 +159,8 @@ struct IWiFi { /** * @brief 注册IWiFi的回调函数，监听异步事件。 * - * @param cbFunc 注册的回调函数 - * @param ifName 网卡名字 + * @param cbFunc 输入参数，注册的回调函数。 + * @param ifName 输入参数，网卡名称。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -173,8 +173,8 @@ struct IWiFi { /** * @brief 去注册IWiFi的回调函数。 - * @param cbFunc 去注册的回调函数 - * @param ifName 网卡名字 + * @param cbFunc 输入参数，去注册的回调函数。 + * @param ifName 输入参数，网卡名称。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -185,9 +185,9 @@ struct IWiFi { int32_t (*unregisterEventCallback)(CallbackFunc cbFunc, const char *ifName); /** - * @brief 销毁对应的特性。 + * @brief 根据输入类型销毁对应的特性{@link IWiFiBaseFeature}。 * - * @param ifeature 销毁的feature对象 + * @param ifeature 输入参数，销毁的feature对象。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -198,9 +198,10 @@ struct IWiFi { int32_t (*destroyFeature)(struct IWiFiBaseFeature *ifeature); /** - * @brief WLAN驱动进行重置。 + * @brief 重置具有指定芯片ID的WLAN驱动程序。 * - * @param chipId 驱动进行重置对应的芯片ID + * @param chipId 输入参数，需要进行重置驱动的对应芯片ID。 + * @param ifName 输入参数，网卡名称。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -211,9 +212,9 @@ struct IWiFi { int32_t (*resetDriver)(const uint8_t chipId, const char *ifName); /** - * @brief 获取网络设备信息 + * @brief 获取网络设备信息（设备索引、网卡名字、MAC等信息）。 * - * @param netDeviceInfoResult 得到的网络设备信息 + * @param netDeviceInfoResult 输出参数，得到的网络设备信息。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -224,10 +225,10 @@ struct IWiFi { int32_t (*getNetDevInfo)(struct NetDeviceInfoResult *netDeviceInfoResult); /** - * @brief 获取正在使用的功率模式 + * @brief 获取正在使用的功率模式。 * - * @param ifName 网卡名字 - * @param mode 功率模式（包含睡眠模式、一般模式、穿墙模式） + * @param ifName 输入参数，网卡名称。 + * @param mode 输出参数，功率模式，包括睡眠模式（待机状态运行）、一般模式（正常额定功率运行）、穿墙模式（最大功率运行，提高信号强度和覆盖面积）。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -240,8 +241,8 @@ struct IWiFi { /** * @brief 设置功率模式 * - * @param ifName 网卡名字 - * @param mode 功率模式（包含睡眠模式、一般模式、穿墙模式） + * @param ifName 输入参数，网卡名称。 + * @param mode 输入参数，功率模式,包括睡眠模式（待机状态运行）、一般模式（正常额定功率运行）、穿墙模式（最大功率运行，提高信号强度和覆盖面积）。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -266,7 +267,7 @@ struct IWiFi { int32_t WifiConstruct(struct IWiFi **wifiInstance); /** - * @brief 销毁IWiFi结构体。 + * @brief 销毁IWiFi结构体并释放相关资源。 * * @param wifiInstance HAL服务对象{@link IWiFi} * diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal_ap_feature.h b/zh-cn/device_api/hdi/wlan/wifi_hal_ap_feature.h index b16b7c49..ecc2d055 100644 --- a/zh-cn/device_api/hdi/wlan/wifi_hal_ap_feature.h +++ b/zh-cn/device_api/hdi/wlan/wifi_hal_ap_feature.h @@ -17,7 +17,7 @@ * @addtogroup WLAN * @{ * - * @brief WLAN可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * @brief WLAN模块向上层WLAN服务提供了统一接口。 * * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 * @@ -28,7 +28,7 @@ /** * @file wifi_hal_ap_feature.h * - * @brief 提供WLAN的AP特性能力。 + * @brief 提供WLAN的AP特性能力（获取与AP连接的STA的基本信息、设置国家码）。 * * @since 1.0 * @version 1.0 @@ -69,10 +69,10 @@ struct IWiFiAp { /** * @brief 获取连接上的所有STA的信息（目前只包含MAC地址）。 * - * @param apFeature AP特性{@link IWiFiAp} - * @param staInfo 保存与AP连接的STA的基本信息 - * @param count staInfo结构体数组的元素个数 - * @param num 实际连接的STA的个数 + * @param apFeature 输入参数，AP特性{@link IWiFiAp}。 + * @param staInfo 输出参数，保存与AP连接的STA的基本信息。 + * @param count 输入参数，staInfo结构体数组的元素个数。 + * @param num 输出参数，实际连接的STA的个数。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -83,11 +83,11 @@ struct IWiFiAp { uint32_t count, uint32_t *num); /** - * @brief 设置国家码。 + * @brief 设置国家码（表示AP射频所在的国家，规定了AP射频特性，包括AP的发送功率、支持的信道等。其目的是为了使AP的射频特性符合不同国家或区域的法律法规要求）。 * - * @param apFeature apFeature AP特性{@link IWiFiAp} - * @param code 设置的国家码 - * @param len 国家码长度 + * @param apFeature 输入参数，AP特性{@link IWiFiAp}。 + * @param code 输入参数，设置的国家码。 + * @param len 输入参数，国家码长度。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -99,9 +99,9 @@ struct IWiFiAp { }; /** - * @brief 初始化AP特性。wifi service在创建AP类型的特性{@link FeatureType}时调用。 + * @brief 初始化AP特性。WLAN服务在创建AP类型的特性{@link FeatureType}时调用。 * - * @param fe AP特性{@link IWiFiAp} + * @param fe 输入参数，AP特性{@link IWiFiAp}。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal_base_feature.h b/zh-cn/device_api/hdi/wlan/wifi_hal_base_feature.h index cbffa097..f08fc5b5 100644 --- a/zh-cn/device_api/hdi/wlan/wifi_hal_base_feature.h +++ b/zh-cn/device_api/hdi/wlan/wifi_hal_base_feature.h @@ -17,7 +17,7 @@ * @addtogroup WLAN * @{ * - * @brief WLAN 可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * @brief WLAN模块向上层WLAN服务提供了统一接口。 * * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 * @@ -47,30 +47,20 @@ extern "C" { /** * @brief 网卡名称最大长度。 - * - * @since 1.0 - * @version 1.0 */ #define IFNAME_MAX_LEN 16 /** * @brief WLAN的MAC地址长度。 - * - * @since 1.0 - * @version 1.0 */ #define WIFI_MAC_ADDR_LENGTH 6 /** - * @brief 访问失败。 - * - * @since 1.0 - * @version 1.0 + * @brief 定义访问失败错误码。 */ #define ERR_UNAUTH_ACCESS (-6) /** - * @brief 特性的类型{@link FeatureType}。 + * @brief 枚举WLAN相关特性的类型{@link FeatureType}。 * - * @since 1.0 * @version 1.0 */ typedef enum { @@ -101,7 +91,7 @@ typedef enum { } FeatureType; /** - * @brief 基本特性，包含获取网络接口名称，设置MAC地址，设置发射功率等公共能力接口。 + * @brief WLAN基本特性操作接口，包括获取网卡名称，设置MAC地址，设置发射功率等公共能力接口。 * * @since 1.0 * @version 1.0 @@ -113,9 +103,9 @@ struct IWiFiBaseFeature { int32_t type; /** - * @brief 获取网络接口的名字。 + * @brief 根据基本特性获取网卡名称。 * - * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * @param baseFeature 输入参数，基本特性{@link IWiFiBaseFeature}。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -126,9 +116,9 @@ struct IWiFiBaseFeature { const char *(*getNetworkIfaceName)(const struct IWiFiBaseFeature *baseFeature); /** - * @brief 获取特性的类型。 + * @brief 获取基本特性的类型{@link FeatureType}。 * - * @param baseFeature 基本特性{@link IWiFiBaseFeature} + * @param baseFeature 输入参数，基本特性{@link IWiFiBaseFeature}。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -139,11 +129,11 @@ struct IWiFiBaseFeature { int32_t (*getFeatureType)(const struct IWiFiBaseFeature *baseFeature); /** - * @brief 设置MAC地址。 + * @brief 根据传入参数设置对应网卡的MAC地址。 * - * @param baseFeature 基本特性{@link IWiFiBaseFeature} - * @param mac 设置的MAC地址 - * @param len 设置的MAC地址长度 + * @param baseFeature 输入参数，基本特性{@link IWiFiBaseFeature}。 + * @param mac 输入参数，设置的MAC地址。 + * @param len 输入参数，设置的MAC地址长度。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -156,9 +146,9 @@ struct IWiFiBaseFeature { /** * @brief 获取设备的MAC地址。 * - * @param baseFeature 基本特性{@link IWiFiBaseFeature} - * @param mac 获得的MAC地址 - * @param len 获得的MAC地址长度 + * @param baseFeature 输入参数，基本特性{@link IWiFiBaseFeature}。 + * @param mac 输出参数，获得的MAC地址。 + * @param len 输入参数，获得的MAC地址长度。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -171,11 +161,11 @@ struct IWiFiBaseFeature { /** * @brief 获取指定频段（2.4G或者5G）下支持的频率。 * - * @param baseFeature 基本特性{@link IWiFiBaseFeature} - * @param band 指定的一个频段 - * @param freqs 保存支持的频率 - * @param count 频率数组的元素个数 - * @param num 实际支持的频率个数 + * @param baseFeature 输入参数，基本特性{@link IWiFiBaseFeature}。 + * @param band 输入参数，指定的一个频段。 + * @param freqs 输出参数，保存支持的频率。 + * @param count 输入参数，频率数组的元素个数。 + * @param num 输出参数，实际支持的频率个数。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -189,8 +179,8 @@ struct IWiFiBaseFeature { /** * @brief 设置发射功率。 * - * @param baseFeature 基本特性{@link IWiFiBaseFeature} - * @param power 设置的发射功率 + * @param baseFeature 输入参数，基本特性{@link IWiFiBaseFeature}。 + * @param power 输入参数，设置的发射功率。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -203,8 +193,8 @@ struct IWiFiBaseFeature { /** * @brief 获得当前驱动的芯片ID。 * - * @param baseFeature 基本特性{@link IWiFiBaseFeature} - * @param chipId 获得的芯片ID + * @param baseFeature 输入参数，基本特性{@link IWiFiBaseFeature}。 + * @param chipId 输出参数，获得的芯片ID。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -215,11 +205,11 @@ struct IWiFiBaseFeature { int32_t (*getChipId)(const struct IWiFiBaseFeature *baseFeature, uint8_t *chipId); /** - * @brief 通过芯片ID获得当前芯片所有的网卡名。 + * @brief 通过芯片ID获得当前芯片所有的网卡名称。 * - * @param chipId 驱动进行重置对应的芯片ID - * @param ifNames 网卡名字 - * @param num 网卡的数量 + * @param chipId 输入参数，需要获取网卡名称的芯片ID。 + * @param ifNames 输出参数，网卡名称。 + * @param num 输出参数，网卡的数量。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -231,9 +221,9 @@ struct IWiFiBaseFeature { }; /** - * @brief 初始化基本特性。用于wifi service在创建任何类型的特性{@link FeatureType}时。 + * @brief WLAN服务创建任何类型的特性{@Link FeatureType}时，都需要调用此函数。 * - * @param fe 基本特性{@link IWiFiBaseFeature} + * @param fe 输入参数，基本特性{@link IWiFiBaseFeature}。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 diff --git a/zh-cn/device_api/hdi/wlan/wifi_hal_sta_feature.h b/zh-cn/device_api/hdi/wlan/wifi_hal_sta_feature.h index 78a47ec4..e687b3b0 100644 --- a/zh-cn/device_api/hdi/wlan/wifi_hal_sta_feature.h +++ b/zh-cn/device_api/hdi/wlan/wifi_hal_sta_feature.h @@ -17,7 +17,7 @@ * @addtogroup WLAN * @{ * - * @brief WLAN可实现跨操作系统迁移，自适应器件差异，模块化拼装编译。 + * @brief WLAN模块向上层WLAN服务提供了统一接口。 * * HDI层开发人员可根据WLAN模块提供的向上统一接口获取如下能力：建立/关闭WLAN热点，扫描，关联WLAN热点，WLAN平台芯片管理，网络数据缓冲的申请、释放、移动等操作，网络设备管理，电源管理等。 * @@ -29,7 +29,7 @@ /** * @file wifi_hal_sta_feature.h * - * @brief 提供WLAN的sta特性能力。 + * @brief 提供WLAN的STA特性能力。 * * @since 1.0 * @version 1.0 @@ -61,9 +61,9 @@ struct IWiFiSta { /** * @brief 设置扫描单个MAC地址。 * - * @param staFeature STA特性{@link IWiFiSta} - * @param scanMac 设置STA扫描的MAC地址 - * @param len MAC地址的长度 + * @param staFeature 输入参数，STA特性{@link IWiFiSta}。 + * @param scanMac 输入参数，设置STA扫描的MAC地址。 + * @param len 输入参数，MAC地址的长度。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -74,10 +74,10 @@ struct IWiFiSta { int32_t (*setScanningMacAddress)(const struct IWiFiSta *staFeature, unsigned char *scanMac, uint8_t len); /** - * @brief 启动扫描 + * @brief 启动扫描。 * - * @param ifName 网卡名字 - * @param scan 扫描参数 + * @param ifName 输入参数，网卡名称。 + * @param scan 输入参数，扫描参数。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 @@ -89,9 +89,9 @@ struct IWiFiSta { }; /** - * @brief 初始化STA特性。wifi service在创建STA类型的特性{@link FeatureType}时调用。 + * @brief 初始化STA特性。WLAN服务在创建STA类型的特性{@link FeatureType}时调用。 * - * @param fe STA特性{@link IWiFiSta} + * @param fe 输出参数，STA特性{@link IWiFiSta}。 * * @return 如果操作成功，则返回0。 * @return 如果操作失败，则返回负值。 -- Gitee