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     public enum WifiConnectionResult {
36         SUCCESS,
37         FAILED_TO_CONNECT,
38         FAILED_TO_ENABLE;
39     }
40 
41     /**
42      * Enables wifi state on device.
43      *
44      * @return <code>true</code> if wifi was enabled successfully
45      * @throws DeviceNotAvailableException
46      */
enableWifi()47     boolean enableWifi() throws DeviceNotAvailableException;
48 
49     /**
50      * Disables wifi state on device.
51      *
52      * @return <code>true</code> if wifi was disabled successfully
53      * @throws DeviceNotAvailableException
54      */
disableWifi()55     boolean disableWifi() throws DeviceNotAvailableException;
56 
57     /**
58      * Waits until one of the expected wifi states occurs.
59      *
60      * @param expectedStates one or more wifi states to expect
61      * @return <code>true</code> if the one of the expected states occurred. <code>false</code> if
62      *         none of the states occurred before timeout is reached
63      * @throws DeviceNotAvailableException
64      */
waitForWifiState(WifiState... expectedStates)65     boolean waitForWifiState(WifiState... expectedStates) throws DeviceNotAvailableException;
66 
67     /**
68      * Adds the open security network identified by ssid.
69      * <p/>
70      * To connect to any wifi network, a network profile must be created in wpa_supplicant
71      * configuration first. This will call wpa_cli to add the open security network identified by
72      * ssid.
73      *
74      * @param ssid the ssid of network to add.
75      * @return <code>true</code> if network was added successfully, <code>false</code> otherwise.
76      * @throws DeviceNotAvailableException
77      */
addOpenNetwork(String ssid)78     boolean addOpenNetwork(String ssid) throws DeviceNotAvailableException;
79 
80     /**
81      * Adds the open security network identified by ssid.
82      * <p/>
83      * To connect to any wifi network, a network profile must be created in wpa_supplicant
84      * configuration first. This will call wpa_cli to add the open security network identified by
85      * ssid.
86      *
87      * @param ssid the ssid of network to add.
88      * @param scanSsid whether to scan for hidden SSID for this network.
89      * @return <code>true</code> if network was added successfully, <code>false</code> otherwise.
90      * @throws DeviceNotAvailableException
91      */
addOpenNetwork(String ssid, boolean scanSsid)92     boolean addOpenNetwork(String ssid, boolean scanSsid) throws DeviceNotAvailableException;
93 
94     /**
95      * Adds the WPA-PSK security network identified by ssid.
96      *
97      * @param ssid the ssid of network to add.
98      * @param psk the WPA-PSK passphrase to use
99      * @return <code>true</code> if network was added successfully, <code>false</code> otherwise.
100      * @throws DeviceNotAvailableException
101      */
addWpaPskNetwork(String ssid, String psk)102     boolean addWpaPskNetwork(String ssid, String psk) throws DeviceNotAvailableException;
103 
104     /**
105      * Adds the WPA-PSK security network identified by ssid.
106      *
107      * @param ssid the ssid of network to add.
108      * @param psk the WPA-PSK passphrase to use
109      * @param scanSsid whether to scan for hidden SSID for this network.
110      * @return <code>true</code> if network was added successfully, <code>false</code> otherwise.
111      * @throws DeviceNotAvailableException
112      */
addWpaPskNetwork(String ssid, String psk, boolean scanSsid)113     boolean addWpaPskNetwork(String ssid, String psk, boolean scanSsid) throws DeviceNotAvailableException;
114 
115     /**
116      * Wait until an ip address is assigned to wifi adapter.
117      *
118      * @param timeout how long to wait
119      * @return <code>true</code> if an ip address is assigned before timeout, <code>false</code>
120      *         otherwise
121      * @throws DeviceNotAvailableException
122      */
waitForIp(long timeout)123     boolean waitForIp(long timeout) throws DeviceNotAvailableException;
124 
125     /**
126      * Gets the IP address associated with the wifi interface. Returns <code>null</code> if there
127      * was a failure retrieving ip address.
128      */
getIpAddress()129     String getIpAddress() throws DeviceNotAvailableException;
130 
131     /**
132      * Gets the service set identifier of the currently connected network.
133      *
134      * @see
135      * <a href="http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()">
136      * http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()</a>
137      * @throws DeviceNotAvailableException
138      */
getSSID()139     String getSSID() throws DeviceNotAvailableException;
140 
141     /**
142      * Gets the basic service set identifier (BSSID) of the currently access point.
143      *
144      * @see
145      * <a href="http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()">
146      * http://developer.android.com/reference/android/net/wifi/WifiInfo.html#getSSID()</a>
147      * @throws DeviceNotAvailableException
148      */
getBSSID()149     String getBSSID() throws DeviceNotAvailableException;
150 
151     /**
152      * Removes all known networks.
153      *
154      * @throws DeviceNotAvailableException
155      */
removeAllNetworks()156     boolean removeAllNetworks() throws DeviceNotAvailableException;
157 
158     /**
159      * Check if wifi is currently enabled.
160      */
isWifiEnabled()161     boolean isWifiEnabled() throws DeviceNotAvailableException;
162 
163     /**
164      * Wait for {@link #isWifiEnabled()} to be true with a default timeout.
165      *
166      * @return <code>true</code> if wifi was enabled before timeout, <code>false</code> otherwise.
167      * @throws DeviceNotAvailableException
168      */
waitForWifiEnabled()169     boolean waitForWifiEnabled() throws DeviceNotAvailableException;
170 
171     /**
172      * Wait for {@link #isWifiEnabled()} to be true.
173      *
174      * @param timeout time in ms to wait
175      * @return <code>true</code> if wifi was enabled before timeout, <code>false</code> otherwise.
176      * @throws DeviceNotAvailableException
177      */
waitForWifiEnabled(long timeout)178     boolean waitForWifiEnabled(long timeout) throws DeviceNotAvailableException;
179 
180     /**
181      * Wait for {@link #isWifiEnabled()} to be false with a default timeout.
182      *
183      * @return <code>true</code> if wifi was disabled before timeout, <code>false</code> otherwise.
184      * @throws DeviceNotAvailableException
185      */
waitForWifiDisabled()186     boolean waitForWifiDisabled() throws DeviceNotAvailableException;
187 
188     /**
189      * Wait for {@link #isWifiEnabled()} to be false.
190      *
191      * @param timeout time in ms to wait
192      * @return <code>true</code> if wifi was disabled before timeout, <code>false</code> otherwise.
193      * @throws DeviceNotAvailableException
194      */
waitForWifiDisabled(long timeout)195     boolean waitForWifiDisabled(long timeout) throws DeviceNotAvailableException;
196 
197     /**
198      * @return <code>true</code> if device has a valid IP address
199      * @throws DeviceNotAvailableException
200      */
hasValidIp()201     boolean hasValidIp() throws DeviceNotAvailableException;
202 
203     /**
204      * Gets the current wifi connection information.
205      * <p/>
206      * This includes SSID, BSSID, IP address, link speed, and RSSI.
207      * @return a map containing wifi connection information.
208      * @throws DeviceNotAvailableException
209      */
getWifiInfo()210     Map<String, String> getWifiInfo() throws DeviceNotAvailableException;
211 
212     /**
213      * Checks connectivity by sending HTTP request to the given url.
214      *
215      * @param urlToCheck a destination url for a HTTP request check
216      * @return <code>true</code> if the device pass connectivity check.
217      * @throws DeviceNotAvailableException
218      */
checkConnectivity(String urlToCheck)219     boolean checkConnectivity(String urlToCheck) throws DeviceNotAvailableException;
220 
221     /**
222      * Connects to a wifi network and check connectivity.
223      *
224      * @param ssid the ssid of network to connect
225      * @param psk the WPA-PSK passphrase to use. This can be null.
226      * @param urlToCheck a destination url for a HTTP request check
227      * @return <code>true</code> if the device pass connectivity check.
228      * @throws DeviceNotAvailableException
229      */
connectToNetwork(String ssid, String psk, String urlToCheck)230     boolean connectToNetwork(String ssid, String psk, String urlToCheck)
231             throws DeviceNotAvailableException;
232 
233     /**
234      * Connects to a wifi network and check connectivity.
235      *
236      * @param ssid the ssid of network to connect
237      * @param psk the WPA-PSK passphrase to use. This can be null.
238      * @param urlToCheck a destination url for a HTTP request check
239      * @param scanSsid whether to scan for hidden SSID for this network
240      * @return WifiConnectionResult representing the wifi connection result
241      * @throws DeviceNotAvailableException
242      */
connectToNetwork( String ssid, String psk, String urlToCheck, boolean scanSsid)243     WifiConnectionResult connectToNetwork(
244             String ssid, String psk, String urlToCheck, boolean scanSsid)
245             throws DeviceNotAvailableException;
246 
247     /**
248      * Connects to a wifi network and check connectivity.
249      *
250      * @param ssid the ssid of network to connect
251      * @param psk the WPA-PSK passphrase to use. This can be null.
252      * @param urlToCheck a destination url for a HTTP request check
253      * @param scanSsid whether to scan for hidden SSID for this network
254      * @param defaultType Default network type to fall back to if ssid's network type is not
255      *     determined
256      * @return WifiConnectionResult representing the wifi connection result
257      * @throws DeviceNotAvailableException
258      */
connectToNetwork( String ssid, String psk, String urlToCheck, boolean scanSsid, String defaultType)259     WifiConnectionResult connectToNetwork(
260             String ssid, String psk, String urlToCheck, boolean scanSsid, String defaultType)
261             throws DeviceNotAvailableException;
262 
263     /**
264      * Disconnect from the current wifi network and disable wifi.
265      *
266      * @return <code>true</code> if the operation succeeded.
267      * @throws DeviceNotAvailableException
268      */
disconnectFromNetwork()269     boolean disconnectFromNetwork() throws DeviceNotAvailableException;
270 
271     /**
272      * Starts network connectivity monitoring.
273      *
274      * @param interval interval between connectivity checks.
275      * @param urlToCheck a URL to check connectivity with.
276      * @return <code>true</code> if the operation succeeded.
277      * @throws DeviceNotAvailableException
278      */
startMonitor(long interval, String urlToCheck)279     boolean startMonitor(long interval, String urlToCheck) throws DeviceNotAvailableException;
280 
281     /**
282      * Stops network connectivity monitoring.
283      * <p/>
284      * This also returns the latency history since the last
285      * {@link IWifiHelper#startMonitor(long, String)} call.
286      *
287      * @return the latency history.
288      * @throws DeviceNotAvailableException
289      */
stopMonitor()290     List<Long> stopMonitor() throws DeviceNotAvailableException;
291 
292     /**
293      * Clean up the resources and the wifi helper packaged install. This should only be called when
294      * Wifi is not needed anymore for the invocation since the device would lose the wifi connection
295      * when the helper is uninstalled.
296      *
297      * @throws DeviceNotAvailableException
298      */
cleanUp()299     void cleanUp() throws DeviceNotAvailableException;
300 }
301