1/* 2 * @file hi_any_api.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18/** 19 * @defgroup hi_wifi_any ANY API 20 * @ingroup hi_wifi 21 */ 22 23#ifndef __HI_ANY_API_H__ 24#define __HI_ANY_API_H__ 25 26#ifdef __cplusplus 27#if __cplusplus 28extern "C" { 29#endif 30#endif 31 32/** 33 * @ingroup hi_wifi_any 34 * 35 * Max length of data for a single ANY transmit.CNcomment:单次ANY发送允许的最大数据长度。CNend 36 */ 37#define WIFI_ANY_MAX_USER_DATA 250 38/** 39 * @ingroup hi_wifi_any 40 * 41 * Length of key in octets used in ANY communication.CNcomment:ANY加密通信的密钥长度，固定为16字节。CNend 42 */ 43#define WIFI_ANY_KEY_LEN 16 44/** 45 * @ingroup hi_wifi_any 46 * 47 * Length of MAC address.CNcomment:MAC地址长度定义CNend 48 */ 49#define WIFI_ANY_MAC_LEN 6 50/** 51 * @ingroup hi_wifi_any 52 * 53 * Max length of wlan ssid(for driver).CNcomment:wifi驱动SSID最大长度,+1为\0预留空间CNend 54 */ 55#define WIFI_ANY_MAX_SSID_LEN (32 + 1) 56 57/** 58 * @ingroup hi_wifi_any 59 * 60 * Struct of peer's information.CNcomment:用户向驱动配置的对端设备信息数据CNend 61 */ 62typedef struct { 63 unsigned char mac[WIFI_ANY_MAC_LEN]; /**< the MAC address for peer device. */ 64 /**< CNcomment: 收发操作的对端MAC地址 */ 65 unsigned char channel; /**< the channel number of peer device,the value 66 0xFF means current channel. */ 67 /**< CNcomment: 对端所在信道号，驱动对该信息仅做存储，0xFF表示当前信道 */ 68 bool has_key; /**< whether need key for packet encryption,if true,key shall be specified. */ 69 /**< CNcomment: 是否配置通信密钥，是则填true，并在key中传入密钥，否则填false */ 70 unsigned char key[WIFI_ANY_KEY_LEN]; /**< the key for packet encryption,it consists of 16 bytes. */ 71 /**< CNcomment: 用于加密通信的密钥，填充的密钥固定为16字节长度 */ 72} hi_wifi_any_peer_info; 73 74/** 75 * @ingroup hi_wifi_any 76 * 77 * Struct of information of ANY device discovered.CNcomment:扫描发现的ANY设备的参数定义CNend 78 */ 79typedef struct { 80 unsigned char bssid[WIFI_ANY_MAC_LEN]; /**< the MAC address of peer device. */ 81 /**< CNcomment: BSSID,若对端为STA则为其MAC地址 */ 82 unsigned char channel; /**< the channel number of peer device. */ 83 /**< CNcomment: 信道号，取值范围1-14，不同区域取值范围有差异 */ 84 unsigned char sta_flag; /**< if peer device is a STA,the value is true,otherwise false. */ 85 /**< CNcomment: true表示对端是STA，否则为普通AP */ 86 unsigned char ssid[WIFI_ANY_MAX_SSID_LEN]; /**< SSID. *//**< CNcomment: SSID */ 87 unsigned char ssid_len; /**< the string length of SSID. *//**< CNcomment: SSID字符串长度 */ 88 char rssi; /**< RSSI value of peer device. *//**< CNcomment: 信号强度 */ 89 unsigned char resv; /**< Reserved. *//**< CNcomment: 保留 */ 90} hi_wifi_any_device; 91 92/** 93* @ingroup hi_wifi_any 94* @brief Callback function invoked when ANY scan is finished.CNcomment:ANY扫描完成回调函数CNend 95* 96* @par Description: 97* When registered,the driver uses this callback to deliver ANY devices found after an ANY scan. \n 98* CNcomment:注册该回调函数之后，驱动每次完成ANY扫描调用该接口反馈结果给上层.CNend 99* 100* @attention 1. This function is called in driver context,should not be blocked or do long time waiting.\n 101 CNcomment:1. 该回调函数运行于驱动线程，不能阻塞或长时间等待.CNend \n 102* 2. The memories of <devices> are requested and freed by the driver automatically.\n 103* CNcomment:2. <devices>由驱动申请内存，也由驱动释放，回调中不应释放.CNend 104* @param devices [IN] Type #hi_wifi_any_device *, array of poniter of ANY devices found.CNcomment:发现的ANY设备信息, 105* 该参数为指针类型的数组。CNend 106* @param num [IN] Type #unsigned char, the number of ANY devices found, maximum is 32.CNcomment:发现的设备数量, 107* 最大不超过32.CNend 108* 109* @retval #void no return value.CNcomment:无返回值.CNend 110* @par Dependency: 111* @li hi_any_api.h: ANY API 112* @see hi_wifi_any_discover_peer 113*/ 114typedef void (*hi_wifi_any_scan_result_cb)(hi_wifi_any_device *devices[], unsigned char num); 115 116/** 117* @ingroup hi_wifi_any 118* @brief Callback function for ANY RX.CNcomment:ANY驱动接收回调函数CNend 119* 120* @par Description: 121* When registered,the driver uses this callback to deliver data received. \n 122* CNcomment:注册该回调函数之后，驱动收到ANY报文则调用该回调函数传递给上层应用.CNend 123* 124* @attention 1. This function is called in driver context,should not be blocked or do long time waiting.\n 125 CNcomment:1. 该回调函数运行于驱动线程，不能阻塞或长时间等待.CNend\n 126* 2. The memories of <mac> and <data> are requested and freed by the driver.\n 127* CNcomment:2. <mac>和<data>由驱动申请内存,也由驱动释放，回调中不应释放.CNend 128* @param mac [IN] Type #unsigned char *, MAC address with 6 octets length.CNcomment:6字节长度MAC地址.CNend 129* @param data [IN] Type #unsigned char *, the address of data received.CNcomment:接收到数据的缓存地址.CNend 130* @param len [IN] Type #unsigned short, the length in octet of data received.CNcomment:接收的数据长度， 131* 最大为250字节.CNend 132* @param seqnum [IN] Type #unsigned char, the sequence number of the ANY frame, range [0-255]. 133* CNcomment:接收到的ANY帧的序列号,范围0-255.CNend 134* 135* @retval #void no return value.CNcomment:无返回值.CNend 136* @par Dependency: 137* @li hi_any_api.h: ANY API 138* @see hi_wifi_any_set_callback 139*/ 140typedef void (*hi_wifi_any_recv_cb)(unsigned char *mac, unsigned char *data, unsigned short len, unsigned char seqnum); 141 142/** 143* @ingroup hi_wifi_any 144* @brief Callback function for ANY TX.CNcomment:ANY驱动发送回调函数CNend 145* 146* @par Description: 147* When registered,the driver uses this callback to notify whether an ACK has received. \n 148* CNcomment:注册该回调函数之后，驱动将发送结果(是否收到ACK)反馈给上层应用.CNend 149* 150* @attention 1. This function is called in driver context,should not be blocked or do long time waiting.\n 151 CNcomment:1. 该回调函数运行于驱动线程，不能阻塞或长时间等待.CNend \n 152* 2. The memories of <mac> are requested and freed by the driver.\n 153* CNcomment:2. <mac>由驱动申请内存，也由驱动释放，回调中不应释放.CNend 154* @param mac [IN] Type #unsigned char *, MAC address with 6 octets length.CNcomment:6字节长度MAC地址.CNend 155* @param status [IN] Type #unsigned char, the result of a single transmit,return 1 if transmitted successfully. 156 CNcomment:单次发送的结果, 值为1代表发送成功，其他值代表发送失败.CNend 157* @param seqnum [IN] Type #unsigned char, the sequence number of the ANY frame, range [0-255]. 158* CNcomment:接收到的ANY帧的序列号,范围0-255.CNend 159* 160* @retval #void no return value.CNcomment:无返回值.CNend 161* @par Dependency: 162* @li hi_any_api.h: ANY API 163* @see hi_wifi_any_set_callback 164*/ 165typedef void (*hi_wifi_any_send_complete_cb)(unsigned char *mac, unsigned char status, unsigned char seqnum); 166 167/** 168 * @ingroup hi_wifi_any 169 * 170 * Struct of ANY callback function.CNcomment:ANY收发回调接口定义CNend 171 */ 172typedef struct { 173 hi_wifi_any_send_complete_cb send_cb; /**< the callback function invoked when an ANY frame is sent. */ 174 /**< CNcomment: ANY发送完成驱动回调函数，用于将驱动发送结果反馈给上层 */ 175 hi_wifi_any_recv_cb recv_cb; /**< the callback function invoked when an ANY frame is received. */ 176 /**< CNcomment: ANY接收数据驱动回调函数，用于将驱动接收的数据传递给上层 */ 177} hi_wifi_any_callback; 178 179/** 180* @ingroup hi_wifi_any 181* @brief Use this funtion to initialize ANY feature.CNcomment:ANY功能初始化函数CNend 182* 183* @par Description: 184* Use this funtion to initialize ANY feature.CNcomment:ANY功能初始化函数CNend 185* 186* @attention A device shall be intialized only once, do de-initialzing first before perform a new initialization.\n 187 CNcomment:一个设备只允许一次初始化，重新初始化之前需要先调用去ANY初始化.CNend \n 188* @param seqnum [IN] Type #const char *, the interface name used to TX/RX ANY frames, eg.wlan0/ap0/mesh0. 189* CNcomment:用于收发ANY报文的接口名称，常用值为"wlan0","ap0"或"mesh0".CNend 190* 191* @retval #HISI_OK Excute successfully 192* @retval #Other Error code 193* @par Dependency: 194* @li hi_any_api.h: ANY API 195* @see NULL 196*/ 197int hi_wifi_any_init(const char *ifname); 198 199/** 200* @ingroup hi_wifi_any 201* @brief Use this funtion to de-initialize ANY feature.CNcomment:ANY功能去初始化函数CNend 202* 203* @par Description: 204* Use this funtion to de-initialize ANY feature.CNcomment:ANY功能去初始化函数CNend 205* 206* @attention NULL 207* @param NULL 208* 209* @retval #HISI_OK Excute successfully 210* @retval #Other Error code 211* @par Dependency: 212* @li hi_any_api.h: ANY API 213* @see NULL 214*/ 215int hi_wifi_any_deinit(void); 216 217/** 218* @ingroup hi_wifi_any 219* @brief Register callback functions for ANY TX and RX.CNcomment:注册ANY驱动发送回调函数和接收回调函数CNend 220* 221* @par Description: 222* Register callback functions for ANY TX and RX.CNcomment:注册ANY驱动发送回调函数和接收回调函数CNend 223* 224* @attention APP shall implement the TX/RX callbacks and register them to driver through this function.\n 225 CNcomment:需要用户自己实现该回调函数功能并通过上述接口注册给驱动.CNend 226* @param send_cb [IN] Type #hi_wifi_any_send_complete_cb, callback function for ANY TX. 227* CNcomment:ANY驱动发送回调函数.CNend 228* @param recv_cb [IN] Type #hi_wifi_any_recv_cb, callback function for ANY RX. 229* CNcomment:ANY驱动接收回调函数.CNend 230* 231* @retval #void no return value.CNcomment:无返回值.CNend 232* @par Dependency: 233* @li hi_any_api.h: ANY API 234* @see hi_wifi_any_send_complete_cb | hi_wifi_any_recv_cb 235*/ 236void hi_wifi_any_set_callback(hi_wifi_any_send_complete_cb send_cb, hi_wifi_any_recv_cb recv_cb); 237 238/** 239* @ingroup hi_wifi_any 240* @brief Send ANY frame to specific mac address.CNcomment:向指定MAC地址的设备发送ANY数据。CNend 241* 242* @par Description: 243* Frame TX interface of ANY, specify frame's sequece number by seq. \n 244* the mac_len shall be constant 6 and data_len for a frame should not exceed 250 octets. \n 245* CNcomment:ANY报文发送接口，可以通过seq指定该报文的发送序列号。\n 246* 其中MAC地址长度固定填6字节，待发送的数据长度data_len不能超过250字节 CNend 247* 248* @attention The memories of <mac> and <data> are requested and freed by user APP.\n 249* CNcomment:<mac>和<data>内存由用户申请和管理，执行完成后驱动不会释放.CNend 250* @param mac [IN] Type #const unsigned char *, destination MAC address, it may be unicast or broadcast. 251* CNcomment:6字节长度目的MAC地址, 可为单播或者广播地址, 不支持组播地址.CNend 252* @param mac_len [IN] Type #unsigned char, length of MAC address which shall be 6 in octet. 253* CNcomment:MAC地址长度, 需为6字节.CNend 254* @param data [IN] Type #unsigned char *, the address of data.CNcomment:待发送数据的缓存地址.CNend 255* @param len [IN] Type #unsigned short, the length in octet of data, maximum is 250. 256* CNcomment:待发送的数据长度, 最大为250字节.CNend 257* @param seqnum [IN] Type #unsigned char, the sequence number of the ANY frame, range [0-255]. 258* CNcomment:待发送的ANY帧的序列号,范围0-255.CNend 259* 260* @retval #HISI_OK Excute successfully 261* @retval #Other Error code 262* @par Dependency: 263* @li hi_any_api.h: ANY API 264* @see hi_wifi_any_send_complete_cb 265*/ 266int hi_wifi_any_send(const unsigned char *mac, unsigned char mac_len, unsigned char *data, 267 unsigned short data_len, unsigned char seq); 268 269/** 270* @ingroup hi_wifi_any 271* @brief Add information of ANY peer device.CNcomment:添加ANY对端设备信息。CNend 272* 273* @par Description: 274* Add information of ANY peer device(mac address, channel and key). \n 275* the number of peer devices must not exceed 16, among which the encrypted must not exceed 6. \n 276* CNcomment:添加对端设备的MAC地址，所在信道信息和用于加密通信的密钥。\n 277* 对端设备总数最多16个，其中加密通信的对端个数最多6个。CNend 278* 279* @attention 1. The driver just stores the channels of peer devices.\n 280* It will not switch to a channel automatically which differs with the current channel. \n 281* CNcomment:1. 驱动仅保存对端设备的信道号，通信过程不会自动切到对应信道.CNend \n 282* 2. The memories of <peer_info> are requested and freed by user APP.\n 283* CNcomment:2. <peer_info>内存由用户管理，驱动接口中不会释放.CNend 284* @param peer_info [IN] Type #hi_wifi_any_peer_info *, information of peer device. 285* CNcomment:对端设备的信息.CNend 286* 287* @retval #HISI_OK Excute successfully 288* @retval #Other Error code 289* @par Dependency: 290* @li hi_any_api.h: ANY API 291* @see NULL 292*/ 293int hi_wifi_any_add_peer(const hi_wifi_any_peer_info *peer_info); 294 295/** 296* @ingroup hi_wifi_any 297* @brief Delete specific peer device.CNcomment:删除指定MAC地址的对端设备信息。CNend 298* 299* @par Description: 300* Delete peer device specified by MAC address, the <len> should be constant 6. \n 301* CNcomment:删除指定MAC地址的对端设备信息,MAC地址长度需固定填6字节。CNend 302* 303* @attention The memories of <mac> are requested and freed by user APP. \n 304* CNcomment:<mac>内存由用户申请和管理，执行完成后驱动不会释放.CNend 305* @param mac [IN] Type #const unsigned char *, peer device's MAC address. 306* CNcomment:待删除的对端设备的MAC地址.CNend 307* @param len [IN] Type #unsigned char, length of MAC address which shall be constant 6. 308* CNcomment:对端设备的MAC地址长度，固定填6字节.CNend 309* 310* @retval #HISI_OK Excute successfully 311* @retval #Other Error code 312* @par Dependency: 313* @li hi_any_api.h: ANY API 314* @see NULL 315*/ 316int hi_wifi_any_del_peer(const unsigned char *mac, unsigned char len); 317 318/** 319* @ingroup hi_wifi_any 320* @brief Get ANY peer device's information by index.CNcomment:获取指定索引的对端设备信息。CNend 321* 322* @par Description: 323* Get ANY peer device's information by index.Index starts from 0 and should not exceed 15. \n 324* CNcomment:获取指定索引的对端设备信息。其中传入的index从0开始指定查询第几个对端，最大不能超过15。CNend 325* 326* @attention The memories of <peer> are requested and freed by user APP. \n 327* CNcomment:<peer>内存由用户申请和管理，由驱动填充查询到的信息.CNend 328* @param index [IN] Type #unsigned char, peer device's index, start from 0. 329* CNcomment:待查询的对端设备的索引，从0开始.CNend 330* @param peer [OUT] Type #hi_wifi_any_peer_info *, peer device's information. 331* CNcomment:查询到的对端设备的信息.CNend 332* 333* @retval #HISI_OK Excute successfully 334* @retval #Other Error code 335* @par Dependency: 336* @li hi_any_api.h: ANY API 337* @see NULL 338*/ 339int hi_wifi_any_fetch_peer(unsigned char index, hi_wifi_any_peer_info *peer); 340 341/** 342* @ingroup hi_wifi_any 343* @brief Start ANY scan and register callback to handle scan results. \n 344* CNcomment:发起ANY扫描并注册回调函数处理扫描完成之后的结果。CNend 345* 346* @par Description: 347* Start ANY scan and register callback to handle scan results. \n 348* The limit to the number of peers discoverd is 32 for a single scan. \n 349* CNcomment:发起ANY扫描并注册回调函数处理扫描完成之后的结果,单次扫描最多返回32个对端设备信息。CNend 350* 351* @attention NULL 352* @param p_fn_cb [IN] Type #hi_wifi_any_scan_result_cb, callback function to handle scan results. 353* CNcomment:由用户实现的回调函数, 扫描完成之后驱动调用该回调处理扫描结果.CNend 354* 355* @retval #HISI_OK Excute successfully 356* @retval #Other Error code 357* @par Dependency: 358* @li hi_any_api.h: ANY API 359* @see hi_wifi_any_scan_result_cb 360*/ 361int hi_wifi_any_discover_peer(hi_wifi_any_scan_result_cb p_fn_cb); 362 363#ifdef __cplusplus 364#if __cplusplus 365 } 366#endif 367#endif 368 369#endif /* end of hi_any_api.h */ 370 371