Home | History | Annotate | Download | only in device 
      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      */
     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      */
     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      */
     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      */
     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      */
     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      */
     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      */
    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      */
    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      */
    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      */
    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      */
    143     String getBSSID() throws DeviceNotAvailableException;
    144 
    145     /**
    146      * Removes all known networks.
    147      *
    148      * @throws DeviceNotAvailableException
    149      */
    150     boolean removeAllNetworks() throws DeviceNotAvailableException;
    151 
    152     /**
    153      * Check if wifi is currently enabled.
    154      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    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      */
    276     void cleanUp() throws DeviceNotAvailableException;
    277 }
    278