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