1 /* 2 * Copyright (c) 2020 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 46 #ifdef __cplusplus 47 extern "C" { 48 #endif 49 50 /** 51 * @brief Enables the station mode. 52 * 53 * @return Returns {@link WIFI_SUCCESS} if the station mode is enabled; returns an error code defined in 54 * {@link WifiErrorCode} otherwise. 55 * @since 7 56 */ 57 WifiErrorCode EnableWifi(void); 58 59 /** 60 * @brief Disables the station mode. 61 * 62 * @return Returns {@link WIFI_SUCCESS} if the station mode is disabled; returns an error code defined in 63 * {@link WifiErrorCode} otherwise. 64 * @since 7 65 */ 66 WifiErrorCode DisableWifi(void); 67 68 /** 69 * @brief Checks whether the station mode is enabled. 70 * 71 * @return Returns {@link WIFI_STA_ACTIVE} if the station mode is enabled; returns {@link WIFI_STA_NOT_ACTIVE} 72 * otherwise. 73 * @since 7 74 */ 75 int IsWifiActive(void); 76 77 /** 78 * @brief Starts a Wi-Fi scan. 79 * 80 * @return Returns {@link WIFI_SUCCESS} if the Wi-Fi scan is started; returns an error code defined in 81 * {@link WifiErrorCode} otherwise. 82 * @since 7 83 */ 84 WifiErrorCode Scan(void); 85 86 /** 87 * @brief Obtains an array of hotspots detected in a Wi-Fi scan. 88 * 89 * The array of hotspots can be obtained only after the Wi-Fi scan is complete. \n 90 * 91 * @param result Indicates the array of hotspots detected in a Wi-Fi scan. The array is requested and released by the 92 * caller. The value must be greater than or equal to {@link WIFI_SCAN_HOTSPOT_LIMIT}. 93 * @param size Indicates the size of the array. 94 * @return Returns {@link WIFI_SUCCESS} if the array of hotspots detected in the Wi-Fi scan is obtained; returns an 95 * error code defined in {@link WifiErrorCode} otherwise. 96 * @since 7 97 */ 98 WifiErrorCode GetScanInfoList(WifiScanInfo *result, unsigned int *size); 99 100 /** 101 * @brief Adds a specified hotspot configuration for connecting to a hotspot. 102 * 103 * This function generates a <b>networkId</b>. \n 104 * 105 * @param config Indicates the hotspot configuration to add. 106 * @param result Indicates the generated <b>networkId</b>. Each <b>networkId</b> matches a hotspot configuration. 107 * @return Returns {@link WIFI_SUCCESS} if the specified hotspot configuration is added; returns an error code defined 108 * in {@link WifiErrorCode} otherwise. 109 * @since 7 110 */ 111 WifiErrorCode AddDeviceConfig(const WifiDeviceConfig *config, int *result); 112 113 /** 114 * @brief Obtains all hotspot configurations. 115 * 116 * Hotspot configurations were added using {@link AddDeviceConfig}. \n 117 * 118 * @param result Indicates the array of all hotspot configurations. The array is requested and released by the caller. 119 * The value must be greater than or equal to {@link WIFI_MAX_CONFIG_SIZE}. 120 * @param size Indicates the size of the array. 121 * @return Returns {@link WIFI_SUCCESS} if all hotspot configurations are obtained; returns an error code defined in 122 * {@link WifiErrorCode} otherwise. 123 * @since 7 124 */ 125 WifiErrorCode GetDeviceConfigs(WifiDeviceConfig *result, unsigned int *size); 126 127 /** 128 * @brief Removes a hotspot configuration matching a specified <b>networkId</b>. 129 * 130 * @param networkId Indicates the <b>networkId</b> matching the hotspot configuration to remove. 131 * @return Returns {@link WIFI_SUCCESS} if the hotspot configuration is removed; returns an error code defined in 132 * {@link WifiErrorCode} otherwise. 133 * @since 7 134 */ 135 WifiErrorCode RemoveDevice(int networkId); 136 137 /** 138 * @brief Disable a hotspot configuration matching a specified <b>networkId</b>. If the config is disabled, it will 139 * not be auto connected. 140 * 141 * @param networkId Indicates the <b>networkId</b> matching the hotspot configuration to disable. 142 * @return Returns {@link WIFI_SUCCESS} if the hotspot configuration is disabled; returns an error code defined in 143 * {@link WifiErrorCode} otherwise. 144 * @since 7 145 */ 146 WifiErrorCode DisableDeviceConfig(int networkId); 147 148 /** 149 * @brief Enable a hotspot configuration matching a specified <b>networkId</b>. If the config is enabled, it will 150 * be connected automatically when wifi is enabled. When the config is added, it is enabled in default. 151 * 152 * @param networkId Indicates the <b>networkId</b> matching the hotspot configuration to enable. 153 * @return Returns {@link WIFI_SUCCESS} if the hotspot configuration is enabled; returns an error code defined in 154 * {@link WifiErrorCode} otherwise. 155 * @since 7 156 */ 157 WifiErrorCode EnableDeviceConfig(int networkId); 158 159 /** 160 * @brief Connects to a hotspot matching a specified <b>networkId</b>. 161 * 162 * Before calling this function, call {@link AddDeviceConfig} to add a hotspot configuration. \n 163 * 164 * @param networkId Indicates the <b>networkId</b> matching the target hotspot. 165 * @return Returns {@link WIFI_SUCCESS} if the hotspot is connected; returns an error code defined in 166 * {@link WifiErrorCode} otherwise. 167 * @since 7 168 */ 169 WifiErrorCode ConnectTo(int networkId); 170 171 /** 172 * @brief Connect to a hotspot by config. 173 * 174 * @param config is device configuration to connect the Wi-Fi network. 175 * @return Returns {@link WIFI_SUCCESS} if the hotspot is connected; returns an error code defined in 176 * {@link WifiErrorCode} otherwise. 177 * @since 7 178 */ 179 WifiErrorCode ConnectToDevice(const WifiDeviceConfig *config); 180 181 /** 182 * @brief Disconnects this Wi-Fi connection. 183 * 184 * @return Returns {@link WIFI_SUCCESS} if this Wi-Fi connection is disconnected; returns an error code defined 185 * in {@link WifiErrorCode} otherwise. 186 * @since 7 187 */ 188 WifiErrorCode Disconnect(void); 189 190 /** 191 * @brief Obtains information about the connected hotspot. 192 * 193 * @param result Indicates the information about the connected hotspot. 194 * @return Returns {@link WIFI_SUCCESS} if the information about the connected hotspot is obtained; returns an error 195 * code defined in {@link WifiErrorCode} otherwise. 196 * @since 7 197 */ 198 WifiErrorCode GetLinkedInfo(WifiLinkedInfo *result); 199 200 /** 201 * @brief Obtains the MAC address of this device. 202 * 203 * @param result Indicates the MAC address of this device. It is a char array whose length is 6. 204 * @return Returns {@link WIFI_SUCCESS} if the MAC address of this device is obtained; returns an error code defined 205 * in {@link WifiErrorCode} otherwise. 206 * @since 7 207 */ 208 WifiErrorCode GetDeviceMacAddress(unsigned char *result); 209 210 /** 211 * @brief Starts a Wi-Fi scan based on a specified parameter. 212 * 213 * Only results matching the specified parameter will be returned for the Wi-Fi scan.\n 214 * 215 * @param params Indicates the pointer to the parameter for starting the Wi-Fi scan. 216 * For details, see {@link WifiScanParams}. 217 * @return Returns {@link WIFI_SUCCESS} if the Wi-Fi scan is started successfully; 218 * returns an error code defined in {@link WifiErrorCode} otherwise. 219 * @since 7 220 */ 221 WifiErrorCode AdvanceScan(WifiScanParams *params); 222 223 /* 224 * @brief get the ip address. 225 * 226 * @return Returns {@link WIFI_SUCCESS} if the IP is got; returns an error code defined 227 * in {@link WifiErrorCode} otherwise. 228 * @since 7 229 */ 230 WifiErrorCode GetIpInfo(IpInfo *info); 231 232 /** 233 * @brief Obtains the signal level indicated by a specified received signal strength indicator (RSSI) and frequency 234 * band. 235 * 236 * 237 * Based on the signal level, you can display the signal strength represented by the number of signal bars. \n 238 * 239 * @param rssi Indicates the RSSI. 240 * @param band Indicates the frequency band, either {@link HOTSPOT_BAND_TYPE_5G} or {@link HOTSPOT_BAND_TYPE_2G}. 241 * @return Returns the signal level if it is obtained; returns <b>-1</b> otherwise. 242 * @since 7 243 */ 244 int GetSignalLevel(int rssi, int band); 245 246 /** 247 * @brief Registers a callback for a specified Wi-Fi event. 248 * 249 * The registered callback will be invoked when the Wi-Fi event defined in {@link WifiEvent} occurs. \n 250 * 251 * @param event Indicates the event for which the callback is to be registered. 252 * @return Returns {@link WIFI_SUCCESS} if the callback is registered successfully; returns an error code defined 253 * in {@link WifiErrorCode} otherwise. 254 * @since 7 255 */ 256 WifiErrorCode RegisterWifiEvent(WifiEvent *event); 257 258 /** 259 * @brief Unregisters a callback previously registered for a specified Wi-Fi event. 260 * 261 * @param event Indicates the event for which the callback is to be unregistered. 262 * @return Returns {@link WIFI_SUCCESS} if the callback is unregistered successfully; returns an error code defined 263 * in {@link WifiErrorCode} otherwise. 264 * @since 7 265 */ 266 WifiErrorCode UnRegisterWifiEvent(const WifiEvent *event); 267 268 #ifdef __cplusplus 269 } 270 #endif 271 272 #endif // WIFI_DEVICE_C_H 273 /** @} */ 274