ConnectivityManager.java revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c
1/* 2 * Copyright (C) 2008 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 17package android.net; 18 19import android.os.RemoteException; 20 21/** 22 * Class that answers queries about the state of network connectivity. It also 23 * notifies applications when network connectivity changes. Get an instance 24 * of this class by calling 25 * {@link android.content.Context#getSystemService(String) Context.getSystemService(Context.CONNECTIVITY_SERVICE)}. 26 * <p> 27 * The primary responsibilities of this class are to: 28 * <ol> 29 * <li>Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)</li> 30 * <li>Send broadcast intents when network connectivity changes</li> 31 * <li>Attempt to "fail over" to another network when connectivity to a network 32 * is lost</li> 33 * <li>Provide an API that allows applications to query the coarse-grained or fine-grained 34 * state of the available networks</li> 35 * </ol> 36 */ 37public class ConnectivityManager 38{ 39 /** 40 * A change in network connectivity has occurred. A connection has either 41 * been established or lost. The NetworkInfo for the affected network is 42 * sent as an extra; it should be consulted to see what kind of 43 * connectivity event occurred. 44 * <p/> 45 * If this is a connection that was the result of failing over from a 46 * disconnected network, then the FAILOVER_CONNECTION boolean extra is 47 * set to true. 48 * <p/> 49 * For a loss of connectivity, if the connectivity manager is attempting 50 * to connect (or has already connected) to another network, the 51 * NetworkInfo for the new network is also passed as an extra. This lets 52 * any receivers of the broadcast know that they should not necessarily 53 * tell the user that no data traffic will be possible. Instead, the 54 * reciever should expect another broadcast soon, indicating either that 55 * the failover attempt succeeded (and so there is still overall data 56 * connectivity), or that the failover attempt failed, meaning that all 57 * connectivity has been lost. 58 * <p/> 59 * For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY 60 * is set to {@code true} if there are no connected networks at all. 61 */ 62 public static final String CONNECTIVITY_ACTION = "android.net.conn.CONNECTIVITY_CHANGE"; 63 /** 64 * The lookup key for a {@link NetworkInfo} object. Retrieve with 65 * {@link android.content.Intent#getParcelableExtra(String)}. 66 */ 67 public static final String EXTRA_NETWORK_INFO = "networkInfo"; 68 /** 69 * The lookup key for a boolean that indicates whether a connect event 70 * is for a network to which the connectivity manager was failing over 71 * following a disconnect on another network. 72 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 73 */ 74 public static final String EXTRA_IS_FAILOVER = "isFailover"; 75 /** 76 * The lookup key for a {@link NetworkInfo} object. This is supplied when 77 * there is another network that it may be possible to connect to. Retrieve with 78 * {@link android.content.Intent#getParcelableExtra(String)}. 79 */ 80 public static final String EXTRA_OTHER_NETWORK_INFO = "otherNetwork"; 81 /** 82 * The lookup key for a boolean that indicates whether there is a 83 * complete lack of connectivity, i.e., no network is available. 84 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 85 */ 86 public static final String EXTRA_NO_CONNECTIVITY = "noConnectivity"; 87 /** 88 * The lookup key for a string that indicates why an attempt to connect 89 * to a network failed. The string has no particular structure. It is 90 * intended to be used in notifications presented to users. Retrieve 91 * it with {@link android.content.Intent#getStringExtra(String)}. 92 */ 93 public static final String EXTRA_REASON = "reason"; 94 /** 95 * The lookup key for a string that provides optionally supplied 96 * extra information about the network state. The information 97 * may be passed up from the lower networking layers, and its 98 * meaning may be specific to a particular network type. Retrieve 99 * it with {@link android.content.Intent#getStringExtra(String)}. 100 */ 101 public static final String EXTRA_EXTRA_INFO = "extraInfo"; 102 103 public static final int TYPE_MOBILE = 0; 104 public static final int TYPE_WIFI = 1; 105 106 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 107 108 private IConnectivityManager mService; 109 110 static public boolean isNetworkTypeValid(int networkType) { 111 return networkType == TYPE_WIFI || networkType == TYPE_MOBILE; 112 } 113 114 public void setNetworkPreference(int preference) { 115 try { 116 mService.setNetworkPreference(preference); 117 } catch (RemoteException e) { 118 } 119 } 120 121 public int getNetworkPreference() { 122 try { 123 return mService.getNetworkPreference(); 124 } catch (RemoteException e) { 125 return -1; 126 } 127 } 128 129 public NetworkInfo getActiveNetworkInfo() { 130 try { 131 return mService.getActiveNetworkInfo(); 132 } catch (RemoteException e) { 133 return null; 134 } 135 } 136 137 public NetworkInfo getNetworkInfo(int networkType) { 138 try { 139 return mService.getNetworkInfo(networkType); 140 } catch (RemoteException e) { 141 return null; 142 } 143 } 144 145 public NetworkInfo[] getAllNetworkInfo() { 146 try { 147 return mService.getAllNetworkInfo(); 148 } catch (RemoteException e) { 149 return null; 150 } 151 } 152 153 /** {@hide} */ 154 public boolean setRadios(boolean turnOn) { 155 try { 156 return mService.setRadios(turnOn); 157 } catch (RemoteException e) { 158 return false; 159 } 160 } 161 162 /** {@hide} */ 163 public boolean setRadio(int networkType, boolean turnOn) { 164 try { 165 return mService.setRadio(networkType, turnOn); 166 } catch (RemoteException e) { 167 return false; 168 } 169 } 170 171 /** 172 * Tells the underlying networking system that the caller wants to 173 * begin using the named feature. The interpretation of {@code feature} 174 * is completely up to each networking implementation. 175 * @param networkType specifies which network the request pertains to 176 * @param feature the name of the feature to be used 177 * @return an integer value representing the outcome of the request. 178 * The interpretation of this value is specific to each networking 179 * implementation+feature combination, except that the value {@code -1} 180 * always indicates failure. 181 */ 182 public int startUsingNetworkFeature(int networkType, String feature) { 183 try { 184 return mService.startUsingNetworkFeature(networkType, feature); 185 } catch (RemoteException e) { 186 return -1; 187 } 188 } 189 190 /** 191 * Tells the underlying networking system that the caller is finished 192 * using the named feature. The interpretation of {@code feature} 193 * is completely up to each networking implementation. 194 * @param networkType specifies which network the request pertains to 195 * @param feature the name of the feature that is no longer needed 196 * @return an integer value representing the outcome of the request. 197 * The interpretation of this value is specific to each networking 198 * implementation+feature combination, except that the value {@code -1} 199 * always indicates failure. 200 */ 201 public int stopUsingNetworkFeature(int networkType, String feature) { 202 try { 203 return mService.stopUsingNetworkFeature(networkType, feature); 204 } catch (RemoteException e) { 205 return -1; 206 } 207 } 208 209 /** 210 * Ensure that a network route exists to deliver traffic to the specified 211 * host via the specified network interface. An attempt to add a route that 212 * already exists is ignored, but treated as successful. 213 * @param networkType the type of the network over which traffic to the specified 214 * host is to be routed 215 * @param hostAddress the IP address of the host to which the route is desired 216 * @return {@code true} on success, {@code false} on failure 217 */ 218 public boolean requestRouteToHost(int networkType, int hostAddress) { 219 try { 220 return mService.requestRouteToHost(networkType, hostAddress); 221 } catch (RemoteException e) { 222 return false; 223 } 224 } 225 226 /** 227 * Don't allow use of default constructor. 228 */ 229 @SuppressWarnings({"UnusedDeclaration"}) 230 private ConnectivityManager() { 231 } 232 233 /** 234 * {@hide} 235 */ 236 public ConnectivityManager(IConnectivityManager service) { 237 if (service == null) { 238 throw new IllegalArgumentException( 239 "ConnectivityManager() cannot be constructed with null service"); 240 } 241 mService = service; 242 } 243} 244