1 /* 2 * Copyright (C) 2020-2022 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 wifiservice 18 * @{ 19 * 20 * @brief Provides functions for the Wi-Fi station and hotspot modes. 21 * 22 * You can use this module to enable and disable the Wi-Fi station or hotspot mode, connect to and disconnect from a 23 * station or hotspot, query the station or hotspot status, and listen for events. \n 24 * 25 * @since 7 26 */ 27 28 /** 29 * @file wifi_device.h 30 * 31 * @brief Provides capabilities to enable and disable the station mode, connect to and disconnect from a station, 32 * query the station status, and listen for events. 33 * 34 * @since 7 35 */ 36 37 #ifndef WIFI_DEVICE_C_H 38 #define WIFI_DEVICE_C_H 39 #include "wifi_event.h" 40 #include "station_info.h" 41 #include "wifi_scan_info.h" 42 #include "wifi_error_code.h" 43 #include "wifi_linked_info.h" 44 #include "wifi_device_config.h" 45 #include "wifi_state.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /** 52 * @brief Enables the station mode. 53 * 54 * @return Returns {@link WIFI_SUCCESS} if the station mode is enabled; returns an error code defined in 55 * {@link WifiErrorCode} otherwise. 56 * @since 7 57 */ 58 WifiErrorCode EnableWifi(void); 59 60 /** 61 * @brief Disables the station mode. 62 * 63 * @return Returns {@link WIFI_SUCCESS} if the station mode is disabled; returns an error code defined in 64 * {@link WifiErrorCode} otherwise. 65 * @since 7 66 */ 67 WifiErrorCode DisableWifi(void); 68 69 /** 70 * @brief Checks whether the station mode is enabled. 71 * 72 * @return Returns {@link WIFI_STA_ACTIVE} if the station mode is enabled; returns {@link WIFI_STA_NOT_ACTIVE} 73 * otherwise. 74 * @since 7 75 */ 76 int IsWifiActive(void); 77 78 /** 79 * @brief Starts a Wi-Fi scan. 80 * 81 * @return Returns {@link WIFI_SUCCESS} if the Wi-Fi scan is started; returns an error code defined in 82 * {@link WifiErrorCode} otherwise. 83 * @since 7 84 */ 85 WifiErrorCode Scan(void); 86 87 /** 88 * @brief Obtains an array of hotspots detected in a Wi-Fi scan. 89 * 90 * The array of hotspots can be obtained only after the Wi-Fi scan is complete. \n 91 * 92 * @param result Indicates the array of hotspots detected in a Wi-Fi scan. The array is requested and released by the 93 * caller. The value must be greater than or equal to {@link WIFI_SCAN_HOTSPOT_LIMIT}. 94 * @param size Indicates the size of the array. 95 * @return Returns {@link WIFI_SUCCESS} if the array of hotspots detected in the Wi-Fi scan is obtained; returns an 96 * error code defined in {@link WifiErrorCode} otherwise. 97 * @since 7 98 */ 99 WifiErrorCode GetScanInfoList(WifiScanInfo *result, unsigned int *size); 100 101 /** 102 * @brief Adds a specified hotspot configuration for connecting to a hotspot. 103 * 104 * This function generates a <b>networkId</b>. \n 105 * 106 * @param config Indicates the hotspot configuration to add. 107 * @param result Indicates the generated <b>networkId</b>. Each <b>networkId</b> matches a hotspot configuration. 108 * @return Returns {@link WIFI_SUCCESS} if the specified hotspot configuration is added; returns an error code defined 109 * in {@link WifiErrorCode} otherwise. 110 * @since 7 111 */ 112 WifiErrorCode AddDeviceConfig(const WifiDeviceConfig *config, int *result); 113 114 /** 115 * @brief Obtains all hotspot configurations. 116 * 117 * Hotspot configurations were added using {@link AddDeviceConfig}. \n 118 * 119 * @param result Indicates the array of all hotspot configurations. The array is requested and released by the caller. 120 * The value must be greater than or equal to {@link WIFI_MAX_CONFIG_SIZE}. 121 * @param size Indicates the size of the array. 122 * @return Returns {@link WIFI_SUCCESS} if all hotspot configurations are obtained; returns an error code defined in 123 * {@link WifiErrorCode} otherwise. 124 * @since 7 125 */ 126 WifiErrorCode GetDeviceConfigs(WifiDeviceConfig *result, unsigned int *size); 127 128 /** 129 * @brief Removes a hotspot configuration matching a specified <b>networkId</b>. 130 * 131 * @param networkId Indicates the <b>networkId</b> matching the hotspot configuration to remove. 132 * @return Returns {@link WIFI_SUCCESS} if the hotspot configuration is removed; returns an error code defined in 133 * {@link WifiErrorCode} otherwise. 134 * @since 7 135 */ 136 WifiErrorCode RemoveDevice(int networkId); 137 138 /** 139 * @brief Disable a hotspot configuration matching a specified <b>networkId</b>. If the config is disabled, it will 140 * not be auto connected. 141 * 142 * @param networkId Indicates the <b>networkId</b> matching the hotspot configuration to disable. 143 * @return Returns {@link WIFI_SUCCESS} if the hotspot configuration is disabled; returns an error code defined in 144 * {@link WifiErrorCode} otherwise. 145 * @since 7 146 */ 147 WifiErrorCode DisableDeviceConfig(int networkId); 148 149 /** 150 * @brief Enable a hotspot configuration matching a specified <b>networkId</b>. If the config is enabled, it will 151 * be connected automatically when wifi is enabled. When the config is added, it is enabled in default. 152 * 153 * @param networkId Indicates the <b>networkId</b> matching the hotspot configuration to enable. 154 * @return Returns {@link WIFI_SUCCESS} if the hotspot configuration is enabled; returns an error code defined in 155 * {@link WifiErrorCode} otherwise. 156 * @since 7 157 */ 158 WifiErrorCode EnableDeviceConfig(int networkId); 159 160 /** 161 * @brief Connects to a hotspot matching a specified <b>networkId</b>. 162 * 163 * Before calling this function, call {@link AddDeviceConfig} to add a hotspot configuration. \n 164 * 165 * @param networkId Indicates the <b>networkId</b> matching the target hotspot. 166 * @return Returns {@link WIFI_SUCCESS} if the hotspot is connected; returns an error code defined in 167 * {@link WifiErrorCode} otherwise. 168 * @since 7 169 */ 170 WifiErrorCode ConnectTo(int networkId); 171 172 /** 173 * @brief Connect to a hotspot by config. 174 * 175 * @param config is device configuration to connect the Wi-Fi network. 176 * @return Returns {@link WIFI_SUCCESS} if the hotspot is connected; returns an error code defined in 177 * {@link WifiErrorCode} otherwise. 178 * @since 7 179 */ 180 WifiErrorCode ConnectToDevice(const WifiDeviceConfig *config); 181 182 /** 183 * @brief Disconnects this Wi-Fi connection. 184 * 185 * @return Returns {@link WIFI_SUCCESS} if this Wi-Fi connection is disconnected; returns an error code defined 186 * in {@link WifiErrorCode} otherwise. 187 * @since 7 188 */ 189 WifiErrorCode Disconnect(void); 190 191 /** 192 * @brief Obtains information about the connected hotspot. 193 * 194 * @param result Indicates the information about the connected hotspot. 195 * @return Returns {@link WIFI_SUCCESS} if the information about the connected hotspot is obtained; returns an error 196 * code defined in {@link WifiErrorCode} otherwise. 197 * @since 7 198 */ 199 WifiErrorCode GetLinkedInfo(WifiLinkedInfo *result); 200 201 /** 202 * @brief Obtains information about the disconnected reason 203 * 204 * @param result Indicates the information about the disconnected reason 205 * @return Returns {@link WIFI_SUCCESS} if get the sta disconnected reason success; returns an error 206 * code defined in {@link WifiErrorCode} otherwise. 207 * @since 10 208 */ 209 WifiErrorCode GetDisconnectedReason(DisconnectedReason *result); 210 211 /** 212 * @brief Obtains the MAC address of this device. 213 * 214 * @param result Indicates the MAC address of this device. It is a char array whose length is 6. 215 * @return Returns {@link WIFI_SUCCESS} if the MAC address of this device is obtained; returns an error code defined 216 * in {@link WifiErrorCode} otherwise. 217 * @since 7 218 */ 219 WifiErrorCode GetDeviceMacAddress(unsigned char *result); 220 221 /** 222 * @brief Starts a Wi-Fi scan based on a specified parameter. 223 * 224 * Only results matching the specified parameter will be returned for the Wi-Fi scan.\n 225 * 226 * @param params Indicates the pointer to the parameter for starting the Wi-Fi scan. 227 * For details, see {@link WifiScanParams}. 228 * @return Returns {@link WIFI_SUCCESS} if the Wi-Fi scan is started successfully; 229 * returns an error code defined in {@link WifiErrorCode} otherwise. 230 * @since 7 231 */ 232 WifiErrorCode AdvanceScan(WifiScanParams *params); 233 234 /* 235 * @brief get the ip address. 236 * 237 * @return Returns {@link WIFI_SUCCESS} if the IP is got; returns an error code defined 238 * in {@link WifiErrorCode} otherwise. 239 * @since 7 240 */ 241 WifiErrorCode GetIpInfo(IpInfo *info); 242 243 /* 244 * @brief get the ipV6 address. 245 * 246 * @return Returns {@link WIFI_SUCCESS} if the IP is got; returns an error code defined 247 * in {@link WifiErrorCode} otherwise. 248 * @since 7 249 */ 250 WifiErrorCode GetIpv6Info(IpV6Info *info); 251 252 /** 253 * @brief Obtains the signal level indicated by a specified received signal strength indicator (RSSI) and frequency 254 * band. 255 * 256 * 257 * Based on the signal level, you can display the signal strength represented by the number of signal bars. \n 258 * 259 * @param rssi Indicates the RSSI. 260 * @param band Indicates the frequency band, either {@link HOTSPOT_BAND_TYPE_5G} or {@link HOTSPOT_BAND_TYPE_2G}. 261 * @return Returns the signal level if it is obtained; returns <b>-1</b> otherwise. 262 * @since 7 263 */ 264 int GetSignalLevel(int rssi, int band); 265 266 /** 267 * @brief set low latency mode 268 * 269 * @param enabled 0: disable low latency, 1: enable low latency 270 * @return Returns {@link WIFI_SUCCESS} if set success; returns an error code defined 271 * in {@link WifiErrorCode} otherwise. 272 * @since 8 273 */ 274 WifiErrorCode SetLowLatencyMode(int enabled); 275 276 /** 277 * @Description set low tx power 278 * 279 * @param wifiLowPowerParam 280 * @return ErrCode - operation result 281 */ 282 WifiErrorCode SetLowTxPower(const WifiLowPowerParam wifiLowPowerParam); 283 284 /** 285 * @Description check wifi-band type is supported 286 * 287 * @param bandType - wifi band type 288 * @param supported - supported / unsupported 289 * @return ErrCode - operation result 290 */ 291 WifiErrorCode IsBandTypeSupported(int bandType, bool *supported); 292 293 /** 294 * @Description get all 5g channellist 295 * 296 * @param result - get result vector of int 297 * @return ErrCode - operation result 298 */ 299 WifiErrorCode Get5GHzChannelList(int *result, int *size); 300 301 /** 302 * @Description start portal certification 303 * 304 * @return ErrCode - operation result 305 */ 306 WifiErrorCode StartPortalCertification(); 307 /** 308 * @brief Registers a callback for a specified Wi-Fi event. 309 * 310 * The registered callback will be invoked when the Wi-Fi event defined in {@link WifiEvent} occurs. \n 311 * 312 * @param event Indicates the event for which the callback is to be registered. 313 * @return Returns {@link WIFI_SUCCESS} if the callback is registered successfully; returns an error code defined 314 * in {@link WifiErrorCode} otherwise. 315 * @since 7 316 */ 317 WifiErrorCode RegisterWifiEvent(WifiEvent *event); 318 319 /** 320 * @brief Unregisters a callback previously registered for a specified Wi-Fi event. 321 * 322 * @param event Indicates the event for which the callback is to be unregistered. 323 * @return Returns {@link WIFI_SUCCESS} if the callback is unregistered successfully; returns an error code defined 324 * in {@link WifiErrorCode} otherwise. 325 * @since 7 326 */ 327 WifiErrorCode UnRegisterWifiEvent(WifiEvent *event); 328 329 /** 330 * @brief Enable semi-Wifi. 331 * 332 * @return Returns {@link WIFI_SUCCESS} if the station mode is semi enabled; returns an error code defined in 333 * {@link WifiErrorCode} otherwise. 334 * @since 7 335 */ 336 WifiErrorCode EnableSemiWifi(void); 337 338 /** 339 * @brief Obtains the wifi detail state 340 * 341 * @return Returns {@link WIFI_SUCCESS} if get detail state successfully; returns an error code defined in 342 * {@link WifiErrorCode} otherwise. 343 * @since 7 344 */ 345 WifiErrorCode GetWifiDetailState(WifiDetailState *state); 346 #ifdef __cplusplus 347 } 348 #endif 349 350 #endif // WIFI_DEVICE_C_H 351 /** @} */ 352