core/java/android/net/ConnectivityManager.java

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