1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.tradefed.device; 18 19 import java.util.List; 20 import java.util.Map; 21 22 23 /** 24 * Helper interface for manipulating wifi services on device. 25 */ 26 interface IWifiHelper { 27 28 /** 29 * The Wifi supplicant state. Should match states defined in android.net.wifi.SupplicantState. 30 */ 31 public enum WifiState { 32 COMPLETED, SCANNING, DISCONNECTED, OTHER; 33 } 34 35 /** 36 * Enables wifi state on device. 37 * 38 * @return <code>true</code> if wifi was enabled successfully 39 * @throws DeviceNotAvailableException 40 */ enableWifi()41 boolean enableWifi() throws DeviceNotAvailableException; 42 43 /** 44 * Disables wifi state on device. 45 * 46 * @return <code>true</code> if wifi was disabled successfully 47 * @throws DeviceNotAvailableException 48 */ disableWifi()49 boolean disableWifi() throws DeviceNotAvailableException; 50 51 /** 52 * Waits until one of the expected wifi states occurs. 53 * 54 * @param expectedStates one or more wifi states to expect 55 * @return <code>true</code> if the one of the expected states occurred. <code>false</code> if 56 * none of the states occurred before timeout is reached 57 * @throws DeviceNotAvailableException 58 */ waitForWifiState(WifiState... expectedStates)59 boolean waitForWifiState(WifiState... expectedStates) throws DeviceNotAvailableException; 60 61 /** 62 * Adds the open security network identified by ssid. 63 * <p/> 64 * To connect to any wifi network, a network profile must be created in wpa_supplicant 65 * configuration first. This will call wpa_cli to add the open security network identified by 66 * ssid. 67 * 68 * @param ssid the ssid of network to add. 69 * @return <code>true</code> if network was added successfully, <code>false</code> otherwise. 70 * @throws DeviceNotAvailableException 71 */ addOpenNetwork(String ssid)72 boolean addOpenNetwork(String ssid) throws DeviceNotAvailableException; 73 74 /** 75 * Adds the open security network identified by ssid. 76 * <p/> 77 * To connect to any wifi network, a network profile must be created in wpa_supplicant 78 * configuration first. This will call wpa_cli to add the open security network identified by 79 * ssid. 80 * 81 * @param ssid the ssid of network to add. 82 * @param scanSsid whether to scan for hidden SSID for this network. 83 * @return <code>true</code> if network was added successfully, <code>false</code> otherwise. 84 * @throws DeviceNotAvailableException 85 */ addOpenNetwork(String ssid, boolean scanSsid)86 boolean addOpenNetwork(String ssid, boolean scanSsid) throws DeviceNotAvailableException; 87 88 /** 89 * Adds the WPA-PSK security network identified by ssid. 90 * 91 * @param ssid the ssid of network to add. 92 * @param psk the WPA-PSK passphrase to use 93 * @return <code>true</code> if network was added successfully, <code>false</code> otherwise. 94 * @throws DeviceNotAvailableException 95 */ addWpaPskNetwork(String ssid, String psk)96 boolean addWpaPskNetwork(String ssid, String psk) throws DeviceNotAvailableException; 97 98 /** 99 * Adds the WPA-PSK security network identified by ssid. 100 * 101 * @param ssid the ssid of network to add. 102 * @param psk the WPA-PSK passphrase to use 103 * @param scanSsid whether to scan for hidden SSID for this network. 104 * @return <code>true</code> if network was added successfully, <code>false</code> otherwise. 105 * @throws DeviceNotAvailableException 106 */ addWpaPskNetwork(String ssid, String psk, boolean scanSsid)107 boolean addWpaPskNetwork(String ssid, String psk, boolean scanSsid) throws DeviceNotAvailableException; 108 109 /** 110 * Wait until an ip address is assigned to wifi adapter. 111 * 112 * @param timeout how long to wait 113 * @return <code>true</code> if an ip address is assigned before timeout, <code>false</code> 114 * otherwise 115 * @throws DeviceNotAvailableException 116 */ waitForIp(long timeout)117 boolean waitForIp(long timeout) throws DeviceNotAvailableException; 118 119 /** 120 * Gets the IP address associated with the wifi interface. Returns <code>null</code> if there 121 * was a failure retrieving ip address. 122 */ getIpAddress()123 String getIpAddress() throws DeviceNotAvailableException; 124 125 /** 126 * Gets the service set identifier of the currently connected network. 127 * 128 * @see 129 * <a href="http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()"> 130 * http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()</a> 131 * @throws DeviceNotAvailableException 132 */ getSSID()133 String getSSID() throws DeviceNotAvailableException; 134 135 /** 136 * Gets the basic service set identifier (BSSID) of the currently access point. 137 * 138 * @see 139 * <a href="http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()"> 140 * http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()</a> 141 * @throws DeviceNotAvailableException 142 */ getBSSID()143 String getBSSID() throws DeviceNotAvailableException; 144 145 /** 146 * Removes all known networks. 147 * 148 * @throws DeviceNotAvailableException 149 */ removeAllNetworks()150 boolean removeAllNetworks() throws DeviceNotAvailableException; 151 152 /** 153 * Check if wifi is currently enabled. 154 */ isWifiEnabled()155 boolean isWifiEnabled() throws DeviceNotAvailableException; 156 157 /** 158 * Wait for {@link #isWifiEnabled()} to be true with a default timeout. 159 * 160 * @return <code>true</code> if wifi was enabled before timeout, <code>false</code> otherwise. 161 * @throws DeviceNotAvailableException 162 */ waitForWifiEnabled()163 boolean waitForWifiEnabled() throws DeviceNotAvailableException; 164 165 /** 166 * Wait for {@link #isWifiEnabled()} to be true. 167 * 168 * @param timeout time in ms to wait 169 * @return <code>true</code> if wifi was enabled before timeout, <code>false</code> otherwise. 170 * @throws DeviceNotAvailableException 171 */ waitForWifiEnabled(long timeout)172 boolean waitForWifiEnabled(long timeout) throws DeviceNotAvailableException; 173 174 /** 175 * Wait for {@link #isWifiEnabled()} to be false with a default timeout. 176 * 177 * @return <code>true</code> if wifi was disabled before timeout, <code>false</code> otherwise. 178 * @throws DeviceNotAvailableException 179 */ waitForWifiDisabled()180 boolean waitForWifiDisabled() throws DeviceNotAvailableException; 181 182 /** 183 * Wait for {@link #isWifiEnabled()} to be false. 184 * 185 * @param timeout time in ms to wait 186 * @return <code>true</code> if wifi was disabled before timeout, <code>false</code> otherwise. 187 * @throws DeviceNotAvailableException 188 */ waitForWifiDisabled(long timeout)189 boolean waitForWifiDisabled(long timeout) throws DeviceNotAvailableException; 190 191 /** 192 * @return <code>true</code> if device has a valid IP address 193 * @throws DeviceNotAvailableException 194 */ hasValidIp()195 boolean hasValidIp() throws DeviceNotAvailableException; 196 197 /** 198 * Gets the current wifi connection information. 199 * <p/> 200 * This includes SSID, BSSID, IP address, link speed, and RSSI. 201 * @return a map containing wifi connection information. 202 * @throws DeviceNotAvailableException 203 */ getWifiInfo()204 Map<String, String> getWifiInfo() throws DeviceNotAvailableException; 205 206 /** 207 * Checks connectivity by sending HTTP request to the given url. 208 * 209 * @param urlToCheck a destination url for a HTTP request check 210 * @return <code>true</code> if the device pass connectivity check. 211 * @throws DeviceNotAvailableException 212 */ checkConnectivity(String urlToCheck)213 boolean checkConnectivity(String urlToCheck) throws DeviceNotAvailableException; 214 215 /** 216 * Connects to a wifi network and check connectivity. 217 * 218 * @param ssid the ssid of network to connect 219 * @param psk the WPA-PSK passphrase to use. This can be null. 220 * @param urlToCheck a destination url for a HTTP request check 221 * @return <code>true</code> if the device pass connectivity check. 222 * @throws DeviceNotAvailableException 223 */ connectToNetwork(String ssid, String psk, String urlToCheck)224 boolean connectToNetwork(String ssid, String psk, String urlToCheck) 225 throws DeviceNotAvailableException; 226 227 /** 228 * Connects to a wifi network and check connectivity. 229 * 230 * @param ssid the ssid of network to connect 231 * @param psk the WPA-PSK passphrase to use. This can be null. 232 * @param urlToCheck a destination url for a HTTP request check 233 * @param scanSsid whether to scan for hidden SSID for this network 234 * @return <code>true</code> if the device pass connectivity check. 235 * @throws DeviceNotAvailableException 236 */ connectToNetwork(String ssid, String psk, String urlToCheck, boolean scanSsid)237 boolean connectToNetwork(String ssid, String psk, String urlToCheck, boolean scanSsid) 238 throws DeviceNotAvailableException; 239 240 /** 241 * Disconnect from the current wifi network and disable wifi. 242 * 243 * @return <code>true</code> if the operation succeeded. 244 * @throws DeviceNotAvailableException 245 */ disconnectFromNetwork()246 boolean disconnectFromNetwork() throws DeviceNotAvailableException; 247 248 /** 249 * Starts network connectivity monitoring. 250 * 251 * @param interval interval between connectivity checks. 252 * @param urlToCheck a URL to check connectivity with. 253 * @return <code>true</code> if the operation succeeded. 254 * @throws DeviceNotAvailableException 255 */ startMonitor(long interval, String urlToCheck)256 boolean startMonitor(long interval, String urlToCheck) throws DeviceNotAvailableException; 257 258 /** 259 * Stops network connectivity monitoring. 260 * <p/> 261 * This also returns the latency history since the last 262 * {@link IWifiHelper#startMonitor(long, String)} call. 263 * 264 * @return the latency history. 265 * @throws DeviceNotAvailableException 266 */ stopMonitor()267 List<Long> stopMonitor() throws DeviceNotAvailableException; 268 269 /** 270 * Clean up the resources and the wifi helper packaged install. This should only be called when 271 * Wifi is not needed anymore for the invocation since the device would lose the wifi connection 272 * when the helper is uninstalled. 273 * 274 * @throws DeviceNotAvailableException 275 */ cleanUp()276 void cleanUp() throws DeviceNotAvailableException; 277 } 278