ConnectivityManager.java revision da3d5e6587c1476d489495ac93e84ebf223024c9
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.annotation.SdkConstant; 20import android.annotation.SdkConstant.SdkConstantType; 21import android.os.Binder; 22import android.os.RemoteException; 23 24import java.net.InetAddress; 25import java.net.UnknownHostException; 26 27/** 28 * Class that answers queries about the state of network connectivity. It also 29 * notifies applications when network connectivity changes. Get an instance 30 * of this class by calling 31 * {@link android.content.Context#getSystemService(String) Context.getSystemService(Context.CONNECTIVITY_SERVICE)}. 32 * <p> 33 * The primary responsibilities of this class are to: 34 * <ol> 35 * <li>Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)</li> 36 * <li>Send broadcast intents when network connectivity changes</li> 37 * <li>Attempt to "fail over" to another network when connectivity to a network 38 * is lost</li> 39 * <li>Provide an API that allows applications to query the coarse-grained or fine-grained 40 * state of the available networks</li> 41 * </ol> 42 */ 43public class ConnectivityManager 44{ 45 /** 46 * A change in network connectivity has occurred. A connection has either 47 * been established or lost. The NetworkInfo for the affected network is 48 * sent as an extra; it should be consulted to see what kind of 49 * connectivity event occurred. 50 * <p/> 51 * If this is a connection that was the result of failing over from a 52 * disconnected network, then the FAILOVER_CONNECTION boolean extra is 53 * set to true. 54 * <p/> 55 * For a loss of connectivity, if the connectivity manager is attempting 56 * to connect (or has already connected) to another network, the 57 * NetworkInfo for the new network is also passed as an extra. This lets 58 * any receivers of the broadcast know that they should not necessarily 59 * tell the user that no data traffic will be possible. Instead, the 60 * reciever should expect another broadcast soon, indicating either that 61 * the failover attempt succeeded (and so there is still overall data 62 * connectivity), or that the failover attempt failed, meaning that all 63 * connectivity has been lost. 64 * <p/> 65 * For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY 66 * is set to {@code true} if there are no connected networks at all. 67 */ 68 public static final String CONNECTIVITY_ACTION = "android.net.conn.CONNECTIVITY_CHANGE"; 69 /** 70 * The lookup key for a {@link NetworkInfo} object. Retrieve with 71 * {@link android.content.Intent#getParcelableExtra(String)}. 72 */ 73 public static final String EXTRA_NETWORK_INFO = "networkInfo"; 74 /** 75 * The lookup key for a boolean that indicates whether a connect event 76 * is for a network to which the connectivity manager was failing over 77 * following a disconnect on another network. 78 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 79 */ 80 public static final String EXTRA_IS_FAILOVER = "isFailover"; 81 /** 82 * The lookup key for a {@link NetworkInfo} object. This is supplied when 83 * there is another network that it may be possible to connect to. Retrieve with 84 * {@link android.content.Intent#getParcelableExtra(String)}. 85 */ 86 public static final String EXTRA_OTHER_NETWORK_INFO = "otherNetwork"; 87 /** 88 * The lookup key for a boolean that indicates whether there is a 89 * complete lack of connectivity, i.e., no network is available. 90 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 91 */ 92 public static final String EXTRA_NO_CONNECTIVITY = "noConnectivity"; 93 /** 94 * The lookup key for a string that indicates why an attempt to connect 95 * to a network failed. The string has no particular structure. It is 96 * intended to be used in notifications presented to users. Retrieve 97 * it with {@link android.content.Intent#getStringExtra(String)}. 98 */ 99 public static final String EXTRA_REASON = "reason"; 100 /** 101 * The lookup key for a string that provides optionally supplied 102 * extra information about the network state. The information 103 * may be passed up from the lower networking layers, and its 104 * meaning may be specific to a particular network type. Retrieve 105 * it with {@link android.content.Intent#getStringExtra(String)}. 106 */ 107 public static final String EXTRA_EXTRA_INFO = "extraInfo"; 108 /** 109 * The lookup key for an int that provides information about 110 * our connection to the internet at large. 0 indicates no connection, 111 * 100 indicates a great connection. Retrieve it with 112 * {@link android.content.Intent@getIntExtra(String)}. 113 * {@hide} 114 */ 115 public static final String EXTRA_INET_CONDITION = "inetCondition"; 116 117 /** 118 * Broadcast Action: The setting for background data usage has changed 119 * values. Use {@link #getBackgroundDataSetting()} to get the current value. 120 * <p> 121 * If an application uses the network in the background, it should listen 122 * for this broadcast and stop using the background data if the value is 123 * false. 124 */ 125 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 126 public static final String ACTION_BACKGROUND_DATA_SETTING_CHANGED = 127 "android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"; 128 129 130 /** 131 * Broadcast Action: The network connection may not be good 132 * uses {@code ConnectivityManager.EXTRA_INET_CONDITION} and 133 * {@code ConnectivityManager.EXTRA_NETWORK_INFO} to specify 134 * the network and it's condition. 135 * @hide 136 */ 137 public static final String INET_CONDITION_ACTION = 138 "android.net.conn.INET_CONDITION_ACTION"; 139 140 /** 141 * Broadcast Action: A tetherable connection has come or gone 142 * TODO - finish the doc 143 * @hide 144 */ 145 public static final String ACTION_TETHER_STATE_CHANGED = 146 "android.net.conn.TETHER_STATE_CHANGED"; 147 148 /** 149 * @hide 150 * gives a String[] 151 */ 152 public static final String EXTRA_AVAILABLE_TETHER = "availableArray"; 153 154 /** 155 * @hide 156 * gives a String[] 157 */ 158 public static final String EXTRA_ACTIVE_TETHER = "activeArray"; 159 160 /** 161 * @hide 162 * gives a String[] 163 */ 164 public static final String EXTRA_ERRORED_TETHER = "erroredArray"; 165 166 /** 167 * The Default Mobile data connection. When active, all data traffic 168 * will use this connection by default. Should not coexist with other 169 * default connections. 170 */ 171 public static final int TYPE_MOBILE = 0; 172 /** 173 * The Default WIFI data connection. When active, all data traffic 174 * will use this connection by default. Should not coexist with other 175 * default connections. 176 */ 177 public static final int TYPE_WIFI = 1; 178 /** 179 * An MMS-specific Mobile data connection. This connection may be the 180 * same as {@link #TYPE_MOBILE} but it may be different. This is used 181 * by applications needing to talk to the carrier's Multimedia Messaging 182 * Service servers. It may coexist with default data connections. 183 */ 184 public static final int TYPE_MOBILE_MMS = 2; 185 /** 186 * A SUPL-specific Mobile data connection. This connection may be the 187 * same as {@link #TYPE_MOBILE} but it may be different. This is used 188 * by applications needing to talk to the carrier's Secure User Plane 189 * Location servers for help locating the device. It may coexist with 190 * default data connections. 191 */ 192 public static final int TYPE_MOBILE_SUPL = 3; 193 /** 194 * A DUN-specific Mobile data connection. This connection may be the 195 * same as {@link #TYPE_MOBILE} but it may be different. This is used 196 * by applicaitons performing a Dial Up Networking bridge so that 197 * the carrier is aware of DUN traffic. It may coexist with default data 198 * connections. 199 */ 200 public static final int TYPE_MOBILE_DUN = 4; 201 /** 202 * A High Priority Mobile data connection. This connection is typically 203 * the same as {@link #TYPE_MOBILE} but the routing setup is different. 204 * Only requesting processes will have access to the Mobile DNS servers 205 * and only IP's explicitly requested via {@link #requestRouteToHost} 206 * will route over this interface if a default route exists. 207 */ 208 public static final int TYPE_MOBILE_HIPRI = 5; 209 /** 210 * The Default WiMAX data connection. When active, all data traffic 211 * will use this connection by default. Should not coexist with other 212 * default connections. 213 */ 214 public static final int TYPE_WIMAX = 6; 215 216 /** {@hide} */ 217 public static final int TYPE_DUMMY = 7; 218 /** {@hide} TODO: Need to adjust this for WiMAX. */ 219 public static final int MAX_RADIO_TYPE = TYPE_WIFI; 220 /** {@hide} TODO: Need to adjust this for WiMAX. */ 221 public static final int MAX_NETWORK_TYPE = TYPE_DUMMY; 222 223 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 224 225 private IConnectivityManager mService; 226 227 static public boolean isNetworkTypeValid(int networkType) { 228 return networkType >= 0 && networkType <= MAX_NETWORK_TYPE; 229 } 230 231 public void setNetworkPreference(int preference) { 232 try { 233 mService.setNetworkPreference(preference); 234 } catch (RemoteException e) { 235 } 236 } 237 238 public int getNetworkPreference() { 239 try { 240 return mService.getNetworkPreference(); 241 } catch (RemoteException e) { 242 return -1; 243 } 244 } 245 246 public NetworkInfo getActiveNetworkInfo() { 247 try { 248 return mService.getActiveNetworkInfo(); 249 } catch (RemoteException e) { 250 return null; 251 } 252 } 253 254 public NetworkInfo getNetworkInfo(int networkType) { 255 try { 256 return mService.getNetworkInfo(networkType); 257 } catch (RemoteException e) { 258 return null; 259 } 260 } 261 262 public NetworkInfo[] getAllNetworkInfo() { 263 try { 264 return mService.getAllNetworkInfo(); 265 } catch (RemoteException e) { 266 return null; 267 } 268 } 269 270 /** @hide */ 271 public LinkProperties getActiveLinkProperties() { 272 try { 273 return mService.getActiveLinkProperties(); 274 } catch (RemoteException e) { 275 return null; 276 } 277 } 278 279 /** @hide */ 280 public LinkProperties getLinkProperties(int networkType) { 281 try { 282 return mService.getLinkProperties(networkType); 283 } catch (RemoteException e) { 284 return null; 285 } 286 } 287 288 /** {@hide} */ 289 public boolean setRadios(boolean turnOn) { 290 try { 291 return mService.setRadios(turnOn); 292 } catch (RemoteException e) { 293 return false; 294 } 295 } 296 297 /** {@hide} */ 298 public boolean setRadio(int networkType, boolean turnOn) { 299 try { 300 return mService.setRadio(networkType, turnOn); 301 } catch (RemoteException e) { 302 return false; 303 } 304 } 305 306 /** 307 * Tells the underlying networking system that the caller wants to 308 * begin using the named feature. The interpretation of {@code feature} 309 * is completely up to each networking implementation. 310 * @param networkType specifies which network the request pertains to 311 * @param feature the name of the feature to be used 312 * @return an integer value representing the outcome of the request. 313 * The interpretation of this value is specific to each networking 314 * implementation+feature combination, except that the value {@code -1} 315 * always indicates failure. 316 */ 317 public int startUsingNetworkFeature(int networkType, String feature) { 318 try { 319 return mService.startUsingNetworkFeature(networkType, feature, 320 new Binder()); 321 } catch (RemoteException e) { 322 return -1; 323 } 324 } 325 326 /** 327 * Tells the underlying networking system that the caller is finished 328 * using the named feature. The interpretation of {@code feature} 329 * is completely up to each networking implementation. 330 * @param networkType specifies which network the request pertains to 331 * @param feature the name of the feature that is no longer needed 332 * @return an integer value representing the outcome of the request. 333 * The interpretation of this value is specific to each networking 334 * implementation+feature combination, except that the value {@code -1} 335 * always indicates failure. 336 */ 337 public int stopUsingNetworkFeature(int networkType, String feature) { 338 try { 339 return mService.stopUsingNetworkFeature(networkType, feature); 340 } catch (RemoteException e) { 341 return -1; 342 } 343 } 344 345 /** 346 * Ensure that a network route exists to deliver traffic to the specified 347 * host via the specified network interface. An attempt to add a route that 348 * already exists is ignored, but treated as successful. 349 * @param networkType the type of the network over which traffic to the specified 350 * host is to be routed 351 * @param hostAddress the IP address of the host to which the route is desired 352 * @return {@code true} on success, {@code false} on failure 353 */ 354 public boolean requestRouteToHost(int networkType, int hostAddress) { 355 InetAddress inetAddress = NetworkUtils.intToInetAddress(hostAddress); 356 357 if (inetAddress == null) { 358 return false; 359 } 360 361 return requestRouteToHostAddress(networkType, inetAddress); 362 } 363 364 /** 365 * Ensure that a network route exists to deliver traffic to the specified 366 * host via the specified network interface. An attempt to add a route that 367 * already exists is ignored, but treated as successful. 368 * @param networkType the type of the network over which traffic to the specified 369 * host is to be routed 370 * @param hostAddress the IP address of the host to which the route is desired 371 * @return {@code true} on success, {@code false} on failure 372 * @hide 373 */ 374 public boolean requestRouteToHostAddress(int networkType, InetAddress hostAddress) { 375 byte[] address = hostAddress.getAddress(); 376 try { 377 return mService.requestRouteToHostAddress(networkType, address); 378 } catch (RemoteException e) { 379 return false; 380 } 381 } 382 383 /** 384 * Returns the value of the setting for background data usage. If false, 385 * applications should not use the network if the application is not in the 386 * foreground. Developers should respect this setting, and check the value 387 * of this before performing any background data operations. 388 * <p> 389 * All applications that have background services that use the network 390 * should listen to {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}. 391 * 392 * @return Whether background data usage is allowed. 393 */ 394 public boolean getBackgroundDataSetting() { 395 try { 396 return mService.getBackgroundDataSetting(); 397 } catch (RemoteException e) { 398 // Err on the side of safety 399 return false; 400 } 401 } 402 403 /** 404 * Sets the value of the setting for background data usage. 405 * 406 * @param allowBackgroundData Whether an application should use data while 407 * it is in the background. 408 * 409 * @attr ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING 410 * @see #getBackgroundDataSetting() 411 * @hide 412 */ 413 public void setBackgroundDataSetting(boolean allowBackgroundData) { 414 try { 415 mService.setBackgroundDataSetting(allowBackgroundData); 416 } catch (RemoteException e) { 417 } 418 } 419 420 /** 421 * Gets the value of the setting for enabling Mobile data. 422 * 423 * @return Whether mobile data is enabled. 424 * @hide 425 */ 426 public boolean getMobileDataEnabled() { 427 try { 428 return mService.getMobileDataEnabled(); 429 } catch (RemoteException e) { 430 return true; 431 } 432 } 433 434 /** 435 * Sets the persisted value for enabling/disabling Mobile data. 436 * 437 * @param enabled Whether the mobile data connection should be 438 * used or not. 439 * @hide 440 */ 441 public void setMobileDataEnabled(boolean enabled) { 442 try { 443 mService.setMobileDataEnabled(enabled); 444 } catch (RemoteException e) { 445 } 446 } 447 448 /** 449 * Don't allow use of default constructor. 450 */ 451 @SuppressWarnings({"UnusedDeclaration"}) 452 private ConnectivityManager() { 453 } 454 455 /** 456 * {@hide} 457 */ 458 public ConnectivityManager(IConnectivityManager service) { 459 if (service == null) { 460 throw new IllegalArgumentException( 461 "ConnectivityManager() cannot be constructed with null service"); 462 } 463 mService = service; 464 } 465 466 /** 467 * {@hide} 468 */ 469 public String[] getTetherableIfaces() { 470 try { 471 return mService.getTetherableIfaces(); 472 } catch (RemoteException e) { 473 return new String[0]; 474 } 475 } 476 477 /** 478 * {@hide} 479 */ 480 public String[] getTetheredIfaces() { 481 try { 482 return mService.getTetheredIfaces(); 483 } catch (RemoteException e) { 484 return new String[0]; 485 } 486 } 487 488 /** 489 * {@hide} 490 */ 491 public String[] getTetheringErroredIfaces() { 492 try { 493 return mService.getTetheringErroredIfaces(); 494 } catch (RemoteException e) { 495 return new String[0]; 496 } 497 } 498 499 /** 500 * @return error A TETHER_ERROR value indicating success or failure type 501 * {@hide} 502 */ 503 public int tether(String iface) { 504 try { 505 return mService.tether(iface); 506 } catch (RemoteException e) { 507 return TETHER_ERROR_SERVICE_UNAVAIL; 508 } 509 } 510 511 /** 512 * @return error A TETHER_ERROR value indicating success or failure type 513 * {@hide} 514 */ 515 public int untether(String iface) { 516 try { 517 return mService.untether(iface); 518 } catch (RemoteException e) { 519 return TETHER_ERROR_SERVICE_UNAVAIL; 520 } 521 } 522 523 /** 524 * {@hide} 525 */ 526 public boolean isTetheringSupported() { 527 try { 528 return mService.isTetheringSupported(); 529 } catch (RemoteException e) { 530 return false; 531 } 532 } 533 534 /** 535 * {@hide} 536 */ 537 public String[] getTetherableUsbRegexs() { 538 try { 539 return mService.getTetherableUsbRegexs(); 540 } catch (RemoteException e) { 541 return new String[0]; 542 } 543 } 544 545 /** 546 * {@hide} 547 */ 548 public String[] getTetherableWifiRegexs() { 549 try { 550 return mService.getTetherableWifiRegexs(); 551 } catch (RemoteException e) { 552 return new String[0]; 553 } 554 } 555 556 /** 557 * {@hide} 558 */ 559 public String[] getTetherableBluetoothRegexs() { 560 try { 561 return mService.getTetherableBluetoothRegexs(); 562 } catch (RemoteException e) { 563 return new String[0]; 564 } 565 } 566 567 /** {@hide} */ 568 public static final int TETHER_ERROR_NO_ERROR = 0; 569 /** {@hide} */ 570 public static final int TETHER_ERROR_UNKNOWN_IFACE = 1; 571 /** {@hide} */ 572 public static final int TETHER_ERROR_SERVICE_UNAVAIL = 2; 573 /** {@hide} */ 574 public static final int TETHER_ERROR_UNSUPPORTED = 3; 575 /** {@hide} */ 576 public static final int TETHER_ERROR_UNAVAIL_IFACE = 4; 577 /** {@hide} */ 578 public static final int TETHER_ERROR_MASTER_ERROR = 5; 579 /** {@hide} */ 580 public static final int TETHER_ERROR_TETHER_IFACE_ERROR = 6; 581 /** {@hide} */ 582 public static final int TETHER_ERROR_UNTETHER_IFACE_ERROR = 7; 583 /** {@hide} */ 584 public static final int TETHER_ERROR_ENABLE_NAT_ERROR = 8; 585 /** {@hide} */ 586 public static final int TETHER_ERROR_DISABLE_NAT_ERROR = 9; 587 /** {@hide} */ 588 public static final int TETHER_ERROR_IFACE_CFG_ERROR = 10; 589 590 /** 591 * @param iface The name of the interface we're interested in 592 * @return error The error code of the last error tethering or untethering the named 593 * interface 594 * {@hide} 595 */ 596 public int getLastTetherError(String iface) { 597 try { 598 return mService.getLastTetherError(iface); 599 } catch (RemoteException e) { 600 return TETHER_ERROR_SERVICE_UNAVAIL; 601 } 602 } 603 604 /** 605 * Ensure the device stays awake until we connect with the next network 606 * @param forWhome The name of the network going down for logging purposes 607 * @return {@code true} on success, {@code false} on failure 608 * {@hide} 609 */ 610 public boolean requestNetworkTransitionWakelock(String forWhom) { 611 try { 612 mService.requestNetworkTransitionWakelock(forWhom); 613 return true; 614 } catch (RemoteException e) { 615 return false; 616 } 617 } 618 619 /** 620 * @param networkType The type of network you want to report on 621 * @param percentage The quality of the connection 0 is bad, 100 is good 622 * {@hide} 623 */ 624 public void reportInetCondition(int networkType, int percentage) { 625 try { 626 mService.reportInetCondition(networkType, percentage); 627 } catch (RemoteException e) { 628 } 629 } 630 631 /** 632 * @param proxyProperties The definition for the new global http proxy 633 * {@hide} 634 */ 635 public void setGlobalProxy(ProxyProperties p) { 636 try { 637 mService.setGlobalProxy(p); 638 } catch (RemoteException e) { 639 } 640 } 641 642 /** 643 * @return proxyProperties for the current global proxy 644 * {@hide} 645 */ 646 public ProxyProperties getGlobalProxy() { 647 try { 648 return mService.getGlobalProxy(); 649 } catch (RemoteException e) { 650 return null; 651 } 652 } 653 654 /** 655 * @return proxyProperties for the current proxy (global if set, network specific if not) 656 * {@hide} 657 */ 658 public ProxyProperties getProxy() { 659 try { 660 return mService.getProxy(); 661 } catch (RemoteException e) { 662 return null; 663 } 664 } 665} 666