1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.net; 18 19import android.annotation.SdkConstant; 20import android.annotation.SdkConstant.SdkConstantType; 21import android.os.Binder; 22import android.os.RemoteException; 23 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 */ 40public 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_ETHERNET; 223 /** {@hide} TODO: Need to adjust this for WiMAX. */ 224 public static final int MAX_NETWORK_TYPE = TYPE_ETHERNET; 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} 569