ConnectivityManager.java revision 5df69fad6e5021d2862bff0553a510f8d6729fbd
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. 169 */ 170 public static final int TYPE_MOBILE = 0; 171 /** 172 * The Default WIFI data connection. When active, all data traffic 173 * will use this connection by default. 174 */ 175 public static final int TYPE_WIFI = 1; 176 /** 177 * An MMS-specific Mobile data connection. This connection may be the 178 * same as {@link #TYPE_MOBILE} but it may be different. This is used 179 * by applications needing to talk to the carrier's Multimedia Messaging 180 * Service servers. It may coexist with default data connections. 181 */ 182 public static final int TYPE_MOBILE_MMS = 2; 183 /** 184 * A SUPL-specific Mobile data connection. This connection may be the 185 * same as {@link #TYPE_MOBILE} but it may be different. This is used 186 * by applications needing to talk to the carrier's Secure User Plane 187 * Location servers for help locating the device. It may coexist with 188 * default data connections. 189 */ 190 public static final int TYPE_MOBILE_SUPL = 3; 191 /** 192 * A DUN-specific Mobile data connection. This connection may be the 193 * same as {@link #TYPE_MOBILE} but it may be different. This is used 194 * by applicaitons performing a Dial Up Networking bridge so that 195 * the carrier is aware of DUN traffic. It may coexist with default data 196 * connections. 197 */ 198 public static final int TYPE_MOBILE_DUN = 4; 199 /** 200 * A High Priority Mobile data connection. This connection is typically 201 * the same as {@link #TYPE_MOBILE} but the routing setup is different. 202 * Only requesting processes will have access to the Mobile DNS servers 203 * and only IP's explicitly requested via {@link #requestRouteToHost} 204 * will route over this interface if a default route exists. 205 */ 206 public static final int TYPE_MOBILE_HIPRI = 5; 207 /** 208 * The Default WiMAX data connection. When active, all data traffic 209 * will use this connection by default. 210 */ 211 public static final int TYPE_WIMAX = 6; 212 213 /** 214 * The Default Bluetooth data connection. When active, all data traffic 215 * will use this connection by default. 216 */ 217 public static final int TYPE_BLUETOOTH = 7; 218 219 /** {@hide} */ 220 public static final int TYPE_DUMMY = 8; 221 222 /** 223 * The Default Ethernet data connection. When active, all data traffic 224 * will use this connection by default. 225 */ 226 public static final int TYPE_ETHERNET = 9; 227 /** 228 * Over the air Adminstration. 229 * {@hide} 230 */ 231 public static final int TYPE_MOBILE_FOTA = 10; 232 233 /** 234 * IP Multimedia Subsystem 235 * {@hide} 236 */ 237 public static final int TYPE_MOBILE_IMS = 11; 238 239 /** 240 * Carrier Branded Services 241 * {@hide} 242 */ 243 public static final int TYPE_MOBILE_CBS = 12; 244 245 /** {@hide} */ 246 public static final int MAX_RADIO_TYPE = TYPE_MOBILE_CBS; 247 248 /** {@hide} */ 249 public static final int MAX_NETWORK_TYPE = TYPE_MOBILE_CBS; 250 251 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 252 253 private IConnectivityManager mService; 254 255 static public boolean isNetworkTypeValid(int networkType) { 256 return networkType >= 0 && networkType <= MAX_NETWORK_TYPE; 257 } 258 259 public void setNetworkPreference(int preference) { 260 try { 261 mService.setNetworkPreference(preference); 262 } catch (RemoteException e) { 263 } 264 } 265 266 public int getNetworkPreference() { 267 try { 268 return mService.getNetworkPreference(); 269 } catch (RemoteException e) { 270 return -1; 271 } 272 } 273 274 public NetworkInfo getActiveNetworkInfo() { 275 try { 276 return mService.getActiveNetworkInfo(); 277 } catch (RemoteException e) { 278 return null; 279 } 280 } 281 282 public NetworkInfo getNetworkInfo(int networkType) { 283 try { 284 return mService.getNetworkInfo(networkType); 285 } catch (RemoteException e) { 286 return null; 287 } 288 } 289 290 public NetworkInfo[] getAllNetworkInfo() { 291 try { 292 return mService.getAllNetworkInfo(); 293 } catch (RemoteException e) { 294 return null; 295 } 296 } 297 298 /** @hide */ 299 public LinkProperties getActiveLinkProperties() { 300 try { 301 return mService.getActiveLinkProperties(); 302 } catch (RemoteException e) { 303 return null; 304 } 305 } 306 307 /** @hide */ 308 public LinkProperties getLinkProperties(int networkType) { 309 try { 310 return mService.getLinkProperties(networkType); 311 } catch (RemoteException e) { 312 return null; 313 } 314 } 315 316 /** {@hide} */ 317 public boolean setRadios(boolean turnOn) { 318 try { 319 return mService.setRadios(turnOn); 320 } catch (RemoteException e) { 321 return false; 322 } 323 } 324 325 /** {@hide} */ 326 public boolean setRadio(int networkType, boolean turnOn) { 327 try { 328 return mService.setRadio(networkType, turnOn); 329 } catch (RemoteException e) { 330 return false; 331 } 332 } 333 334 /** 335 * Tells the underlying networking system that the caller wants to 336 * begin using the named feature. The interpretation of {@code feature} 337 * is completely up to each networking implementation. 338 * @param networkType specifies which network the request pertains to 339 * @param feature the name of the feature to be used 340 * @return an integer value representing the outcome of the request. 341 * The interpretation of this value is specific to each networking 342 * implementation+feature combination, except that the value {@code -1} 343 * always indicates failure. 344 */ 345 public int startUsingNetworkFeature(int networkType, String feature) { 346 try { 347 return mService.startUsingNetworkFeature(networkType, feature, 348 new Binder()); 349 } catch (RemoteException e) { 350 return -1; 351 } 352 } 353 354 /** 355 * Tells the underlying networking system that the caller is finished 356 * using the named feature. The interpretation of {@code feature} 357 * is completely up to each networking implementation. 358 * @param networkType specifies which network the request pertains to 359 * @param feature the name of the feature that is no longer needed 360 * @return an integer value representing the outcome of the request. 361 * The interpretation of this value is specific to each networking 362 * implementation+feature combination, except that the value {@code -1} 363 * always indicates failure. 364 */ 365 public int stopUsingNetworkFeature(int networkType, String feature) { 366 try { 367 return mService.stopUsingNetworkFeature(networkType, feature); 368 } catch (RemoteException e) { 369 return -1; 370 } 371 } 372 373 /** 374 * Ensure that a network route exists to deliver traffic to the specified 375 * host via the specified network interface. An attempt to add a route that 376 * already exists is ignored, but treated as successful. 377 * @param networkType the type of the network over which traffic to the specified 378 * host is to be routed 379 * @param hostAddress the IP address of the host to which the route is desired 380 * @return {@code true} on success, {@code false} on failure 381 */ 382 public boolean requestRouteToHost(int networkType, int hostAddress) { 383 InetAddress inetAddress = NetworkUtils.intToInetAddress(hostAddress); 384 385 if (inetAddress == null) { 386 return false; 387 } 388 389 return requestRouteToHostAddress(networkType, inetAddress); 390 } 391 392 /** 393 * Ensure that a network route exists to deliver traffic to the specified 394 * host via the specified network interface. An attempt to add a route that 395 * already exists is ignored, but treated as successful. 396 * @param networkType the type of the network over which traffic to the specified 397 * host is to be routed 398 * @param hostAddress the IP address of the host to which the route is desired 399 * @return {@code true} on success, {@code false} on failure 400 * @hide 401 */ 402 public boolean requestRouteToHostAddress(int networkType, InetAddress hostAddress) { 403 byte[] address = hostAddress.getAddress(); 404 try { 405 return mService.requestRouteToHostAddress(networkType, address); 406 } catch (RemoteException e) { 407 return false; 408 } 409 } 410 411 /** 412 * Returns the value of the setting for background data usage. If false, 413 * applications should not use the network if the application is not in the 414 * foreground. Developers should respect this setting, and check the value 415 * of this before performing any background data operations. 416 * <p> 417 * All applications that have background services that use the network 418 * should listen to {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}. 419 * 420 * @return Whether background data usage is allowed. 421 */ 422 public boolean getBackgroundDataSetting() { 423 try { 424 return mService.getBackgroundDataSetting(); 425 } catch (RemoteException e) { 426 // Err on the side of safety 427 return false; 428 } 429 } 430 431 /** 432 * Sets the value of the setting for background data usage. 433 * 434 * @param allowBackgroundData Whether an application should use data while 435 * it is in the background. 436 * 437 * @attr ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING 438 * @see #getBackgroundDataSetting() 439 * @hide 440 */ 441 public void setBackgroundDataSetting(boolean allowBackgroundData) { 442 try { 443 mService.setBackgroundDataSetting(allowBackgroundData); 444 } catch (RemoteException e) { 445 } 446 } 447 448 /** 449 * Gets the value of the setting for enabling Mobile data. 450 * 451 * @return Whether mobile data is enabled. 452 * @hide 453 */ 454 public boolean getMobileDataEnabled() { 455 try { 456 return mService.getMobileDataEnabled(); 457 } catch (RemoteException e) { 458 return true; 459 } 460 } 461 462 /** 463 * Sets the persisted value for enabling/disabling Mobile data. 464 * 465 * @param enabled Whether the mobile data connection should be 466 * used or not. 467 * @hide 468 */ 469 public void setMobileDataEnabled(boolean enabled) { 470 try { 471 mService.setMobileDataEnabled(enabled); 472 } catch (RemoteException e) { 473 } 474 } 475 476 /** 477 * Don't allow use of default constructor. 478 */ 479 @SuppressWarnings({"UnusedDeclaration"}) 480 private ConnectivityManager() { 481 } 482 483 /** 484 * {@hide} 485 */ 486 public ConnectivityManager(IConnectivityManager service) { 487 if (service == null) { 488 throw new IllegalArgumentException( 489 "ConnectivityManager() cannot be constructed with null service"); 490 } 491 mService = service; 492 } 493 494 /** 495 * {@hide} 496 */ 497 public String[] getTetherableIfaces() { 498 try { 499 return mService.getTetherableIfaces(); 500 } catch (RemoteException e) { 501 return new String[0]; 502 } 503 } 504 505 /** 506 * {@hide} 507 */ 508 public String[] getTetheredIfaces() { 509 try { 510 return mService.getTetheredIfaces(); 511 } catch (RemoteException e) { 512 return new String[0]; 513 } 514 } 515 516 /** 517 * {@hide} 518 */ 519 public String[] getTetheringErroredIfaces() { 520 try { 521 return mService.getTetheringErroredIfaces(); 522 } catch (RemoteException e) { 523 return new String[0]; 524 } 525 } 526 527 /** 528 * @return error A TETHER_ERROR value indicating success or failure type 529 * {@hide} 530 */ 531 public int tether(String iface) { 532 try { 533 return mService.tether(iface); 534 } catch (RemoteException e) { 535 return TETHER_ERROR_SERVICE_UNAVAIL; 536 } 537 } 538 539 /** 540 * @return error A TETHER_ERROR value indicating success or failure type 541 * {@hide} 542 */ 543 public int untether(String iface) { 544 try { 545 return mService.untether(iface); 546 } catch (RemoteException e) { 547 return TETHER_ERROR_SERVICE_UNAVAIL; 548 } 549 } 550 551 /** 552 * {@hide} 553 */ 554 public boolean isTetheringSupported() { 555 try { 556 return mService.isTetheringSupported(); 557 } catch (RemoteException e) { 558 return false; 559 } 560 } 561 562 /** 563 * {@hide} 564 */ 565 public String[] getTetherableUsbRegexs() { 566 try { 567 return mService.getTetherableUsbRegexs(); 568 } catch (RemoteException e) { 569 return new String[0]; 570 } 571 } 572 573 /** 574 * {@hide} 575 */ 576 public String[] getTetherableWifiRegexs() { 577 try { 578 return mService.getTetherableWifiRegexs(); 579 } catch (RemoteException e) { 580 return new String[0]; 581 } 582 } 583 584 /** 585 * {@hide} 586 */ 587 public String[] getTetherableBluetoothRegexs() { 588 try { 589 return mService.getTetherableBluetoothRegexs(); 590 } catch (RemoteException e) { 591 return new String[0]; 592 } 593 } 594 595 /** {@hide} */ 596 public static final int TETHER_ERROR_NO_ERROR = 0; 597 /** {@hide} */ 598 public static final int TETHER_ERROR_UNKNOWN_IFACE = 1; 599 /** {@hide} */ 600 public static final int TETHER_ERROR_SERVICE_UNAVAIL = 2; 601 /** {@hide} */ 602 public static final int TETHER_ERROR_UNSUPPORTED = 3; 603 /** {@hide} */ 604 public static final int TETHER_ERROR_UNAVAIL_IFACE = 4; 605 /** {@hide} */ 606 public static final int TETHER_ERROR_MASTER_ERROR = 5; 607 /** {@hide} */ 608 public static final int TETHER_ERROR_TETHER_IFACE_ERROR = 6; 609 /** {@hide} */ 610 public static final int TETHER_ERROR_UNTETHER_IFACE_ERROR = 7; 611 /** {@hide} */ 612 public static final int TETHER_ERROR_ENABLE_NAT_ERROR = 8; 613 /** {@hide} */ 614 public static final int TETHER_ERROR_DISABLE_NAT_ERROR = 9; 615 /** {@hide} */ 616 public static final int TETHER_ERROR_IFACE_CFG_ERROR = 10; 617 618 /** 619 * @param iface The name of the interface we're interested in 620 * @return error The error code of the last error tethering or untethering the named 621 * interface 622 * {@hide} 623 */ 624 public int getLastTetherError(String iface) { 625 try { 626 return mService.getLastTetherError(iface); 627 } catch (RemoteException e) { 628 return TETHER_ERROR_SERVICE_UNAVAIL; 629 } 630 } 631 632 /** 633 * Ensure the device stays awake until we connect with the next network 634 * @param forWhome The name of the network going down for logging purposes 635 * @return {@code true} on success, {@code false} on failure 636 * {@hide} 637 */ 638 public boolean requestNetworkTransitionWakelock(String forWhom) { 639 try { 640 mService.requestNetworkTransitionWakelock(forWhom); 641 return true; 642 } catch (RemoteException e) { 643 return false; 644 } 645 } 646 647 /** 648 * @param networkType The type of network you want to report on 649 * @param percentage The quality of the connection 0 is bad, 100 is good 650 * {@hide} 651 */ 652 public void reportInetCondition(int networkType, int percentage) { 653 try { 654 mService.reportInetCondition(networkType, percentage); 655 } catch (RemoteException e) { 656 } 657 } 658 659 /** 660 * @param proxyProperties The definition for the new global http proxy 661 * {@hide} 662 */ 663 public void setGlobalProxy(ProxyProperties p) { 664 try { 665 mService.setGlobalProxy(p); 666 } catch (RemoteException e) { 667 } 668 } 669 670 /** 671 * @return proxyProperties for the current global proxy 672 * {@hide} 673 */ 674 public ProxyProperties getGlobalProxy() { 675 try { 676 return mService.getGlobalProxy(); 677 } catch (RemoteException e) { 678 return null; 679 } 680 } 681 682 /** 683 * @return proxyProperties for the current proxy (global if set, network specific if not) 684 * {@hide} 685 */ 686 public ProxyProperties getProxy() { 687 try { 688 return mService.getProxy(); 689 } catch (RemoteException e) { 690 return null; 691 } 692 } 693 694 /** 695 * @param networkType The network who's dependence has changed 696 * @param met Boolean - true if network use is ok, false if not 697 * {@hide} 698 */ 699 public void setDataDependency(int networkType, boolean met) { 700 try { 701 mService.setDataDependency(networkType, met); 702 } catch (RemoteException e) { 703 } 704 } 705} 706