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