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 * Broadcast Action: A tetherable connection has come or gone 120 * TODO - finish the doc 121 * @hide 122 */ 123 public static final String ACTION_TETHER_STATE_CHANGED = 124 "android.net.conn.TETHER_STATE_CHANGED"; 125 126 /** 127 * @hide 128 * gives a String[] 129 */ 130 public static final String EXTRA_AVAILABLE_TETHER = "availableArray"; 131 132 /** 133 * @hide 134 * gives a String[] 135 */ 136 public static final String EXTRA_ACTIVE_TETHER = "activeArray"; 137 138 /** 139 * @hide 140 * gives a String[] 141 */ 142 public static final String EXTRA_ERRORED_TETHER = "erroredArray"; 143 144 /** 145 * The Default Mobile data connection. When active, all data traffic 146 * will use this connection by default. Should not coexist with other 147 * default connections. 148 */ 149 public static final int TYPE_MOBILE = 0; 150 /** 151 * The Default WIFI data connection. When active, all data traffic 152 * will use this connection by default. Should not coexist with other 153 * default connections. 154 */ 155 public static final int TYPE_WIFI = 1; 156 /** 157 * An MMS-specific Mobile data connection. This connection may be the 158 * same as {@link #TYPE_MOBILE} but it may be different. This is used 159 * by applications needing to talk to the carrier's Multimedia Messaging 160 * Service servers. It may coexist with default data connections. 161 */ 162 public static final int TYPE_MOBILE_MMS = 2; 163 /** 164 * A SUPL-specific Mobile data connection. This connection may be the 165 * same as {@link #TYPE_MOBILE} but it may be different. This is used 166 * by applications needing to talk to the carrier's Secure User Plane 167 * Location servers for help locating the device. It may coexist with 168 * default data connections. 169 */ 170 public static final int TYPE_MOBILE_SUPL = 3; 171 /** 172 * A DUN-specific Mobile data connection. This connection may be the 173 * same as {@link #TYPE_MOBILE} but it may be different. This is used 174 * by applicaitons performing a Dial Up Networking bridge so that 175 * the carrier is aware of DUN traffic. It may coexist with default data 176 * connections. 177 */ 178 public static final int TYPE_MOBILE_DUN = 4; 179 /** 180 * A High Priority Mobile data connection. This connection is typically 181 * the same as {@link #TYPE_MOBILE} but the routing setup is different. 182 * Only requesting processes will have access to the Mobile DNS servers 183 * and only IP's explicitly requested via {@link #requestRouteToHost} 184 * will route over this interface if a default route exists. 185 */ 186 public static final int TYPE_MOBILE_HIPRI = 5; 187 /** 188 * The Default WiMAX data connection. When active, all data traffic 189 * will use this connection by default. Should not coexist with other 190 * default connections. 191 */ 192 public static final int TYPE_WIMAX = 6; 193 /** {@hide} TODO: Need to adjust this for WiMAX. */ 194 public static final int MAX_RADIO_TYPE = TYPE_WIFI; 195 /** {@hide} TODO: Need to adjust this for WiMAX. */ 196 public static final int MAX_NETWORK_TYPE = TYPE_MOBILE_HIPRI; 197 198 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 199 200 private IConnectivityManager mService; 201 202 static public boolean isNetworkTypeValid(int networkType) { 203 return networkType >= 0 && networkType <= MAX_NETWORK_TYPE; 204 } 205 206 public void setNetworkPreference(int preference) { 207 try { 208 mService.setNetworkPreference(preference); 209 } catch (RemoteException e) { 210 } 211 } 212 213 public int getNetworkPreference() { 214 try { 215 return mService.getNetworkPreference(); 216 } catch (RemoteException e) { 217 return -1; 218 } 219 } 220 221 public NetworkInfo getActiveNetworkInfo() { 222 try { 223 return mService.getActiveNetworkInfo(); 224 } catch (RemoteException e) { 225 return null; 226 } 227 } 228 229 public NetworkInfo getNetworkInfo(int networkType) { 230 try { 231 return mService.getNetworkInfo(networkType); 232 } catch (RemoteException e) { 233 return null; 234 } 235 } 236 237 public NetworkInfo[] getAllNetworkInfo() { 238 try { 239 return mService.getAllNetworkInfo(); 240 } catch (RemoteException e) { 241 return null; 242 } 243 } 244 245 /** {@hide} */ 246 public boolean setRadios(boolean turnOn) { 247 try { 248 return mService.setRadios(turnOn); 249 } catch (RemoteException e) { 250 return false; 251 } 252 } 253 254 /** {@hide} */ 255 public boolean setRadio(int networkType, boolean turnOn) { 256 try { 257 return mService.setRadio(networkType, turnOn); 258 } catch (RemoteException e) { 259 return false; 260 } 261 } 262 263 /** 264 * Tells the underlying networking system that the caller wants to 265 * begin using the named feature. The interpretation of {@code feature} 266 * is completely up to each networking implementation. 267 * @param networkType specifies which network the request pertains to 268 * @param feature the name of the feature to be used 269 * @return an integer value representing the outcome of the request. 270 * The interpretation of this value is specific to each networking 271 * implementation+feature combination, except that the value {@code -1} 272 * always indicates failure. 273 */ 274 public int startUsingNetworkFeature(int networkType, String feature) { 275 try { 276 return mService.startUsingNetworkFeature(networkType, feature, 277 new Binder()); 278 } catch (RemoteException e) { 279 return -1; 280 } 281 } 282 283 /** 284 * Tells the underlying networking system that the caller is finished 285 * using the named feature. The interpretation of {@code feature} 286 * is completely up to each networking implementation. 287 * @param networkType specifies which network the request pertains to 288 * @param feature the name of the feature that is no longer needed 289 * @return an integer value representing the outcome of the request. 290 * The interpretation of this value is specific to each networking 291 * implementation+feature combination, except that the value {@code -1} 292 * always indicates failure. 293 */ 294 public int stopUsingNetworkFeature(int networkType, String feature) { 295 try { 296 return mService.stopUsingNetworkFeature(networkType, feature); 297 } catch (RemoteException e) { 298 return -1; 299 } 300 } 301 302 /** 303 * Ensure that a network route exists to deliver traffic to the specified 304 * host via the specified network interface. An attempt to add a route that 305 * already exists is ignored, but treated as successful. 306 * @param networkType the type of the network over which traffic to the specified 307 * host is to be routed 308 * @param hostAddress the IP address of the host to which the route is desired 309 * @return {@code true} on success, {@code false} on failure 310 */ 311 public boolean requestRouteToHost(int networkType, int hostAddress) { 312 try { 313 return mService.requestRouteToHost(networkType, hostAddress); 314 } catch (RemoteException e) { 315 return false; 316 } 317 } 318 319 /** 320 * Returns the value of the setting for background data usage. If false, 321 * applications should not use the network if the application is not in the 322 * foreground. Developers should respect this setting, and check the value 323 * of this before performing any background data operations. 324 * <p> 325 * All applications that have background services that use the network 326 * should listen to {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}. 327 * 328 * @return Whether background data usage is allowed. 329 */ 330 public boolean getBackgroundDataSetting() { 331 try { 332 return mService.getBackgroundDataSetting(); 333 } catch (RemoteException e) { 334 // Err on the side of safety 335 return false; 336 } 337 } 338 339 /** 340 * Sets the value of the setting for background data usage. 341 * 342 * @param allowBackgroundData Whether an application should use data while 343 * it is in the background. 344 * 345 * @attr ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING 346 * @see #getBackgroundDataSetting() 347 * @hide 348 */ 349 public void setBackgroundDataSetting(boolean allowBackgroundData) { 350 try { 351 mService.setBackgroundDataSetting(allowBackgroundData); 352 } catch (RemoteException e) { 353 } 354 } 355 356 /** 357 * Gets the value of the setting for enabling Mobile data. 358 * 359 * @return Whether mobile data is enabled. 360 * @hide 361 */ 362 public boolean getMobileDataEnabled() { 363 try { 364 return mService.getMobileDataEnabled(); 365 } catch (RemoteException e) { 366 return true; 367 } 368 } 369 370 /** 371 * Sets the persisted value for enabling/disabling Mobile data. 372 * 373 * @param enabled Whether the mobile data connection should be 374 * used or not. 375 * @hide 376 */ 377 public void setMobileDataEnabled(boolean enabled) { 378 try { 379 mService.setMobileDataEnabled(enabled); 380 } catch (RemoteException e) { 381 } 382 } 383 384 /** 385 * Don't allow use of default constructor. 386 */ 387 @SuppressWarnings({"UnusedDeclaration"}) 388 private ConnectivityManager() { 389 } 390 391 /** 392 * {@hide} 393 */ 394 public ConnectivityManager(IConnectivityManager service) { 395 if (service == null) { 396 throw new IllegalArgumentException( 397 "ConnectivityManager() cannot be constructed with null service"); 398 } 399 mService = service; 400 } 401 402 /** 403 * {@hide} 404 */ 405 public String[] getTetherableIfaces() { 406 try { 407 return mService.getTetherableIfaces(); 408 } catch (RemoteException e) { 409 return new String[0]; 410 } 411 } 412 413 /** 414 * {@hide} 415 */ 416 public String[] getTetheredIfaces() { 417 try { 418 return mService.getTetheredIfaces(); 419 } catch (RemoteException e) { 420 return new String[0]; 421 } 422 } 423 424 /** 425 * {@hide} 426 */ 427 public String[] getTetheringErroredIfaces() { 428 try { 429 return mService.getTetheringErroredIfaces(); 430 } catch (RemoteException e) { 431 return new String[0]; 432 } 433 } 434 435 /** 436 * @return error A TETHER_ERROR value indicating success or failure type 437 * {@hide} 438 */ 439 public int tether(String iface) { 440 try { 441 return mService.tether(iface); 442 } catch (RemoteException e) { 443 return TETHER_ERROR_SERVICE_UNAVAIL; 444 } 445 } 446 447 /** 448 * @return error A TETHER_ERROR value indicating success or failure type 449 * {@hide} 450 */ 451 public int untether(String iface) { 452 try { 453 return mService.untether(iface); 454 } catch (RemoteException e) { 455 return TETHER_ERROR_SERVICE_UNAVAIL; 456 } 457 } 458 459 /** 460 * {@hide} 461 */ 462 public boolean isTetheringSupported() { 463 try { 464 return mService.isTetheringSupported(); 465 } catch (RemoteException e) { 466 return false; 467 } 468 } 469 470 /** 471 * {@hide} 472 */ 473 public String[] getTetherableUsbRegexs() { 474 try { 475 return mService.getTetherableUsbRegexs(); 476 } catch (RemoteException e) { 477 return new String[0]; 478 } 479 } 480 481 /** 482 * {@hide} 483 */ 484 public String[] getTetherableWifiRegexs() { 485 try { 486 return mService.getTetherableWifiRegexs(); 487 } catch (RemoteException e) { 488 return new String[0]; 489 } 490 } 491 492 /** {@hide} */ 493 public static final int TETHER_ERROR_NO_ERROR = 0; 494 /** {@hide} */ 495 public static final int TETHER_ERROR_UNKNOWN_IFACE = 1; 496 /** {@hide} */ 497 public static final int TETHER_ERROR_SERVICE_UNAVAIL = 2; 498 /** {@hide} */ 499 public static final int TETHER_ERROR_UNSUPPORTED = 3; 500 /** {@hide} */ 501 public static final int TETHER_ERROR_UNAVAIL_IFACE = 4; 502 /** {@hide} */ 503 public static final int TETHER_ERROR_MASTER_ERROR = 5; 504 /** {@hide} */ 505 public static final int TETHER_ERROR_TETHER_IFACE_ERROR = 6; 506 /** {@hide} */ 507 public static final int TETHER_ERROR_UNTETHER_IFACE_ERROR = 7; 508 /** {@hide} */ 509 public static final int TETHER_ERROR_ENABLE_NAT_ERROR = 8; 510 /** {@hide} */ 511 public static final int TETHER_ERROR_DISABLE_NAT_ERROR = 9; 512 /** {@hide} */ 513 public static final int TETHER_ERROR_IFACE_CFG_ERROR = 10; 514 515 /** 516 * @param iface The name of the interface we're interested in 517 * @return error The error code of the last error tethering or untethering the named 518 * interface 519 * {@hide} 520 */ 521 public int getLastTetherError(String iface) { 522 try { 523 return mService.getLastTetherError(iface); 524 } catch (RemoteException e) { 525 return TETHER_ERROR_SERVICE_UNAVAIL; 526 } 527 } 528 } 529
