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