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