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 static com.android.internal.util.Preconditions.checkNotNull; 20 21 import android.annotation.SdkConstant; 22 import android.annotation.SdkConstant.SdkConstantType; 23 import android.content.Context; 24 import android.os.Binder; 25 import android.os.Build.VERSION_CODES; 26 import android.os.Messenger; 27 import android.os.RemoteException; 28 import android.os.ResultReceiver; 29 import android.provider.Settings; 30 31 import java.net.InetAddress; 32 33 /** 34 * Class that answers queries about the state of network connectivity. It also 35 * notifies applications when network connectivity changes. Get an instance 36 * of this class by calling 37 * {@link android.content.Context#getSystemService(String) Context.getSystemService(Context.CONNECTIVITY_SERVICE)}. 38 * <p> 39 * The primary responsibilities of this class are to: 40 * <ol> 41 * <li>Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)</li> 42 * <li>Send broadcast intents when network connectivity changes</li> 43 * <li>Attempt to "fail over" to another network when connectivity to a network 44 * is lost</li> 45 * <li>Provide an API that allows applications to query the coarse-grained or fine-grained 46 * state of the available networks</li> 47 * </ol> 48 */ 49 public class ConnectivityManager { 50 private static final String TAG = "ConnectivityManager"; 51 52 /** 53 * A change in network connectivity has occurred. A connection has either 54 * been established or lost. The NetworkInfo for the affected network is 55 * sent as an extra; it should be consulted to see what kind of 56 * connectivity event occurred. 57 * <p/> 58 * If this is a connection that was the result of failing over from a 59 * disconnected network, then the FAILOVER_CONNECTION boolean extra is 60 * set to true. 61 * <p/> 62 * For a loss of connectivity, if the connectivity manager is attempting 63 * to connect (or has already connected) to another network, the 64 * NetworkInfo for the new network is also passed as an extra. This lets 65 * any receivers of the broadcast know that they should not necessarily 66 * tell the user that no data traffic will be possible. Instead, the 67 * receiver should expect another broadcast soon, indicating either that 68 * the failover attempt succeeded (and so there is still overall data 69 * connectivity), or that the failover attempt failed, meaning that all 70 * connectivity has been lost. 71 * <p/> 72 * For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY 73 * is set to {@code true} if there are no connected networks at all. 74 */ 75 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 76 public static final String CONNECTIVITY_ACTION = "android.net.conn.CONNECTIVITY_CHANGE"; 77 78 /** 79 * Identical to {@link #CONNECTIVITY_ACTION} broadcast, but sent without any 80 * applicable {@link Settings.Secure#CONNECTIVITY_CHANGE_DELAY}. 81 * 82 * @hide 83 */ 84 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 85 public static final String CONNECTIVITY_ACTION_IMMEDIATE = 86 "android.net.conn.CONNECTIVITY_CHANGE_IMMEDIATE"; 87 88 /** 89 * The lookup key for a {@link NetworkInfo} object. Retrieve with 90 * {@link android.content.Intent#getParcelableExtra(String)}. 91 * 92 * @deprecated Since {@link NetworkInfo} can vary based on UID, applications 93 * should always obtain network information through 94 * {@link #getActiveNetworkInfo()} or 95 * {@link #getAllNetworkInfo()}. 96 * @see #EXTRA_NETWORK_TYPE 97 */ 98 @Deprecated 99 public static final String EXTRA_NETWORK_INFO = "networkInfo"; 100 101 /** 102 * Network type which triggered a {@link #CONNECTIVITY_ACTION} broadcast. 103 * Can be used with {@link #getNetworkInfo(int)} to get {@link NetworkInfo} 104 * state based on the calling application. 105 * 106 * @see android.content.Intent#getIntExtra(String, int) 107 */ 108 public static final String EXTRA_NETWORK_TYPE = "networkType"; 109 110 /** 111 * The lookup key for a boolean that indicates whether a connect event 112 * is for a network to which the connectivity manager was failing over 113 * following a disconnect on another network. 114 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 115 */ 116 public static final String EXTRA_IS_FAILOVER = "isFailover"; 117 /** 118 * The lookup key for a {@link NetworkInfo} object. This is supplied when 119 * there is another network that it may be possible to connect to. Retrieve with 120 * {@link android.content.Intent#getParcelableExtra(String)}. 121 */ 122 public static final String EXTRA_OTHER_NETWORK_INFO = "otherNetwork"; 123 /** 124 * The lookup key for a boolean that indicates whether there is a 125 * complete lack of connectivity, i.e., no network is available. 126 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 127 */ 128 public static final String EXTRA_NO_CONNECTIVITY = "noConnectivity"; 129 /** 130 * The lookup key for a string that indicates why an attempt to connect 131 * to a network failed. The string has no particular structure. It is 132 * intended to be used in notifications presented to users. Retrieve 133 * it with {@link android.content.Intent#getStringExtra(String)}. 134 */ 135 public static final String EXTRA_REASON = "reason"; 136 /** 137 * The lookup key for a string that provides optionally supplied 138 * extra information about the network state. The information 139 * may be passed up from the lower networking layers, and its 140 * meaning may be specific to a particular network type. Retrieve 141 * it with {@link android.content.Intent#getStringExtra(String)}. 142 */ 143 public static final String EXTRA_EXTRA_INFO = "extraInfo"; 144 /** 145 * The lookup key for an int that provides information about 146 * our connection to the internet at large. 0 indicates no connection, 147 * 100 indicates a great connection. Retrieve it with 148 * {@link android.content.Intent#getIntExtra(String, int)}. 149 * {@hide} 150 */ 151 public static final String EXTRA_INET_CONDITION = "inetCondition"; 152 153 /** 154 * Broadcast action to indicate the change of data activity status 155 * (idle or active) on a network in a recent period. 156 * The network becomes active when data transmission is started, or 157 * idle if there is no data transmission for a period of time. 158 * {@hide} 159 */ 160 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 161 public static final String ACTION_DATA_ACTIVITY_CHANGE = "android.net.conn.DATA_ACTIVITY_CHANGE"; 162 /** 163 * The lookup key for an enum that indicates the network device type on which this data activity 164 * change happens. 165 * {@hide} 166 */ 167 public static final String EXTRA_DEVICE_TYPE = "deviceType"; 168 /** 169 * The lookup key for a boolean that indicates the device is active or not. {@code true} means 170 * it is actively sending or receiving data and {@code false} means it is idle. 171 * {@hide} 172 */ 173 public static final String EXTRA_IS_ACTIVE = "isActive"; 174 175 /** 176 * Broadcast Action: The setting for background data usage has changed 177 * values. Use {@link #getBackgroundDataSetting()} to get the current value. 178 * <p> 179 * If an application uses the network in the background, it should listen 180 * for this broadcast and stop using the background data if the value is 181 * {@code false}. 182 * <p> 183 * 184 * @deprecated As of {@link VERSION_CODES#ICE_CREAM_SANDWICH}, availability 185 * of background data depends on several combined factors, and 186 * this broadcast is no longer sent. Instead, when background 187 * data is unavailable, {@link #getActiveNetworkInfo()} will now 188 * appear disconnected. During first boot after a platform 189 * upgrade, this broadcast will be sent once if 190 * {@link #getBackgroundDataSetting()} was {@code false} before 191 * the upgrade. 192 */ 193 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 194 @Deprecated 195 public static final String ACTION_BACKGROUND_DATA_SETTING_CHANGED = 196 "android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"; 197 198 /** 199 * Broadcast Action: The network connection may not be good 200 * uses {@code ConnectivityManager.EXTRA_INET_CONDITION} and 201 * {@code ConnectivityManager.EXTRA_NETWORK_INFO} to specify 202 * the network and it's condition. 203 * @hide 204 */ 205 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 206 public static final String INET_CONDITION_ACTION = 207 "android.net.conn.INET_CONDITION_ACTION"; 208 209 /** 210 * Broadcast Action: A tetherable connection has come or gone. 211 * Uses {@code ConnectivityManager.EXTRA_AVAILABLE_TETHER}, 212 * {@code ConnectivityManager.EXTRA_ACTIVE_TETHER} and 213 * {@code ConnectivityManager.EXTRA_ERRORED_TETHER} to indicate 214 * the current state of tethering. Each include a list of 215 * interface names in that state (may be empty). 216 * @hide 217 */ 218 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 219 public static final String ACTION_TETHER_STATE_CHANGED = 220 "android.net.conn.TETHER_STATE_CHANGED"; 221 222 /** 223 * @hide 224 * gives a String[] listing all the interfaces configured for 225 * tethering and currently available for tethering. 226 */ 227 public static final String EXTRA_AVAILABLE_TETHER = "availableArray"; 228 229 /** 230 * @hide 231 * gives a String[] listing all the interfaces currently tethered 232 * (ie, has dhcp support and packets potentially forwarded/NATed) 233 */ 234 public static final String EXTRA_ACTIVE_TETHER = "activeArray"; 235 236 /** 237 * @hide 238 * gives a String[] listing all the interfaces we tried to tether and 239 * failed. Use {@link #getLastTetherError} to find the error code 240 * for any interfaces listed here. 241 */ 242 public static final String EXTRA_ERRORED_TETHER = "erroredArray"; 243 244 /** 245 * Broadcast Action: The captive portal tracker has finished its test. 246 * Sent only while running Setup Wizard, in lieu of showing a user 247 * notification. 248 * @hide 249 */ 250 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 251 public static final String ACTION_CAPTIVE_PORTAL_TEST_COMPLETED = 252 "android.net.conn.CAPTIVE_PORTAL_TEST_COMPLETED"; 253 /** 254 * The lookup key for a boolean that indicates whether a captive portal was detected. 255 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 256 * @hide 257 */ 258 public static final String EXTRA_IS_CAPTIVE_PORTAL = "captivePortal"; 259 260 /** 261 * The absence of a connection type. 262 * @hide 263 */ 264 public static final int TYPE_NONE = -1; 265 266 /** 267 * The Mobile data connection. When active, all data traffic 268 * will use this network type's interface by default 269 * (it has a default route) 270 */ 271 public static final int TYPE_MOBILE = 0; 272 /** 273 * The WIFI data connection. When active, all data traffic 274 * will use this network type's interface by default 275 * (it has a default route). 276 */ 277 public static final int TYPE_WIFI = 1; 278 /** 279 * An MMS-specific Mobile data connection. This network type may use the 280 * same network interface as {@link #TYPE_MOBILE} or it may use a different 281 * one. This is used by applications needing to talk to the carrier's 282 * Multimedia Messaging Service servers. 283 */ 284 public static final int TYPE_MOBILE_MMS = 2; 285 /** 286 * A SUPL-specific Mobile data connection. This network type may use the 287 * same network interface as {@link #TYPE_MOBILE} or it may use a different 288 * one. This is used by applications needing to talk to the carrier's 289 * Secure User Plane Location servers for help locating the device. 290 */ 291 public static final int TYPE_MOBILE_SUPL = 3; 292 /** 293 * A DUN-specific Mobile data connection. This network type may use the 294 * same network interface as {@link #TYPE_MOBILE} or it may use a different 295 * one. This is sometimes by the system when setting up an upstream connection 296 * for tethering so that the carrier is aware of DUN traffic. 297 */ 298 public static final int TYPE_MOBILE_DUN = 4; 299 /** 300 * A High Priority Mobile data connection. This network type uses the 301 * same network interface as {@link #TYPE_MOBILE} but the routing setup 302 * is different. Only requesting processes will have access to the 303 * Mobile DNS servers and only IP's explicitly requested via {@link #requestRouteToHost} 304 * will route over this interface if no default route exists. 305 */ 306 public static final int TYPE_MOBILE_HIPRI = 5; 307 /** 308 * The WiMAX data connection. When active, all data traffic 309 * will use this network type's interface by default 310 * (it has a default route). 311 */ 312 public static final int TYPE_WIMAX = 6; 313 314 /** 315 * The Bluetooth data connection. When active, all data traffic 316 * will use this network type's interface by default 317 * (it has a default route). 318 */ 319 public static final int TYPE_BLUETOOTH = 7; 320 321 /** 322 * Dummy data connection. This should not be used on shipping devices. 323 */ 324 public static final int TYPE_DUMMY = 8; 325 326 /** 327 * The Ethernet data connection. When active, all data traffic 328 * will use this network type's interface by default 329 * (it has a default route). 330 */ 331 public static final int TYPE_ETHERNET = 9; 332 333 /** 334 * Over the air Administration. 335 * {@hide} 336 */ 337 public static final int TYPE_MOBILE_FOTA = 10; 338 339 /** 340 * IP Multimedia Subsystem. 341 * {@hide} 342 */ 343 public static final int TYPE_MOBILE_IMS = 11; 344 345 /** 346 * Carrier Branded Services. 347 * {@hide} 348 */ 349 public static final int TYPE_MOBILE_CBS = 12; 350 351 /** 352 * A Wi-Fi p2p connection. Only requesting processes will have access to 353 * the peers connected. 354 * {@hide} 355 */ 356 public static final int TYPE_WIFI_P2P = 13; 357 358 /** {@hide} */ 359 public static final int MAX_RADIO_TYPE = TYPE_WIFI_P2P; 360 361 /** {@hide} */ 362 public static final int MAX_NETWORK_TYPE = TYPE_WIFI_P2P; 363 364 /** 365 * If you want to set the default network preference,you can directly 366 * change the networkAttributes array in framework's config.xml. 367 * 368 * @deprecated Since we support so many more networks now, the single 369 * network default network preference can't really express 370 * the hierarchy. Instead, the default is defined by the 371 * networkAttributes in config.xml. You can determine 372 * the current value by calling {@link #getNetworkPreference()} 373 * from an App. 374 */ 375 @Deprecated 376 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 377 378 /** 379 * Default value for {@link Settings.Global#CONNECTIVITY_CHANGE_DELAY} in 380 * milliseconds. This was introduced because IPv6 routes seem to take a 381 * moment to settle - trying network activity before the routes are adjusted 382 * can lead to packets using the wrong interface or having the wrong IP address. 383 * This delay is a bit crude, but in the future hopefully we will have kernel 384 * notifications letting us know when it's safe to use the new network. 385 * 386 * @hide 387 */ 388 public static final int CONNECTIVITY_CHANGE_DELAY_DEFAULT = 3000; 389 390 private final IConnectivityManager mService; 391 392 /** 393 * Tests if a given integer represents a valid network type. 394 * @param networkType the type to be tested 395 * @return a boolean. {@code true} if the type is valid, else {@code false} 396 */ 397 public static boolean isNetworkTypeValid(int networkType) { 398 return networkType >= 0 && networkType <= MAX_NETWORK_TYPE; 399 } 400 401 /** 402 * Returns a non-localized string representing a given network type. 403 * ONLY used for debugging output. 404 * @param type the type needing naming 405 * @return a String for the given type, or a string version of the type ("87") 406 * if no name is known. 407 * {@hide} 408 */ 409 public static String getNetworkTypeName(int type) { 410 switch (type) { 411 case TYPE_MOBILE: 412 return "MOBILE"; 413 case TYPE_WIFI: 414 return "WIFI"; 415 case TYPE_MOBILE_MMS: 416 return "MOBILE_MMS"; 417 case TYPE_MOBILE_SUPL: 418 return "MOBILE_SUPL"; 419 case TYPE_MOBILE_DUN: 420 return "MOBILE_DUN"; 421 case TYPE_MOBILE_HIPRI: 422 return "MOBILE_HIPRI"; 423 case TYPE_WIMAX: 424 return "WIMAX"; 425 case TYPE_BLUETOOTH: 426 return "BLUETOOTH"; 427 case TYPE_DUMMY: 428 return "DUMMY"; 429 case TYPE_ETHERNET: 430 return "ETHERNET"; 431 case TYPE_MOBILE_FOTA: 432 return "MOBILE_FOTA"; 433 case TYPE_MOBILE_IMS: 434 return "MOBILE_IMS"; 435 case TYPE_MOBILE_CBS: 436 return "MOBILE_CBS"; 437 case TYPE_WIFI_P2P: 438 return "WIFI_P2P"; 439 default: 440 return Integer.toString(type); 441 } 442 } 443 444 /** 445 * Checks if a given type uses the cellular data connection. 446 * This should be replaced in the future by a network property. 447 * @param networkType the type to check 448 * @return a boolean - {@code true} if uses cellular network, else {@code false} 449 * {@hide} 450 */ 451 public static boolean isNetworkTypeMobile(int networkType) { 452 switch (networkType) { 453 case TYPE_MOBILE: 454 case TYPE_MOBILE_MMS: 455 case TYPE_MOBILE_SUPL: 456 case TYPE_MOBILE_DUN: 457 case TYPE_MOBILE_HIPRI: 458 case TYPE_MOBILE_FOTA: 459 case TYPE_MOBILE_IMS: 460 case TYPE_MOBILE_CBS: 461 return true; 462 default: 463 return false; 464 } 465 } 466 467 /** 468 * Specifies the preferred network type. When the device has more 469 * than one type available the preferred network type will be used. 470 * Note that this made sense when we only had 2 network types, 471 * but with more and more default networks we need an array to list 472 * their ordering. This will be deprecated soon. 473 * 474 * @param preference the network type to prefer over all others. It is 475 * unspecified what happens to the old preferred network in the 476 * overall ordering. 477 */ 478 public void setNetworkPreference(int preference) { 479 try { 480 mService.setNetworkPreference(preference); 481 } catch (RemoteException e) { 482 } 483 } 484 485 /** 486 * Retrieves the current preferred network type. 487 * Note that this made sense when we only had 2 network types, 488 * but with more and more default networks we need an array to list 489 * their ordering. This will be deprecated soon. 490 * 491 * @return an integer representing the preferred network type 492 * 493 * <p>This method requires the caller to hold the permission 494 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 495 */ 496 public int getNetworkPreference() { 497 try { 498 return mService.getNetworkPreference(); 499 } catch (RemoteException e) { 500 return -1; 501 } 502 } 503 504 /** 505 * Returns details about the currently active default data network. When 506 * connected, this network is the default route for outgoing connections. 507 * You should always check {@link NetworkInfo#isConnected()} before initiating 508 * network traffic. This may return {@code null} when there is no default 509 * network. 510 * 511 * @return a {@link NetworkInfo} object for the current default network 512 * or {@code null} if no network default network is currently active 513 * 514 * <p>This method requires the call to hold the permission 515 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 516 */ 517 public NetworkInfo getActiveNetworkInfo() { 518 try { 519 return mService.getActiveNetworkInfo(); 520 } catch (RemoteException e) { 521 return null; 522 } 523 } 524 525 /** 526 * Returns details about the currently active default data network 527 * for a given uid. This is for internal use only to avoid spying 528 * other apps. 529 * 530 * @return a {@link NetworkInfo} object for the current default network 531 * for the given uid or {@code null} if no default network is 532 * available for the specified uid. 533 * 534 * <p>This method requires the caller to hold the permission 535 * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL} 536 * {@hide} 537 */ 538 public NetworkInfo getActiveNetworkInfoForUid(int uid) { 539 try { 540 return mService.getActiveNetworkInfoForUid(uid); 541 } catch (RemoteException e) { 542 return null; 543 } 544 } 545 546 /** 547 * Returns connection status information about a particular 548 * network type. 549 * 550 * @param networkType integer specifying which networkType in 551 * which you're interested. 552 * @return a {@link NetworkInfo} object for the requested 553 * network type or {@code null} if the type is not 554 * supported by the device. 555 * 556 * <p>This method requires the call to hold the permission 557 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 558 */ 559 public NetworkInfo getNetworkInfo(int networkType) { 560 try { 561 return mService.getNetworkInfo(networkType); 562 } catch (RemoteException e) { 563 return null; 564 } 565 } 566 567 /** 568 * Returns connection status information about all network 569 * types supported by the device. 570 * 571 * @return an array of {@link NetworkInfo} objects. Check each 572 * {@link NetworkInfo#getType} for which type each applies. 573 * 574 * <p>This method requires the call to hold the permission 575 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 576 */ 577 public NetworkInfo[] getAllNetworkInfo() { 578 try { 579 return mService.getAllNetworkInfo(); 580 } catch (RemoteException e) { 581 return null; 582 } 583 } 584 585 /** 586 * Returns the IP information for the current default network. 587 * 588 * @return a {@link LinkProperties} object describing the IP info 589 * for the current default network, or {@code null} if there 590 * is no current default network. 591 * 592 * <p>This method requires the call to hold the permission 593 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 594 * {@hide} 595 */ 596 public LinkProperties getActiveLinkProperties() { 597 try { 598 return mService.getActiveLinkProperties(); 599 } catch (RemoteException e) { 600 return null; 601 } 602 } 603 604 /** 605 * Returns the IP information for a given network type. 606 * 607 * @param networkType the network type of interest. 608 * @return a {@link LinkProperties} object describing the IP info 609 * for the given networkType, or {@code null} if there is 610 * no current default network. 611 * 612 * <p>This method requires the call to hold the permission 613 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 614 * {@hide} 615 */ 616 public LinkProperties getLinkProperties(int networkType) { 617 try { 618 return mService.getLinkProperties(networkType); 619 } catch (RemoteException e) { 620 return null; 621 } 622 } 623 624 /** 625 * Tells each network type to set its radio power state as directed. 626 * 627 * @param turnOn a boolean, {@code true} to turn the radios on, 628 * {@code false} to turn them off. 629 * @return a boolean, {@code true} indicating success. All network types 630 * will be tried, even if some fail. 631 * 632 * <p>This method requires the call to hold the permission 633 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 634 * {@hide} 635 */ 636 public boolean setRadios(boolean turnOn) { 637 try { 638 return mService.setRadios(turnOn); 639 } catch (RemoteException e) { 640 return false; 641 } 642 } 643 644 /** 645 * Tells a given networkType to set its radio power state as directed. 646 * 647 * @param networkType the int networkType of interest. 648 * @param turnOn a boolean, {@code true} to turn the radio on, 649 * {@code} false to turn it off. 650 * @return a boolean, {@code true} indicating success. 651 * 652 * <p>This method requires the call to hold the permission 653 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 654 * {@hide} 655 */ 656 public boolean setRadio(int networkType, boolean turnOn) { 657 try { 658 return mService.setRadio(networkType, turnOn); 659 } catch (RemoteException e) { 660 return false; 661 } 662 } 663 664 /** 665 * Tells the underlying networking system that the caller wants to 666 * begin using the named feature. The interpretation of {@code feature} 667 * is completely up to each networking implementation. 668 * <p>This method requires the caller to hold the permission 669 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 670 * @param networkType specifies which network the request pertains to 671 * @param feature the name of the feature to be used 672 * @return an integer value representing the outcome of the request. 673 * The interpretation of this value is specific to each networking 674 * implementation+feature combination, except that the value {@code -1} 675 * always indicates failure. 676 */ 677 public int startUsingNetworkFeature(int networkType, String feature) { 678 try { 679 return mService.startUsingNetworkFeature(networkType, feature, 680 new Binder()); 681 } catch (RemoteException e) { 682 return -1; 683 } 684 } 685 686 /** 687 * Tells the underlying networking system that the caller is finished 688 * using the named feature. The interpretation of {@code feature} 689 * is completely up to each networking implementation. 690 * <p>This method requires the caller to hold the permission 691 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 692 * @param networkType specifies which network the request pertains to 693 * @param feature the name of the feature that is no longer needed 694 * @return an integer value representing the outcome of the request. 695 * The interpretation of this value is specific to each networking 696 * implementation+feature combination, except that the value {@code -1} 697 * always indicates failure. 698 */ 699 public int stopUsingNetworkFeature(int networkType, String feature) { 700 try { 701 return mService.stopUsingNetworkFeature(networkType, feature); 702 } catch (RemoteException e) { 703 return -1; 704 } 705 } 706 707 /** 708 * Ensure that a network route exists to deliver traffic to the specified 709 * host via the specified network interface. An attempt to add a route that 710 * already exists is ignored, but treated as successful. 711 * <p>This method requires the caller to hold the permission 712 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 713 * @param networkType the type of the network over which traffic to the specified 714 * host is to be routed 715 * @param hostAddress the IP address of the host to which the route is desired 716 * @return {@code true} on success, {@code false} on failure 717 */ 718 public boolean requestRouteToHost(int networkType, int hostAddress) { 719 InetAddress inetAddress = NetworkUtils.intToInetAddress(hostAddress); 720 721 if (inetAddress == null) { 722 return false; 723 } 724 725 return requestRouteToHostAddress(networkType, inetAddress); 726 } 727 728 /** 729 * Ensure that a network route exists to deliver traffic to the specified 730 * host via the specified network interface. An attempt to add a route that 731 * already exists is ignored, but treated as successful. 732 * @param networkType the type of the network over which traffic to the specified 733 * host is to be routed 734 * @param hostAddress the IP address of the host to which the route is desired 735 * @return {@code true} on success, {@code false} on failure 736 * @hide 737 */ 738 public boolean requestRouteToHostAddress(int networkType, InetAddress hostAddress) { 739 byte[] address = hostAddress.getAddress(); 740 try { 741 return mService.requestRouteToHostAddress(networkType, address); 742 } catch (RemoteException e) { 743 return false; 744 } 745 } 746 747 /** 748 * Returns the value of the setting for background data usage. If false, 749 * applications should not use the network if the application is not in the 750 * foreground. Developers should respect this setting, and check the value 751 * of this before performing any background data operations. 752 * <p> 753 * All applications that have background services that use the network 754 * should listen to {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}. 755 * <p> 756 * @deprecated As of {@link VERSION_CODES#ICE_CREAM_SANDWICH}, availability of 757 * background data depends on several combined factors, and this method will 758 * always return {@code true}. Instead, when background data is unavailable, 759 * {@link #getActiveNetworkInfo()} will now appear disconnected. 760 * 761 * @return Whether background data usage is allowed. 762 */ 763 @Deprecated 764 public boolean getBackgroundDataSetting() { 765 // assume that background data is allowed; final authority is 766 // NetworkInfo which may be blocked. 767 return true; 768 } 769 770 /** 771 * Sets the value of the setting for background data usage. 772 * 773 * @param allowBackgroundData Whether an application should use data while 774 * it is in the background. 775 * 776 * @attr ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING 777 * @see #getBackgroundDataSetting() 778 * @hide 779 */ 780 @Deprecated 781 public void setBackgroundDataSetting(boolean allowBackgroundData) { 782 // ignored 783 } 784 785 /** 786 * Return quota status for the current active network, or {@code null} if no 787 * network is active. Quota status can change rapidly, so these values 788 * shouldn't be cached. 789 * 790 * <p>This method requires the call to hold the permission 791 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 792 * 793 * @hide 794 */ 795 public NetworkQuotaInfo getActiveNetworkQuotaInfo() { 796 try { 797 return mService.getActiveNetworkQuotaInfo(); 798 } catch (RemoteException e) { 799 return null; 800 } 801 } 802 803 /** 804 * Gets the value of the setting for enabling Mobile data. 805 * 806 * @return Whether mobile data is enabled. 807 * 808 * <p>This method requires the call to hold the permission 809 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 810 * @hide 811 */ 812 public boolean getMobileDataEnabled() { 813 try { 814 return mService.getMobileDataEnabled(); 815 } catch (RemoteException e) { 816 return true; 817 } 818 } 819 820 /** 821 * Sets the persisted value for enabling/disabling Mobile data. 822 * 823 * @param enabled Whether the user wants the mobile data connection used 824 * or not. 825 * @hide 826 */ 827 public void setMobileDataEnabled(boolean enabled) { 828 try { 829 mService.setMobileDataEnabled(enabled); 830 } catch (RemoteException e) { 831 } 832 } 833 834 /** 835 * {@hide} 836 */ 837 public ConnectivityManager(IConnectivityManager service) { 838 mService = checkNotNull(service, "missing IConnectivityManager"); 839 } 840 841 /** {@hide} */ 842 public static ConnectivityManager from(Context context) { 843 return (ConnectivityManager) context.getSystemService(Context.CONNECTIVITY_SERVICE); 844 } 845 846 /** 847 * Get the set of tetherable, available interfaces. This list is limited by 848 * device configuration and current interface existence. 849 * 850 * @return an array of 0 or more Strings of tetherable interface names. 851 * 852 * <p>This method requires the call to hold the permission 853 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 854 * {@hide} 855 */ 856 public String[] getTetherableIfaces() { 857 try { 858 return mService.getTetherableIfaces(); 859 } catch (RemoteException e) { 860 return new String[0]; 861 } 862 } 863 864 /** 865 * Get the set of tethered interfaces. 866 * 867 * @return an array of 0 or more String of currently tethered interface names. 868 * 869 * <p>This method requires the call to hold the permission 870 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 871 * {@hide} 872 */ 873 public String[] getTetheredIfaces() { 874 try { 875 return mService.getTetheredIfaces(); 876 } catch (RemoteException e) { 877 return new String[0]; 878 } 879 } 880 881 /** 882 * Get the set of interface names which attempted to tether but 883 * failed. Re-attempting to tether may cause them to reset to the Tethered 884 * state. Alternatively, causing the interface to be destroyed and recreated 885 * may cause them to reset to the available state. 886 * {@link ConnectivityManager#getLastTetherError} can be used to get more 887 * information on the cause of the errors. 888 * 889 * @return an array of 0 or more String indicating the interface names 890 * which failed to tether. 891 * 892 * <p>This method requires the call to hold the permission 893 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 894 * {@hide} 895 */ 896 public String[] getTetheringErroredIfaces() { 897 try { 898 return mService.getTetheringErroredIfaces(); 899 } catch (RemoteException e) { 900 return new String[0]; 901 } 902 } 903 904 /** 905 * Attempt to tether the named interface. This will setup a dhcp server 906 * on the interface, forward and NAT IP packets and forward DNS requests 907 * to the best active upstream network interface. Note that if no upstream 908 * IP network interface is available, dhcp will still run and traffic will be 909 * allowed between the tethered devices and this device, though upstream net 910 * access will of course fail until an upstream network interface becomes 911 * active. 912 * 913 * @param iface the interface name to tether. 914 * @return error a {@code TETHER_ERROR} value indicating success or failure type 915 * 916 * <p>This method requires the call to hold the permission 917 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 918 * {@hide} 919 */ 920 public int tether(String iface) { 921 try { 922 return mService.tether(iface); 923 } catch (RemoteException e) { 924 return TETHER_ERROR_SERVICE_UNAVAIL; 925 } 926 } 927 928 /** 929 * Stop tethering the named interface. 930 * 931 * @param iface the interface name to untether. 932 * @return error a {@code TETHER_ERROR} value indicating success or failure type 933 * 934 * <p>This method requires the call to hold the permission 935 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 936 * {@hide} 937 */ 938 public int untether(String iface) { 939 try { 940 return mService.untether(iface); 941 } catch (RemoteException e) { 942 return TETHER_ERROR_SERVICE_UNAVAIL; 943 } 944 } 945 946 /** 947 * Check if the device allows for tethering. It may be disabled via 948 * {@code ro.tether.denied} system property, {@link Settings#TETHER_SUPPORTED} or 949 * due to device configuration. 950 * 951 * @return a boolean - {@code true} indicating Tethering is supported. 952 * 953 * <p>This method requires the call to hold the permission 954 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 955 * {@hide} 956 */ 957 public boolean isTetheringSupported() { 958 try { 959 return mService.isTetheringSupported(); 960 } catch (RemoteException e) { 961 return false; 962 } 963 } 964 965 /** 966 * Get the list of regular expressions that define any tetherable 967 * USB network interfaces. If USB tethering is not supported by the 968 * device, this list should be empty. 969 * 970 * @return an array of 0 or more regular expression Strings defining 971 * what interfaces are considered tetherable usb interfaces. 972 * 973 * <p>This method requires the call to hold the permission 974 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 975 * {@hide} 976 */ 977 public String[] getTetherableUsbRegexs() { 978 try { 979 return mService.getTetherableUsbRegexs(); 980 } catch (RemoteException e) { 981 return new String[0]; 982 } 983 } 984 985 /** 986 * Get the list of regular expressions that define any tetherable 987 * Wifi network interfaces. If Wifi tethering is not supported by the 988 * device, this list should be empty. 989 * 990 * @return an array of 0 or more regular expression Strings defining 991 * what interfaces are considered tetherable wifi interfaces. 992 * 993 * <p>This method requires the call to hold the permission 994 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 995 * {@hide} 996 */ 997 public String[] getTetherableWifiRegexs() { 998 try { 999 return mService.getTetherableWifiRegexs(); 1000 } catch (RemoteException e) { 1001 return new String[0]; 1002 } 1003 } 1004 1005 /** 1006 * Get the list of regular expressions that define any tetherable 1007 * Bluetooth network interfaces. If Bluetooth tethering is not supported by the 1008 * device, this list should be empty. 1009 * 1010 * @return an array of 0 or more regular expression Strings defining 1011 * what interfaces are considered tetherable bluetooth interfaces. 1012 * 1013 * <p>This method requires the call to hold the permission 1014 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 1015 * {@hide} 1016 */ 1017 public String[] getTetherableBluetoothRegexs() { 1018 try { 1019 return mService.getTetherableBluetoothRegexs(); 1020 } catch (RemoteException e) { 1021 return new String[0]; 1022 } 1023 } 1024 1025 /** 1026 * Attempt to both alter the mode of USB and Tethering of USB. A 1027 * utility method to deal with some of the complexity of USB - will 1028 * attempt to switch to Rndis and subsequently tether the resulting 1029 * interface on {@code true} or turn off tethering and switch off 1030 * Rndis on {@code false}. 1031 * 1032 * @param enable a boolean - {@code true} to enable tethering 1033 * @return error a {@code TETHER_ERROR} value indicating success or failure type 1034 * 1035 * <p>This method requires the call to hold the permission 1036 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE}. 1037 * {@hide} 1038 */ 1039 public int setUsbTethering(boolean enable) { 1040 try { 1041 return mService.setUsbTethering(enable); 1042 } catch (RemoteException e) { 1043 return TETHER_ERROR_SERVICE_UNAVAIL; 1044 } 1045 } 1046 1047 /** {@hide} */ 1048 public static final int TETHER_ERROR_NO_ERROR = 0; 1049 /** {@hide} */ 1050 public static final int TETHER_ERROR_UNKNOWN_IFACE = 1; 1051 /** {@hide} */ 1052 public static final int TETHER_ERROR_SERVICE_UNAVAIL = 2; 1053 /** {@hide} */ 1054 public static final int TETHER_ERROR_UNSUPPORTED = 3; 1055 /** {@hide} */ 1056 public static final int TETHER_ERROR_UNAVAIL_IFACE = 4; 1057 /** {@hide} */ 1058 public static final int TETHER_ERROR_MASTER_ERROR = 5; 1059 /** {@hide} */ 1060 public static final int TETHER_ERROR_TETHER_IFACE_ERROR = 6; 1061 /** {@hide} */ 1062 public static final int TETHER_ERROR_UNTETHER_IFACE_ERROR = 7; 1063 /** {@hide} */ 1064 public static final int TETHER_ERROR_ENABLE_NAT_ERROR = 8; 1065 /** {@hide} */ 1066 public static final int TETHER_ERROR_DISABLE_NAT_ERROR = 9; 1067 /** {@hide} */ 1068 public static final int TETHER_ERROR_IFACE_CFG_ERROR = 10; 1069 1070 /** 1071 * Get a more detailed error code after a Tethering or Untethering 1072 * request asynchronously failed. 1073 * 1074 * @param iface The name of the interface of interest 1075 * @return error The error code of the last error tethering or untethering the named 1076 * interface 1077 * 1078 * <p>This method requires the call to hold the permission 1079 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 1080 * {@hide} 1081 */ 1082 public int getLastTetherError(String iface) { 1083 try { 1084 return mService.getLastTetherError(iface); 1085 } catch (RemoteException e) { 1086 return TETHER_ERROR_SERVICE_UNAVAIL; 1087 } 1088 } 1089 1090 /** 1091 * Try to ensure the device stays awake until we connect with the next network. 1092 * Actually just holds a wakelock for a number of seconds while we try to connect 1093 * to any default networks. This will expire if the timeout passes or if we connect 1094 * to a default after this is called. For internal use only. 1095 * 1096 * @param forWhom the name of the network going down for logging purposes 1097 * @return {@code true} on success, {@code false} on failure 1098 * 1099 * <p>This method requires the call to hold the permission 1100 * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}. 1101 * {@hide} 1102 */ 1103 public boolean requestNetworkTransitionWakelock(String forWhom) { 1104 try { 1105 mService.requestNetworkTransitionWakelock(forWhom); 1106 return true; 1107 } catch (RemoteException e) { 1108 return false; 1109 } 1110 } 1111 1112 /** 1113 * Report network connectivity status. This is currently used only 1114 * to alter status bar UI. 1115 * 1116 * @param networkType The type of network you want to report on 1117 * @param percentage The quality of the connection 0 is bad, 100 is good 1118 * 1119 * <p>This method requires the call to hold the permission 1120 * {@link android.Manifest.permission#STATUS_BAR}. 1121 * {@hide} 1122 */ 1123 public void reportInetCondition(int networkType, int percentage) { 1124 try { 1125 mService.reportInetCondition(networkType, percentage); 1126 } catch (RemoteException e) { 1127 } 1128 } 1129 1130 /** 1131 * Set a network-independent global http proxy. This is not normally what you want 1132 * for typical HTTP proxies - they are general network dependent. However if you're 1133 * doing something unusual like general internal filtering this may be useful. On 1134 * a private network where the proxy is not accessible, you may break HTTP using this. 1135 * 1136 * @param proxyProperties The a {@link ProxyProperites} object defining the new global 1137 * HTTP proxy. A {@code null} value will clear the global HTTP proxy. 1138 * 1139 * <p>This method requires the call to hold the permission 1140 * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}. 1141 * {@hide} 1142 */ 1143 public void setGlobalProxy(ProxyProperties p) { 1144 try { 1145 mService.setGlobalProxy(p); 1146 } catch (RemoteException e) { 1147 } 1148 } 1149 1150 /** 1151 * Retrieve any network-independent global HTTP proxy. 1152 * 1153 * @return {@link ProxyProperties} for the current global HTTP proxy or {@code null} 1154 * if no global HTTP proxy is set. 1155 * 1156 * <p>This method requires the call to hold the permission 1157 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 1158 * {@hide} 1159 */ 1160 public ProxyProperties getGlobalProxy() { 1161 try { 1162 return mService.getGlobalProxy(); 1163 } catch (RemoteException e) { 1164 return null; 1165 } 1166 } 1167 1168 /** 1169 * Get the HTTP proxy settings for the current default network. Note that 1170 * if a global proxy is set, it will override any per-network setting. 1171 * 1172 * @return the {@link ProxyProperties} for the current HTTP proxy, or {@code null} if no 1173 * HTTP proxy is active. 1174 * 1175 * <p>This method requires the call to hold the permission 1176 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 1177 * {@hide} 1178 */ 1179 public ProxyProperties getProxy() { 1180 try { 1181 return mService.getProxy(); 1182 } catch (RemoteException e) { 1183 return null; 1184 } 1185 } 1186 1187 /** 1188 * Sets a secondary requirement bit for the given networkType. 1189 * This requirement bit is generally under the control of the carrier 1190 * or its agents and is not directly controlled by the user. 1191 * 1192 * @param networkType The network who's dependence has changed 1193 * @param met Boolean - true if network use is OK, false if not 1194 * 1195 * <p>This method requires the call to hold the permission 1196 * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}. 1197 * {@hide} 1198 */ 1199 public void setDataDependency(int networkType, boolean met) { 1200 try { 1201 mService.setDataDependency(networkType, met); 1202 } catch (RemoteException e) { 1203 } 1204 } 1205 1206 /** 1207 * Returns true if the hardware supports the given network type 1208 * else it returns false. This doesn't indicate we have coverage 1209 * or are authorized onto a network, just whether or not the 1210 * hardware supports it. For example a GSM phone without a SIM 1211 * should still return {@code true} for mobile data, but a wifi only 1212 * tablet would return {@code false}. 1213 * 1214 * @param networkType The network type we'd like to check 1215 * @return {@code true} if supported, else {@code false} 1216 * 1217 * <p>This method requires the call to hold the permission 1218 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 1219 * @hide 1220 */ 1221 public boolean isNetworkSupported(int networkType) { 1222 try { 1223 return mService.isNetworkSupported(networkType); 1224 } catch (RemoteException e) {} 1225 return false; 1226 } 1227 1228 /** 1229 * Returns if the currently active data network is metered. A network is 1230 * classified as metered when the user is sensitive to heavy data usage on 1231 * that connection due to monetary costs, data limitations or 1232 * battery/performance issues. You should check this before doing large 1233 * data transfers, and warn the user or delay the operation until another 1234 * network is available. 1235 * 1236 * @return {@code true} if large transfers should be avoided, otherwise 1237 * {@code false}. 1238 * 1239 * <p>This method requires the call to hold the permission 1240 * {@link android.Manifest.permission#ACCESS_NETWORK_STATE}. 1241 */ 1242 public boolean isActiveNetworkMetered() { 1243 try { 1244 return mService.isActiveNetworkMetered(); 1245 } catch (RemoteException e) { 1246 return false; 1247 } 1248 } 1249 1250 /** 1251 * If the LockdownVpn mechanism is enabled, updates the vpn 1252 * with a reload of its profile. 1253 * 1254 * @return a boolean with {@code} indicating success 1255 * 1256 * <p>This method can only be called by the system UID 1257 * {@hide} 1258 */ 1259 public boolean updateLockdownVpn() { 1260 try { 1261 return mService.updateLockdownVpn(); 1262 } catch (RemoteException e) { 1263 return false; 1264 } 1265 } 1266 1267 /** 1268 * Signal that the captive portal check on the indicated network 1269 * is complete and we can turn the network on for general use. 1270 * 1271 * @param info the {@link NetworkInfo} object for the networkType 1272 * in question. 1273 * 1274 * <p>This method requires the call to hold the permission 1275 * {@link android.Manifest.permission#CONNECTIVITY_INTERNAL}. 1276 * {@hide} 1277 */ 1278 public void captivePortalCheckComplete(NetworkInfo info) { 1279 try { 1280 mService.captivePortalCheckComplete(info); 1281 } catch (RemoteException e) { 1282 } 1283 } 1284 1285 /** 1286 * Supply the backend messenger for a network tracker 1287 * 1288 * @param type NetworkType to set 1289 * @param messenger {@link Messenger} 1290 * {@hide} 1291 */ 1292 public void supplyMessenger(int networkType, Messenger messenger) { 1293 try { 1294 mService.supplyMessenger(networkType, messenger); 1295 } catch (RemoteException e) { 1296 } 1297 } 1298 1299 /** 1300 * The ResultReceiver resultCode for checkMobileProvisioning (CMP_RESULT_CODE) 1301 */ 1302 1303 /** 1304 * No connection was possible to the network. 1305 * {@hide} 1306 */ 1307 public static final int CMP_RESULT_CODE_NO_CONNECTION = 0; 1308 1309 /** 1310 * A connection was made to the internet, all is well. 1311 * {@hide} 1312 */ 1313 public static final int CMP_RESULT_CODE_CONNECTABLE = 1; 1314 1315 /** 1316 * A connection was made but there was a redirection, we appear to be in walled garden. 1317 * This is an indication of a warm sim on a mobile network. 1318 * {@hide} 1319 */ 1320 public static final int CMP_RESULT_CODE_REDIRECTED = 2; 1321 1322 /** 1323 * A connection was made but no dns server was available to resolve a name to address. 1324 * This is an indication of a warm sim on a mobile network. 1325 * 1326 * {@hide} 1327 */ 1328 public static final int CMP_RESULT_CODE_NO_DNS = 3; 1329 1330 /** 1331 * A connection was made but could not open a TCP connection. 1332 * This is an indication of a warm sim on a mobile network. 1333 * {@hide} 1334 */ 1335 public static final int CMP_RESULT_CODE_NO_TCP_CONNECTION = 4; 1336 1337 /** 1338 * Check mobile provisioning. The resultCode passed to 1339 * onReceiveResult will be one of the CMP_RESULT_CODE_xxxx values above. 1340 * This may take a minute or more to complete. 1341 * 1342 * @param sendNotificaiton, when true a notification will be sent to user. 1343 * @param suggestedTimeOutMs, timeout in milliseconds 1344 * @param resultReceiver needs to be supplied to receive the result 1345 * 1346 * @return time out that will be used, maybe less that suggestedTimeOutMs 1347 * -1 if an error. 1348 * 1349 * {@hide} 1350 */ 1351 public int checkMobileProvisioning(boolean sendNotification, int suggestedTimeOutMs, 1352 ResultReceiver resultReceiver) { 1353 int timeOutMs = -1; 1354 try { 1355 timeOutMs = mService.checkMobileProvisioning(sendNotification, suggestedTimeOutMs, 1356 resultReceiver); 1357 } catch (RemoteException e) { 1358 } 1359 return timeOutMs; 1360 } 1361 1362 /** 1363 * Get the carrier provisioning url. 1364 * {@hide} 1365 */ 1366 public String getMobileProvisioningUrl() { 1367 try { 1368 return mService.getMobileProvisioningUrl(); 1369 } catch (RemoteException e) { 1370 } 1371 return null; 1372 } 1373 } 1374
