1 /* 2 * Copyright (c) 2021-2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup WLAN 18 * @{ 19 * 20 * @brief Provides cross-OS migration, component adaptation, and modular assembly and compilation. 21 * 22 * Based on the unified APIs provided by the WLAN module, developers of the Hardware Driver Interface 23 * (HDI) are capable of creating, disabling, scanning for, and connecting to WLAN hotspots, managing WLAN chips, 24 * network devices, and power, and applying for, releasing, and moving network data buffers. 25 * 26 * @since 1.0 27 * @version 1.0 28 */ 29 30 /** 31 * @file wifi_hal.h 32 * 33 * @brief Declares APIs for basic WLAN features. 34 * 35 * @since 1.0 36 * @version 1.0 37 */ 38 39 #ifndef WIFI_HAL_H 40 #define WIFI_HAL_H 41 42 #include "wifi_hal_ap_feature.h" 43 #include "wifi_hal_sta_feature.h" 44 45 #ifdef __cplusplus 46 #if __cplusplus 47 extern "C" { 48 #endif 49 #endif 50 51 /** 52 * @brief Defines a callback to listen for <b>IWiFi</b> asynchronous events. 53 * 54 * @param event Indicates the event type passed to the callback. 55 * @param data Indicates the pointer to the data passed to the callback. 56 * @param ifName The interface name. 57 * 58 * @return Returns <b>0</b> if the <b>IWiFi</b> callback is defined; returns a negative value otherwise. 59 * 60 * @since 1.0 61 * @version 1.0 62 */ 63 typedef int32_t (*CallbackFunc)(uint32_t event, void *data, const char *ifName); 64 65 /** 66 * @brief Defines a hid2d callback to listen for <b>IWiFi</b> asynchronous events. 67 * 68 * @param recvMsg Indicates message received. 69 * @param recvMsgLen Indicates the length of message. 70 * 71 * @return Returns <b>0</b> if the <b>IWiFi</b> hid2d callback is defined; returns a negative value otherwise. 72 * 73 * @since 1.0 74 * @version 1.0 75 */ 76 typedef int32_t (*Hid2dCallbackFunc)(const uint8_t *recvMsg, uint32_t recvMsgLen); 77 78 /** 79 * @brief Defines the basic WLAN features provided by the hardware abstraction layer (HAL). 80 * 81 * The basic features include creating and stopping a channel between the HAL and the WLAN driver, 82 * and creating, obtaining, and destroying WLAN features. 83 * 84 * @since 1.0 85 * @version 1.0 86 */ 87 struct IWiFi { 88 /** 89 * @brief Creates a channel between the HAL and the WLAN driver and obtains the driver NIC information. 90 * 91 * @param iwifi Indicates the pointer to the {@link IWiFi} object. 92 * 93 * @return Returns <b>0</b> if the channel is created and the driver NIC information is obtained; 94 * returns a negative value otherwise. 95 * 96 * @since 1.0 97 * @version 1.0 98 */ 99 int32_t (*start)(struct IWiFi *iwifi); 100 101 /** 102 * @brief Stops the channel between the HAL and the WLAN driver. 103 * 104 * @param iwifi Indicates the pointer to the {@link IWiFi} object. 105 * 106 * @return Returns <b>0</b> if the channel is stopped; returns a negative value otherwise. 107 * 108 * @since 1.0 109 * @version 1.0 110 */ 111 int32_t (*stop)(struct IWiFi *iwifi); 112 113 /** 114 * @brief Obtains the WLAN features available for the device no matter whether it works as an AP, 115 * STA, or P2P server/client. 116 * 117 * @param supType Indicates the pointer to the WLAN features available for the device. 118 * @param size Indicates the length of the <b>supType</b> array. 119 * 120 * @return Returns <b>0</b> if the WLAN features are obtained; returns a negative value otherwise. 121 * 122 * @since 1.0 123 * @version 1.0 124 */ 125 int32_t (*getSupportFeature)(uint8_t *supType, uint32_t size); 126 127 /** 128 * @brief Obtains the WLAN features available for the device that plays different roles simultaneously 129 * (any combination of AP, STA, and P2P server/client). 130 * 131 * @param combo Indicates the pointer to WLAN features available for the device. 132 * @param size Indicates the length of the <b>combo</b> array. 133 * 134 * @return Returns <b>0</b> if the WLAN features are obtained; returns a negative value otherwise. 135 * 136 * @since 1.0 137 * @version 1.0 138 */ 139 int32_t (*getSupportCombo)(uint64_t *combo, uint32_t size); 140 141 /** 142 * @brief Creates an {@link IWiFiBaseFeature} object of a specified type. 143 * 144 * @param type Indicates the feature type. 145 * @param ifeature Indicates the double pointer to the {@link IWiFiBaseFeature} object. 146 * 147 * @return Returns <b>0</b> if the {@link IWiFiBaseFeature} object is created; returns a negative value otherwise. 148 * 149 * @since 1.0 150 * @version 1.0 151 */ 152 int32_t (*createFeature)(int32_t type, struct IWiFiBaseFeature **ifeature); 153 154 /** 155 * @brief Obtains an {@link IWiFiBaseFeature} object based on a specified network interface name. 156 * 157 * @param ifName Indicates the pointer to the network interface name. 158 * @param ifeature Indicates the double pointer to the {@link IWiFiBaseFeature} object. 159 * 160 * @return Returns <b>0</b> if the {@link IWiFiBaseFeature} object is obtained; returns a negative value otherwise. 161 * 162 * @since 1.0 163 * @version 1.0 164 */ 165 int32_t (*getFeatureByIfName)(const char *ifName, struct IWiFiBaseFeature **ifeature); 166 167 /** 168 * @brief Registers a callback to listen for <b>IWiFi</b> asynchronous events. 169 * 170 * @param cbFunc Indicates the callback to register. 171 * @param ifName Indicates the pointer to the network interface name. 172 * 173 * @return Returns <b>0</b> if the callback is registered; returns a negative value otherwise. 174 * 175 * @since 1.0 176 * @version 1.0 177 */ 178 int32_t (*registerEventCallback)(CallbackFunc cbFunc, const char *ifName); 179 180 /** 181 * @brief Deregisters an <b>IWiFi</b> callback. 182 183 * @param cbFunc Indicates the callback to register. 184 * @param ifName Indicates the pointer to the network interface name. 185 * 186 * @return Returns <b>0</b> if the <b>IWiFi</b> callback is deregistered; returns a negative value otherwise. 187 * 188 * @since 1.0 189 * @version 1.0 190 */ 191 int32_t (*unregisterEventCallback)(CallbackFunc cbFunc, const char *ifName); 192 193 /** 194 * @brief Destroys a specified {@link IWiFiBaseFeature} object. 195 * 196 * @param ifeature Indicates the pointer to the {@link IWiFiBaseFeature} object to destroy. 197 * 198 * @return Returns <b>0</b> if the {@link IWiFiBaseFeature} object is destroyed; returns a negative value otherwise. 199 * 200 * @since 1.0 201 * @version 1.0 202 */ 203 int32_t (*destroyFeature)(struct IWiFiBaseFeature *ifeature); 204 205 /** 206 * @brief Resets the WLAN driver with a specified chip ID. 207 * 208 * @param chipId Indicates the chip ID. 209 * 210 * @return Returns <b>0</b> if the WLAN driver is reset; returns a negative value otherwise. 211 * 212 * @since 1.0 213 * @version 1.0 214 */ 215 int32_t (*resetDriver)(const uint8_t chipId, const char *ifName); 216 217 /** 218 * @brief get net device infos. 219 * 220 * @param netDeviceInfoResult get net device infos. 221 * 222 * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise. 223 * 224 * @since 1.0 225 * @version 1.0 226 */ 227 int32_t (*getNetDevInfo)(struct NetDeviceInfoResult *netDeviceInfoResult); 228 229 /** 230 * @brief Obtains the power mode which is being used. 231 * 232 * @param ifName Indicates the pointer to the network interface name. 233 * @param mode Indicates the pointer to the power mode. 234 * 235 * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise. 236 * 237 * @since 1.0 238 * @version 1.0 239 */ 240 int32_t (*getPowerMode)(const char *ifName, uint8_t *mode); 241 242 /** 243 * @brief Set the power mode. 244 * 245 * @param ifName Indicates the pointer to the network interface name. 246 * @param mode The value set to power mode. 247 * 248 * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise. 249 * 250 * @since 1.0 251 * @version 1.0 252 */ 253 int32_t (*setPowerMode)(const char *ifName, uint8_t mode); 254 255 /** 256 * @brief Start channel measurement(asynchronous interface, need call getChannelMeasResult to 257 * get measurement results). 258 * 259 * @param ifName Indicates the pointer to the network interface name. 260 * @param measParam Parameters of the measurement channel. 261 * 262 * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise. 263 * 264 * @since 3.2 265 * @version 1.0 266 */ 267 int32_t (*startChannelMeas)(const char *ifName, const struct MeasParam *measParam); 268 269 /** 270 * @brief Obtaining channel measurement results. 271 * 272 * @param ifName Indicates the pointer to the network interface name. 273 * @param measResult Channel measurement result data. 274 * 275 * @return Returns <b>0</b> if get infos successful; returns a negative value otherwise. 276 * 277 * @since 3.2 278 * @version 1.0 279 */ 280 int32_t (*getChannelMeasResult)(const char *ifName, struct MeasResult *measResult); 281 282 /** 283 * @brief Config projection screen parameters. 284 * 285 * @param ifName Indicates the pointer to the network interface name. 286 * @param param Indicates the parameters used to config projection screen. 287 * 288 * @return Returns <b>0</b> if Config projection screen parameters successful; returns a negative value otherwise. 289 * 290 * @since 3.2 291 * @version 1.0 292 */ 293 int32_t (*setProjectionScreenParam)(const char *ifName, const ProjectionScreenParam *param); 294 295 /** 296 * @brief Send ioctl command to driver. 297 * 298 * @param ifName Indicates the pointer to the network interface name. 299 * @param cmdId Indicates the command identity document. 300 * @param paramBuf Indicates the paramter send to driver. 301 * @param paramBufLen Indicates the length of parameter. 302 * 303 * @return Returns <b>0</b> if Send ioctl command successful; returns a negative value otherwise. 304 * 305 * @since 3.2 306 * @version 1.0 307 */ 308 int32_t (*sendCmdIoctl)(const char *ifName, int32_t cmdId, const int8_t *paramBuf, uint32_t paramBufLen); 309 310 /** 311 * @brief Registers a hid2d callback to listen for <b>IWiFi</b> asynchronous events. 312 * 313 * @param func Indicates the callback function to register. 314 * @param ifName Indicates the pointer to the network interface name. 315 * 316 * @return Returns <b>0</b> if the hid2d callback is registered; returns a negative value otherwise. 317 * 318 * @since 3.2 319 * @version 1.0 320 */ 321 int32_t (*registerHid2dCallback)(Hid2dCallback func, const char *ifName); 322 323 /** 324 * @brief Unegisters a hid2d callback to listen for <b>IWiFi</b> asynchronous events. 325 * 326 * @param func Indicates the callback function to unregister. 327 * @param ifName Indicates the pointer to the network interface name. 328 * 329 * @return Returns <b>0</b> if the hid2d callback is unregistered; returns a negative value otherwise. 330 * 331 * @since 3.2 332 * @version 1.0 333 */ 334 int32_t (*unregisterHid2dCallback)(Hid2dCallback func, const char *ifName); 335 336 /** 337 * @brief Get station information. 338 * 339 * @param ifName Indicates the pointer to the network interface name. 340 * @param info Indicates the Station information. 341 * @param mac Indicates the mac address of station. 342 * @param param Indicates the length of mac address. 343 * 344 * @return Returns <b>0</b> if get station information successful; returns a negative value otherwise. 345 * 346 * @since 3.2 347 * @version 1.0 348 */ 349 int32_t (*getStationInfo)(const char *ifName, StationInfo *info, const uint8_t *mac, uint32_t macLen); 350 }; 351 352 /** 353 * @brief Creates an {@link IWiFi} structure. 354 * 355 * @param wifiInstance Indicates the double pointer to the {@link IWiFi} structure. 356 * 357 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 358 * 359 * @since 1.0 360 * @version 1.0 361 */ 362 int32_t WifiConstruct(struct IWiFi **wifiInstance); 363 364 /** 365 * @brief Destroys a specified {@link IWiFi} structure. 366 * 367 * @param wifiInstance Indicates the double pointer to the {@link IWiFi} structure. 368 * 369 * @return Returns <b>0</b> if the operation is successful; returns a negative value otherwise. 370 * 371 * @since 1.0 372 * @version 1.0 373 */ 374 int32_t WifiDestruct(struct IWiFi **wifiInstance); 375 376 #ifdef __cplusplus 377 #if __cplusplus 378 } 379 #endif 380 #endif 381 382 #endif 383 /** @} */ 384