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 28 extern "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 */ 62 typedef 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 */ 79 typedef 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 */ 114 typedef 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 */ 140 typedef 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 */ 165 typedef 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 */ 172 typedef 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 */ 197 int 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 */ 215 int 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 */ 236 void 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 */ 266 int 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 */ 293 int 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 */ 316 int 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 */ 339 int 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 */ 361 int 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