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 17 package android.net; 18 19 import android.annotation.SdkConstant; 20 import android.annotation.SdkConstant.SdkConstantType; 21 import android.os.Binder; 22 import android.os.RemoteException; 23 24 /** 25 * Class that answers queries about the state of network connectivity. It also 26 * notifies applications when network connectivity changes. Get an instance 27 * of this class by calling 28 * {@link android.content.Context#getSystemService(String) Context.getSystemService(Context.CONNECTIVITY_SERVICE)}. 29 * <p> 30 * The primary responsibilities of this class are to: 31 * <ol> 32 * <li>Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)</li> 33 * <li>Send broadcast intents when network connectivity changes</li> 34 * <li>Attempt to "fail over" to another network when connectivity to a network 35 * is lost</li> 36 * <li>Provide an API that allows applications to query the coarse-grained or fine-grained 37 * state of the available networks</li> 38 * </ol> 39 */ 40 public class ConnectivityManager 41 { 42 /** 43 * A change in network connectivity has occurred. A connection has either 44 * been established or lost. The NetworkInfo for the affected network is 45 * sent as an extra; it should be consulted to see what kind of 46 * connectivity event occurred. 47 * <p/> 48 * If this is a connection that was the result of failing over from a 49 * disconnected network, then the FAILOVER_CONNECTION boolean extra is 50 * set to true. 51 * <p/> 52 * For a loss of connectivity, if the connectivity manager is attempting 53 * to connect (or has already connected) to another network, the 54 * NetworkInfo for the new network is also passed as an extra. This lets 55 * any receivers of the broadcast know that they should not necessarily 56 * tell the user that no data traffic will be possible. Instead, the 57 * reciever should expect another broadcast soon, indicating either that 58 * the failover attempt succeeded (and so there is still overall data 59 * connectivity), or that the failover attempt failed, meaning that all 60 * connectivity has been lost. 61 * <p/> 62 * For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY 63 * is set to {@code true} if there are no connected networks at all. 64 */ 65 public static final String CONNECTIVITY_ACTION = "android.net.conn.CONNECTIVITY_CHANGE"; 66 /** 67 * The lookup key for a {@link NetworkInfo} object. Retrieve with 68 * {@link android.content.Intent#getParcelableExtra(String)}. 69 */ 70 public static final String EXTRA_NETWORK_INFO = "networkInfo"; 71 /** 72 * The lookup key for a boolean that indicates whether a connect event 73 * is for a network to which the connectivity manager was failing over 74 * following a disconnect on another network. 75 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 76 */ 77 public static final String EXTRA_IS_FAILOVER = "isFailover"; 78 /** 79 * The lookup key for a {@link NetworkInfo} object. This is supplied when 80 * there is another network that it may be possible to connect to. Retrieve with 81 * {@link android.content.Intent#getParcelableExtra(String)}. 82 */ 83 public static final String EXTRA_OTHER_NETWORK_INFO = "otherNetwork"; 84 /** 85 * The lookup key for a boolean that indicates whether there is a 86 * complete lack of connectivity, i.e., no network is available. 87 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 88 */ 89 public static final String EXTRA_NO_CONNECTIVITY = "noConnectivity"; 90 /** 91 * The lookup key for a string that indicates why an attempt to connect 92 * to a network failed. The string has no particular structure. It is 93 * intended to be used in notifications presented to users. Retrieve 94 * it with {@link android.content.Intent#getStringExtra(String)}. 95 */ 96 public static final String EXTRA_REASON = "reason"; 97 /** 98 * The lookup key for a string that provides optionally supplied 99 * extra information about the network state. The information 100 * may be passed up from the lower networking layers, and its 101 * meaning may be specific to a particular network type. Retrieve 102 * it with {@link android.content.Intent#getStringExtra(String)}. 103 */ 104 public static final String EXTRA_EXTRA_INFO = "extraInfo"; 105 106 /** 107 * Broadcast Action: The setting for background data usage has changed 108 * values. Use {@link #getBackgroundDataSetting()} to get the current value. 109 * <p> 110 * If an application uses the network in the background, it should listen 111 * for this broadcast and stop using the background data if the value is 112 * false. 113 */ 114 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 115 public static final String ACTION_BACKGROUND_DATA_SETTING_CHANGED = 116 "android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"; 117 118 /** 119 * The Default Mobile data connection. When active, all data traffic 120 * will use this connection by default. Should not coexist with other 121 * default connections. 122 */ 123 public static final int TYPE_MOBILE = 0; 124 /** 125 * The Default WIFI data connection. When active, all data traffic 126 * will use this connection by default. Should not coexist with other 127 * default connections. 128 */ 129 public static final int TYPE_WIFI = 1; 130 /** 131 * An MMS-specific Mobile data connection. This connection may be the 132 * same as {@link #TYPEMOBILE} but it may be different. This is used 133 * by applications needing to talk to the carrier's Multimedia Messaging 134 * Service servers. It may coexist with default data connections. 135 * {@hide} 136 */ 137 public static final int TYPE_MOBILE_MMS = 2; 138 /** 139 * A SUPL-specific Mobile data connection. This connection may be the 140 * same as {@link #TYPEMOBILE} but it may be different. This is used 141 * by applications needing to talk to the carrier's Secure User Plane 142 * Location servers for help locating the device. It may coexist with 143 * default data connections. 144 * {@hide} 145 */ 146 public static final int TYPE_MOBILE_SUPL = 3; 147 /** 148 * A DUN-specific Mobile data connection. This connection may be the 149 * same as {@link #TYPEMOBILE} but it may be different. This is used 150 * by applicaitons performing a Dial Up Networking bridge so that 151 * the carrier is aware of DUN traffic. It may coexist with default data 152 * connections. 153 * {@hide} 154 */ 155 public static final int TYPE_MOBILE_DUN = 4; 156 /** 157 * A High Priority Mobile data connection. This connection is typically 158 * the same as {@link #TYPEMOBILE} but the routing setup is different. 159 * Only requesting processes will have access to the Mobile DNS servers 160 * and only IP's explicitly requested via {@link #requestRouteToHost} 161 * will route over this interface. 162 *{@hide} 163 */ 164 public static final int TYPE_MOBILE_HIPRI = 5; 165 /** {@hide} */ 166 public static final int MAX_RADIO_TYPE = TYPE_WIFI; 167 /** {@hide} */ 168 public static final int MAX_NETWORK_TYPE = TYPE_MOBILE_HIPRI; 169 170 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 171 172 private IConnectivityManager mService; 173 isNetworkTypeValid(int networkType)174 static public boolean isNetworkTypeValid(int networkType) { 175 return networkType >= 0 && networkType <= MAX_NETWORK_TYPE; 176 } 177 setNetworkPreference(int preference)178 public void setNetworkPreference(int preference) { 179 try { 180 mService.setNetworkPreference(preference); 181 } catch (RemoteException e) { 182 } 183 } 184 getNetworkPreference()185 public int getNetworkPreference() { 186 try { 187 return mService.getNetworkPreference(); 188 } catch (RemoteException e) { 189 return -1; 190 } 191 } 192 getActiveNetworkInfo()193 public NetworkInfo getActiveNetworkInfo() { 194 try { 195 return mService.getActiveNetworkInfo(); 196 } catch (RemoteException e) { 197 return null; 198 } 199 } 200 getNetworkInfo(int networkType)201 public NetworkInfo getNetworkInfo(int networkType) { 202 try { 203 return mService.getNetworkInfo(networkType); 204 } catch (RemoteException e) { 205 return null; 206 } 207 } 208 getAllNetworkInfo()209 public NetworkInfo[] getAllNetworkInfo() { 210 try { 211 return mService.getAllNetworkInfo(); 212 } catch (RemoteException e) { 213 return null; 214 } 215 } 216 217 /** {@hide} */ setRadios(boolean turnOn)218 public boolean setRadios(boolean turnOn) { 219 try { 220 return mService.setRadios(turnOn); 221 } catch (RemoteException e) { 222 return false; 223 } 224 } 225 226 /** {@hide} */ setRadio(int networkType, boolean turnOn)227 public boolean setRadio(int networkType, boolean turnOn) { 228 try { 229 return mService.setRadio(networkType, turnOn); 230 } catch (RemoteException e) { 231 return false; 232 } 233 } 234 235 /** 236 * Tells the underlying networking system that the caller wants to 237 * begin using the named feature. The interpretation of {@code feature} 238 * is completely up to each networking implementation. 239 * @param networkType specifies which network the request pertains to 240 * @param feature the name of the feature to be used 241 * @return an integer value representing the outcome of the request. 242 * The interpretation of this value is specific to each networking 243 * implementation+feature combination, except that the value {@code -1} 244 * always indicates failure. 245 */ startUsingNetworkFeature(int networkType, String feature)246 public int startUsingNetworkFeature(int networkType, String feature) { 247 try { 248 return mService.startUsingNetworkFeature(networkType, feature, 249 new Binder()); 250 } catch (RemoteException e) { 251 return -1; 252 } 253 } 254 255 /** 256 * Tells the underlying networking system that the caller is finished 257 * using the named feature. The interpretation of {@code feature} 258 * is completely up to each networking implementation. 259 * @param networkType specifies which network the request pertains to 260 * @param feature the name of the feature that is no longer needed 261 * @return an integer value representing the outcome of the request. 262 * The interpretation of this value is specific to each networking 263 * implementation+feature combination, except that the value {@code -1} 264 * always indicates failure. 265 */ stopUsingNetworkFeature(int networkType, String feature)266 public int stopUsingNetworkFeature(int networkType, String feature) { 267 try { 268 return mService.stopUsingNetworkFeature(networkType, feature); 269 } catch (RemoteException e) { 270 return -1; 271 } 272 } 273 274 /** 275 * Ensure that a network route exists to deliver traffic to the specified 276 * host via the specified network interface. An attempt to add a route that 277 * already exists is ignored, but treated as successful. 278 * @param networkType the type of the network over which traffic to the specified 279 * host is to be routed 280 * @param hostAddress the IP address of the host to which the route is desired 281 * @return {@code true} on success, {@code false} on failure 282 */ requestRouteToHost(int networkType, int hostAddress)283 public boolean requestRouteToHost(int networkType, int hostAddress) { 284 try { 285 return mService.requestRouteToHost(networkType, hostAddress); 286 } catch (RemoteException e) { 287 return false; 288 } 289 } 290 291 /** 292 * Returns the value of the setting for background data usage. If false, 293 * applications should not use the network if the application is not in the 294 * foreground. Developers should respect this setting, and check the value 295 * of this before performing any background data operations. 296 * <p> 297 * All applications that have background services that use the network 298 * should listen to {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}. 299 * 300 * @return Whether background data usage is allowed. 301 */ getBackgroundDataSetting()302 public boolean getBackgroundDataSetting() { 303 try { 304 return mService.getBackgroundDataSetting(); 305 } catch (RemoteException e) { 306 // Err on the side of safety 307 return false; 308 } 309 } 310 311 /** 312 * Sets the value of the setting for background data usage. 313 * 314 * @param allowBackgroundData Whether an application should use data while 315 * it is in the background. 316 * 317 * @attr ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING 318 * @see #getBackgroundDataSetting() 319 * @hide 320 */ setBackgroundDataSetting(boolean allowBackgroundData)321 public void setBackgroundDataSetting(boolean allowBackgroundData) { 322 try { 323 mService.setBackgroundDataSetting(allowBackgroundData); 324 } catch (RemoteException e) { 325 } 326 } 327 328 /** 329 * Don't allow use of default constructor. 330 */ 331 @SuppressWarnings({"UnusedDeclaration"}) ConnectivityManager()332 private ConnectivityManager() { 333 } 334 335 /** 336 * {@hide} 337 */ ConnectivityManager(IConnectivityManager service)338 public ConnectivityManager(IConnectivityManager service) { 339 if (service == null) { 340 throw new IllegalArgumentException( 341 "ConnectivityManager() cannot be constructed with null service"); 342 } 343 mService = service; 344 } 345 } 346