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 package android.net; 17 18 import static android.annotation.SystemApi.Client.MODULE_LIBRARIES; 19 import static android.net.NetworkCapabilities.NET_ENTERPRISE_ID_1; 20 import static android.net.NetworkRequest.Type.BACKGROUND_REQUEST; 21 import static android.net.NetworkRequest.Type.LISTEN; 22 import static android.net.NetworkRequest.Type.LISTEN_FOR_BEST; 23 import static android.net.NetworkRequest.Type.REQUEST; 24 import static android.net.NetworkRequest.Type.TRACK_DEFAULT; 25 import static android.net.NetworkRequest.Type.TRACK_SYSTEM_DEFAULT; 26 import static android.net.QosCallback.QosCallbackRegistrationException; 27 28 import android.annotation.CallbackExecutor; 29 import android.annotation.IntDef; 30 import android.annotation.NonNull; 31 import android.annotation.Nullable; 32 import android.annotation.RequiresPermission; 33 import android.annotation.SdkConstant; 34 import android.annotation.SdkConstant.SdkConstantType; 35 import android.annotation.SuppressLint; 36 import android.annotation.SystemApi; 37 import android.annotation.SystemService; 38 import android.app.PendingIntent; 39 import android.app.admin.DevicePolicyManager; 40 import android.compat.annotation.UnsupportedAppUsage; 41 import android.content.ComponentName; 42 import android.content.Context; 43 import android.content.Intent; 44 import android.net.ConnectivityDiagnosticsManager.DataStallReport.DetectionMethod; 45 import android.net.IpSecManager.UdpEncapsulationSocket; 46 import android.net.SocketKeepalive.Callback; 47 import android.net.TetheringManager.StartTetheringCallback; 48 import android.net.TetheringManager.TetheringEventCallback; 49 import android.net.TetheringManager.TetheringRequest; 50 import android.os.Binder; 51 import android.os.Build; 52 import android.os.Build.VERSION_CODES; 53 import android.os.Bundle; 54 import android.os.Handler; 55 import android.os.IBinder; 56 import android.os.Looper; 57 import android.os.Message; 58 import android.os.Messenger; 59 import android.os.ParcelFileDescriptor; 60 import android.os.PersistableBundle; 61 import android.os.Process; 62 import android.os.RemoteException; 63 import android.os.ResultReceiver; 64 import android.os.ServiceSpecificException; 65 import android.os.UserHandle; 66 import android.provider.Settings; 67 import android.telephony.SubscriptionManager; 68 import android.telephony.TelephonyManager; 69 import android.util.ArrayMap; 70 import android.util.Log; 71 import android.util.Range; 72 import android.util.SparseIntArray; 73 74 import com.android.internal.annotations.GuardedBy; 75 76 import libcore.net.event.NetworkEventDispatcher; 77 78 import java.io.IOException; 79 import java.io.UncheckedIOException; 80 import java.lang.annotation.Retention; 81 import java.lang.annotation.RetentionPolicy; 82 import java.net.DatagramSocket; 83 import java.net.InetAddress; 84 import java.net.InetSocketAddress; 85 import java.net.Socket; 86 import java.util.ArrayList; 87 import java.util.Collection; 88 import java.util.HashMap; 89 import java.util.List; 90 import java.util.Map; 91 import java.util.Objects; 92 import java.util.concurrent.Executor; 93 import java.util.concurrent.ExecutorService; 94 import java.util.concurrent.Executors; 95 import java.util.concurrent.RejectedExecutionException; 96 97 /** 98 * Class that answers queries about the state of network connectivity. It also 99 * notifies applications when network connectivity changes. 100 * <p> 101 * The primary responsibilities of this class are to: 102 * <ol> 103 * <li>Monitor network connections (Wi-Fi, GPRS, UMTS, etc.)</li> 104 * <li>Send broadcast intents when network connectivity changes</li> 105 * <li>Attempt to "fail over" to another network when connectivity to a network 106 * is lost</li> 107 * <li>Provide an API that allows applications to query the coarse-grained or fine-grained 108 * state of the available networks</li> 109 * <li>Provide an API that allows applications to request and select networks for their data 110 * traffic</li> 111 * </ol> 112 */ 113 @SystemService(Context.CONNECTIVITY_SERVICE) 114 public class ConnectivityManager { 115 private static final String TAG = "ConnectivityManager"; 116 private static final boolean DEBUG = Log.isLoggable(TAG, Log.DEBUG); 117 118 /** 119 * A change in network connectivity has occurred. A default connection has either 120 * been established or lost. The NetworkInfo for the affected network is 121 * sent as an extra; it should be consulted to see what kind of 122 * connectivity event occurred. 123 * <p/> 124 * Apps targeting Android 7.0 (API level 24) and higher do not receive this 125 * broadcast if they declare the broadcast receiver in their manifest. Apps 126 * will still receive broadcasts if they register their 127 * {@link android.content.BroadcastReceiver} with 128 * {@link android.content.Context#registerReceiver Context.registerReceiver()} 129 * and that context is still valid. 130 * <p/> 131 * If this is a connection that was the result of failing over from a 132 * disconnected network, then the FAILOVER_CONNECTION boolean extra is 133 * set to true. 134 * <p/> 135 * For a loss of connectivity, if the connectivity manager is attempting 136 * to connect (or has already connected) to another network, the 137 * NetworkInfo for the new network is also passed as an extra. This lets 138 * any receivers of the broadcast know that they should not necessarily 139 * tell the user that no data traffic will be possible. Instead, the 140 * receiver should expect another broadcast soon, indicating either that 141 * the failover attempt succeeded (and so there is still overall data 142 * connectivity), or that the failover attempt failed, meaning that all 143 * connectivity has been lost. 144 * <p/> 145 * For a disconnect event, the boolean extra EXTRA_NO_CONNECTIVITY 146 * is set to {@code true} if there are no connected networks at all. 147 * <p /> 148 * Note that this broadcast is deprecated and generally tries to implement backwards 149 * compatibility with older versions of Android. As such, it may not reflect new 150 * capabilities of the system, like multiple networks being connected at the same 151 * time, the details of newer technology, or changes in tethering state. 152 * 153 * @deprecated apps should use the more versatile {@link #requestNetwork}, 154 * {@link #registerNetworkCallback} or {@link #registerDefaultNetworkCallback} 155 * functions instead for faster and more detailed updates about the network 156 * changes they care about. 157 */ 158 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 159 @Deprecated 160 public static final String CONNECTIVITY_ACTION = "android.net.conn.CONNECTIVITY_CHANGE"; 161 162 /** 163 * The device has connected to a network that has presented a captive 164 * portal, which is blocking Internet connectivity. The user was presented 165 * with a notification that network sign in is required, 166 * and the user invoked the notification's action indicating they 167 * desire to sign in to the network. Apps handling this activity should 168 * facilitate signing in to the network. This action includes a 169 * {@link Network} typed extra called {@link #EXTRA_NETWORK} that represents 170 * the network presenting the captive portal; all communication with the 171 * captive portal must be done using this {@code Network} object. 172 * <p/> 173 * This activity includes a {@link CaptivePortal} extra named 174 * {@link #EXTRA_CAPTIVE_PORTAL} that can be used to indicate different 175 * outcomes of the captive portal sign in to the system: 176 * <ul> 177 * <li> When the app handling this action believes the user has signed in to 178 * the network and the captive portal has been dismissed, the app should 179 * call {@link CaptivePortal#reportCaptivePortalDismissed} so the system can 180 * reevaluate the network. If reevaluation finds the network no longer 181 * subject to a captive portal, the network may become the default active 182 * data network.</li> 183 * <li> When the app handling this action believes the user explicitly wants 184 * to ignore the captive portal and the network, the app should call 185 * {@link CaptivePortal#ignoreNetwork}. </li> 186 * </ul> 187 */ 188 @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) 189 public static final String ACTION_CAPTIVE_PORTAL_SIGN_IN = "android.net.conn.CAPTIVE_PORTAL"; 190 191 /** 192 * The lookup key for a {@link NetworkInfo} object. Retrieve with 193 * {@link android.content.Intent#getParcelableExtra(String)}. 194 * 195 * @deprecated The {@link NetworkInfo} object is deprecated, as many of its properties 196 * can't accurately represent modern network characteristics. 197 * Please obtain information about networks from the {@link NetworkCapabilities} 198 * or {@link LinkProperties} objects instead. 199 */ 200 @Deprecated 201 public static final String EXTRA_NETWORK_INFO = "networkInfo"; 202 203 /** 204 * Network type which triggered a {@link #CONNECTIVITY_ACTION} broadcast. 205 * 206 * @see android.content.Intent#getIntExtra(String, int) 207 * @deprecated The network type is not rich enough to represent the characteristics 208 * of modern networks. Please use {@link NetworkCapabilities} instead, 209 * in particular the transports. 210 */ 211 @Deprecated 212 public static final String EXTRA_NETWORK_TYPE = "networkType"; 213 214 /** 215 * The lookup key for a boolean that indicates whether a connect event 216 * is for a network to which the connectivity manager was failing over 217 * following a disconnect on another network. 218 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 219 * 220 * @deprecated See {@link NetworkInfo}. 221 */ 222 @Deprecated 223 public static final String EXTRA_IS_FAILOVER = "isFailover"; 224 /** 225 * The lookup key for a {@link NetworkInfo} object. This is supplied when 226 * there is another network that it may be possible to connect to. Retrieve with 227 * {@link android.content.Intent#getParcelableExtra(String)}. 228 * 229 * @deprecated See {@link NetworkInfo}. 230 */ 231 @Deprecated 232 public static final String EXTRA_OTHER_NETWORK_INFO = "otherNetwork"; 233 /** 234 * The lookup key for a boolean that indicates whether there is a 235 * complete lack of connectivity, i.e., no network is available. 236 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 237 */ 238 public static final String EXTRA_NO_CONNECTIVITY = "noConnectivity"; 239 /** 240 * The lookup key for a string that indicates why an attempt to connect 241 * to a network failed. The string has no particular structure. It is 242 * intended to be used in notifications presented to users. Retrieve 243 * it with {@link android.content.Intent#getStringExtra(String)}. 244 */ 245 public static final String EXTRA_REASON = "reason"; 246 /** 247 * The lookup key for a string that provides optionally supplied 248 * extra information about the network state. The information 249 * may be passed up from the lower networking layers, and its 250 * meaning may be specific to a particular network type. Retrieve 251 * it with {@link android.content.Intent#getStringExtra(String)}. 252 * 253 * @deprecated See {@link NetworkInfo#getExtraInfo()}. 254 */ 255 @Deprecated 256 public static final String EXTRA_EXTRA_INFO = "extraInfo"; 257 /** 258 * The lookup key for an int that provides information about 259 * our connection to the internet at large. 0 indicates no connection, 260 * 100 indicates a great connection. Retrieve it with 261 * {@link android.content.Intent#getIntExtra(String, int)}. 262 * {@hide} 263 */ 264 public static final String EXTRA_INET_CONDITION = "inetCondition"; 265 /** 266 * The lookup key for a {@link CaptivePortal} object included with the 267 * {@link #ACTION_CAPTIVE_PORTAL_SIGN_IN} intent. The {@code CaptivePortal} 268 * object can be used to either indicate to the system that the captive 269 * portal has been dismissed or that the user does not want to pursue 270 * signing in to captive portal. Retrieve it with 271 * {@link android.content.Intent#getParcelableExtra(String)}. 272 */ 273 public static final String EXTRA_CAPTIVE_PORTAL = "android.net.extra.CAPTIVE_PORTAL"; 274 275 /** 276 * Key for passing a URL to the captive portal login activity. 277 */ 278 public static final String EXTRA_CAPTIVE_PORTAL_URL = "android.net.extra.CAPTIVE_PORTAL_URL"; 279 280 /** 281 * Key for passing a {@link android.net.captiveportal.CaptivePortalProbeSpec} to the captive 282 * portal login activity. 283 * {@hide} 284 */ 285 @SystemApi 286 public static final String EXTRA_CAPTIVE_PORTAL_PROBE_SPEC = 287 "android.net.extra.CAPTIVE_PORTAL_PROBE_SPEC"; 288 289 /** 290 * Key for passing a user agent string to the captive portal login activity. 291 * {@hide} 292 */ 293 @SystemApi 294 public static final String EXTRA_CAPTIVE_PORTAL_USER_AGENT = 295 "android.net.extra.CAPTIVE_PORTAL_USER_AGENT"; 296 297 /** 298 * Broadcast action to indicate the change of data activity status 299 * (idle or active) on a network in a recent period. 300 * The network becomes active when data transmission is started, or 301 * idle if there is no data transmission for a period of time. 302 * {@hide} 303 */ 304 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 305 public static final String ACTION_DATA_ACTIVITY_CHANGE = 306 "android.net.conn.DATA_ACTIVITY_CHANGE"; 307 /** 308 * The lookup key for an enum that indicates the network device type on which this data activity 309 * change happens. 310 * {@hide} 311 */ 312 public static final String EXTRA_DEVICE_TYPE = "deviceType"; 313 /** 314 * The lookup key for a boolean that indicates the device is active or not. {@code true} means 315 * it is actively sending or receiving data and {@code false} means it is idle. 316 * {@hide} 317 */ 318 public static final String EXTRA_IS_ACTIVE = "isActive"; 319 /** 320 * The lookup key for a long that contains the timestamp (nanos) of the radio state change. 321 * {@hide} 322 */ 323 public static final String EXTRA_REALTIME_NS = "tsNanos"; 324 325 /** 326 * Broadcast Action: The setting for background data usage has changed 327 * values. Use {@link #getBackgroundDataSetting()} to get the current value. 328 * <p> 329 * If an application uses the network in the background, it should listen 330 * for this broadcast and stop using the background data if the value is 331 * {@code false}. 332 * <p> 333 * 334 * @deprecated As of {@link VERSION_CODES#ICE_CREAM_SANDWICH}, availability 335 * of background data depends on several combined factors, and 336 * this broadcast is no longer sent. Instead, when background 337 * data is unavailable, {@link #getActiveNetworkInfo()} will now 338 * appear disconnected. During first boot after a platform 339 * upgrade, this broadcast will be sent once if 340 * {@link #getBackgroundDataSetting()} was {@code false} before 341 * the upgrade. 342 */ 343 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 344 @Deprecated 345 public static final String ACTION_BACKGROUND_DATA_SETTING_CHANGED = 346 "android.net.conn.BACKGROUND_DATA_SETTING_CHANGED"; 347 348 /** 349 * Broadcast Action: The network connection may not be good 350 * uses {@code ConnectivityManager.EXTRA_INET_CONDITION} and 351 * {@code ConnectivityManager.EXTRA_NETWORK_INFO} to specify 352 * the network and it's condition. 353 * @hide 354 */ 355 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 356 @UnsupportedAppUsage 357 public static final String INET_CONDITION_ACTION = 358 "android.net.conn.INET_CONDITION_ACTION"; 359 360 /** 361 * Broadcast Action: A tetherable connection has come or gone. 362 * Uses {@code ConnectivityManager.EXTRA_AVAILABLE_TETHER}, 363 * {@code ConnectivityManager.EXTRA_ACTIVE_LOCAL_ONLY}, 364 * {@code ConnectivityManager.EXTRA_ACTIVE_TETHER}, and 365 * {@code ConnectivityManager.EXTRA_ERRORED_TETHER} to indicate 366 * the current state of tethering. Each include a list of 367 * interface names in that state (may be empty). 368 * @hide 369 */ 370 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 371 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 372 public static final String ACTION_TETHER_STATE_CHANGED = 373 TetheringManager.ACTION_TETHER_STATE_CHANGED; 374 375 /** 376 * @hide 377 * gives a String[] listing all the interfaces configured for 378 * tethering and currently available for tethering. 379 */ 380 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 381 public static final String EXTRA_AVAILABLE_TETHER = TetheringManager.EXTRA_AVAILABLE_TETHER; 382 383 /** 384 * @hide 385 * gives a String[] listing all the interfaces currently in local-only 386 * mode (ie, has DHCPv4+IPv6-ULA support and no packet forwarding) 387 */ 388 public static final String EXTRA_ACTIVE_LOCAL_ONLY = TetheringManager.EXTRA_ACTIVE_LOCAL_ONLY; 389 390 /** 391 * @hide 392 * gives a String[] listing all the interfaces currently tethered 393 * (ie, has DHCPv4 support and packets potentially forwarded/NATed) 394 */ 395 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 396 public static final String EXTRA_ACTIVE_TETHER = TetheringManager.EXTRA_ACTIVE_TETHER; 397 398 /** 399 * @hide 400 * gives a String[] listing all the interfaces we tried to tether and 401 * failed. Use {@link #getLastTetherError} to find the error code 402 * for any interfaces listed here. 403 */ 404 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 405 public static final String EXTRA_ERRORED_TETHER = TetheringManager.EXTRA_ERRORED_TETHER; 406 407 /** 408 * Broadcast Action: The captive portal tracker has finished its test. 409 * Sent only while running Setup Wizard, in lieu of showing a user 410 * notification. 411 * @hide 412 */ 413 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 414 public static final String ACTION_CAPTIVE_PORTAL_TEST_COMPLETED = 415 "android.net.conn.CAPTIVE_PORTAL_TEST_COMPLETED"; 416 /** 417 * The lookup key for a boolean that indicates whether a captive portal was detected. 418 * Retrieve it with {@link android.content.Intent#getBooleanExtra(String,boolean)}. 419 * @hide 420 */ 421 public static final String EXTRA_IS_CAPTIVE_PORTAL = "captivePortal"; 422 423 /** 424 * Action used to display a dialog that asks the user whether to connect to a network that is 425 * not validated. This intent is used to start the dialog in settings via startActivity. 426 * 427 * This action includes a {@link Network} typed extra which is called 428 * {@link ConnectivityManager#EXTRA_NETWORK} that represents the network which is unvalidated. 429 * 430 * @hide 431 */ 432 @SystemApi(client = MODULE_LIBRARIES) 433 public static final String ACTION_PROMPT_UNVALIDATED = "android.net.action.PROMPT_UNVALIDATED"; 434 435 /** 436 * Action used to display a dialog that asks the user whether to avoid a network that is no 437 * longer validated. This intent is used to start the dialog in settings via startActivity. 438 * 439 * This action includes a {@link Network} typed extra which is called 440 * {@link ConnectivityManager#EXTRA_NETWORK} that represents the network which is no longer 441 * validated. 442 * 443 * @hide 444 */ 445 @SystemApi(client = MODULE_LIBRARIES) 446 public static final String ACTION_PROMPT_LOST_VALIDATION = 447 "android.net.action.PROMPT_LOST_VALIDATION"; 448 449 /** 450 * Action used to display a dialog that asks the user whether to stay connected to a network 451 * that has not validated. This intent is used to start the dialog in settings via 452 * startActivity. 453 * 454 * This action includes a {@link Network} typed extra which is called 455 * {@link ConnectivityManager#EXTRA_NETWORK} that represents the network which has partial 456 * connectivity. 457 * 458 * @hide 459 */ 460 @SystemApi(client = MODULE_LIBRARIES) 461 public static final String ACTION_PROMPT_PARTIAL_CONNECTIVITY = 462 "android.net.action.PROMPT_PARTIAL_CONNECTIVITY"; 463 464 /** 465 * Clear DNS Cache Action: This is broadcast when networks have changed and old 466 * DNS entries should be cleared. 467 * @hide 468 */ 469 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 470 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 471 public static final String ACTION_CLEAR_DNS_CACHE = "android.net.action.CLEAR_DNS_CACHE"; 472 473 /** 474 * Invalid tethering type. 475 * @see #startTethering(int, boolean, OnStartTetheringCallback) 476 * @hide 477 */ 478 public static final int TETHERING_INVALID = TetheringManager.TETHERING_INVALID; 479 480 /** 481 * Wifi tethering type. 482 * @see #startTethering(int, boolean, OnStartTetheringCallback) 483 * @hide 484 */ 485 @SystemApi 486 public static final int TETHERING_WIFI = 0; 487 488 /** 489 * USB tethering type. 490 * @see #startTethering(int, boolean, OnStartTetheringCallback) 491 * @hide 492 */ 493 @SystemApi 494 public static final int TETHERING_USB = 1; 495 496 /** 497 * Bluetooth tethering type. 498 * @see #startTethering(int, boolean, OnStartTetheringCallback) 499 * @hide 500 */ 501 @SystemApi 502 public static final int TETHERING_BLUETOOTH = 2; 503 504 /** 505 * Wifi P2p tethering type. 506 * Wifi P2p tethering is set through events automatically, and don't 507 * need to start from #startTethering(int, boolean, OnStartTetheringCallback). 508 * @hide 509 */ 510 public static final int TETHERING_WIFI_P2P = TetheringManager.TETHERING_WIFI_P2P; 511 512 /** 513 * Extra used for communicating with the TetherService. Includes the type of tethering to 514 * enable if any. 515 * @hide 516 */ 517 public static final String EXTRA_ADD_TETHER_TYPE = TetheringConstants.EXTRA_ADD_TETHER_TYPE; 518 519 /** 520 * Extra used for communicating with the TetherService. Includes the type of tethering for 521 * which to cancel provisioning. 522 * @hide 523 */ 524 public static final String EXTRA_REM_TETHER_TYPE = TetheringConstants.EXTRA_REM_TETHER_TYPE; 525 526 /** 527 * Extra used for communicating with the TetherService. True to schedule a recheck of tether 528 * provisioning. 529 * @hide 530 */ 531 public static final String EXTRA_SET_ALARM = TetheringConstants.EXTRA_SET_ALARM; 532 533 /** 534 * Tells the TetherService to run a provision check now. 535 * @hide 536 */ 537 public static final String EXTRA_RUN_PROVISION = TetheringConstants.EXTRA_RUN_PROVISION; 538 539 /** 540 * Extra used for communicating with the TetherService. Contains the {@link ResultReceiver} 541 * which will receive provisioning results. Can be left empty. 542 * @hide 543 */ 544 public static final String EXTRA_PROVISION_CALLBACK = 545 TetheringConstants.EXTRA_PROVISION_CALLBACK; 546 547 /** 548 * The absence of a connection type. 549 * @hide 550 */ 551 @SystemApi 552 public static final int TYPE_NONE = -1; 553 554 /** 555 * A Mobile data connection. Devices may support more than one. 556 * 557 * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or 558 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an 559 * appropriate network. {@see NetworkCapabilities} for supported transports. 560 */ 561 @Deprecated 562 public static final int TYPE_MOBILE = 0; 563 564 /** 565 * A WIFI data connection. Devices may support more than one. 566 * 567 * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or 568 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an 569 * appropriate network. {@see NetworkCapabilities} for supported transports. 570 */ 571 @Deprecated 572 public static final int TYPE_WIFI = 1; 573 574 /** 575 * An MMS-specific Mobile data connection. This network type may use the 576 * same network interface as {@link #TYPE_MOBILE} or it may use a different 577 * one. This is used by applications needing to talk to the carrier's 578 * Multimedia Messaging Service servers. 579 * 580 * @deprecated Applications should instead use {@link NetworkCapabilities#hasCapability} or 581 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request a network that 582 * provides the {@link NetworkCapabilities#NET_CAPABILITY_MMS} capability. 583 */ 584 @Deprecated 585 public static final int TYPE_MOBILE_MMS = 2; 586 587 /** 588 * A SUPL-specific Mobile data connection. This network type may use the 589 * same network interface as {@link #TYPE_MOBILE} or it may use a different 590 * one. This is used by applications needing to talk to the carrier's 591 * Secure User Plane Location servers for help locating the device. 592 * 593 * @deprecated Applications should instead use {@link NetworkCapabilities#hasCapability} or 594 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request a network that 595 * provides the {@link NetworkCapabilities#NET_CAPABILITY_SUPL} capability. 596 */ 597 @Deprecated 598 public static final int TYPE_MOBILE_SUPL = 3; 599 600 /** 601 * A DUN-specific Mobile data connection. This network type may use the 602 * same network interface as {@link #TYPE_MOBILE} or it may use a different 603 * one. This is sometimes by the system when setting up an upstream connection 604 * for tethering so that the carrier is aware of DUN traffic. 605 * 606 * @deprecated Applications should instead use {@link NetworkCapabilities#hasCapability} or 607 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request a network that 608 * provides the {@link NetworkCapabilities#NET_CAPABILITY_DUN} capability. 609 */ 610 @Deprecated 611 public static final int TYPE_MOBILE_DUN = 4; 612 613 /** 614 * A High Priority Mobile data connection. This network type uses the 615 * same network interface as {@link #TYPE_MOBILE} but the routing setup 616 * is different. 617 * 618 * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or 619 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an 620 * appropriate network. {@see NetworkCapabilities} for supported transports. 621 */ 622 @Deprecated 623 public static final int TYPE_MOBILE_HIPRI = 5; 624 625 /** 626 * A WiMAX data connection. 627 * 628 * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or 629 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an 630 * appropriate network. {@see NetworkCapabilities} for supported transports. 631 */ 632 @Deprecated 633 public static final int TYPE_WIMAX = 6; 634 635 /** 636 * A Bluetooth data connection. 637 * 638 * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or 639 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an 640 * appropriate network. {@see NetworkCapabilities} for supported transports. 641 */ 642 @Deprecated 643 public static final int TYPE_BLUETOOTH = 7; 644 645 /** 646 * Fake data connection. This should not be used on shipping devices. 647 * @deprecated This is not used any more. 648 */ 649 @Deprecated 650 public static final int TYPE_DUMMY = 8; 651 652 /** 653 * An Ethernet data connection. 654 * 655 * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or 656 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an 657 * appropriate network. {@see NetworkCapabilities} for supported transports. 658 */ 659 @Deprecated 660 public static final int TYPE_ETHERNET = 9; 661 662 /** 663 * Over the air Administration. 664 * @deprecated Use {@link NetworkCapabilities} instead. 665 * {@hide} 666 */ 667 @Deprecated 668 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 130143562) 669 public static final int TYPE_MOBILE_FOTA = 10; 670 671 /** 672 * IP Multimedia Subsystem. 673 * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_IMS} instead. 674 * {@hide} 675 */ 676 @Deprecated 677 @UnsupportedAppUsage 678 public static final int TYPE_MOBILE_IMS = 11; 679 680 /** 681 * Carrier Branded Services. 682 * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_CBS} instead. 683 * {@hide} 684 */ 685 @Deprecated 686 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 130143562) 687 public static final int TYPE_MOBILE_CBS = 12; 688 689 /** 690 * A Wi-Fi p2p connection. Only requesting processes will have access to 691 * the peers connected. 692 * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_WIFI_P2P} instead. 693 * {@hide} 694 */ 695 @Deprecated 696 @SystemApi 697 public static final int TYPE_WIFI_P2P = 13; 698 699 /** 700 * The network to use for initially attaching to the network 701 * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_IA} instead. 702 * {@hide} 703 */ 704 @Deprecated 705 @UnsupportedAppUsage 706 public static final int TYPE_MOBILE_IA = 14; 707 708 /** 709 * Emergency PDN connection for emergency services. This 710 * may include IMS and MMS in emergency situations. 711 * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_EIMS} instead. 712 * {@hide} 713 */ 714 @Deprecated 715 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 130143562) 716 public static final int TYPE_MOBILE_EMERGENCY = 15; 717 718 /** 719 * The network that uses proxy to achieve connectivity. 720 * @deprecated Use {@link NetworkCapabilities} instead. 721 * {@hide} 722 */ 723 @Deprecated 724 @SystemApi 725 public static final int TYPE_PROXY = 16; 726 727 /** 728 * A virtual network using one or more native bearers. 729 * It may or may not be providing security services. 730 * @deprecated Applications should use {@link NetworkCapabilities#TRANSPORT_VPN} instead. 731 */ 732 @Deprecated 733 public static final int TYPE_VPN = 17; 734 735 /** 736 * A network that is exclusively meant to be used for testing 737 * 738 * @deprecated Use {@link NetworkCapabilities} instead. 739 * @hide 740 */ 741 @Deprecated 742 public static final int TYPE_TEST = 18; // TODO: Remove this once NetworkTypes are unused. 743 744 /** 745 * @deprecated Use {@link NetworkCapabilities} instead. 746 * @hide 747 */ 748 @Deprecated 749 @Retention(RetentionPolicy.SOURCE) 750 @IntDef(prefix = { "TYPE_" }, value = { 751 TYPE_NONE, 752 TYPE_MOBILE, 753 TYPE_WIFI, 754 TYPE_MOBILE_MMS, 755 TYPE_MOBILE_SUPL, 756 TYPE_MOBILE_DUN, 757 TYPE_MOBILE_HIPRI, 758 TYPE_WIMAX, 759 TYPE_BLUETOOTH, 760 TYPE_DUMMY, 761 TYPE_ETHERNET, 762 TYPE_MOBILE_FOTA, 763 TYPE_MOBILE_IMS, 764 TYPE_MOBILE_CBS, 765 TYPE_WIFI_P2P, 766 TYPE_MOBILE_IA, 767 TYPE_MOBILE_EMERGENCY, 768 TYPE_PROXY, 769 TYPE_VPN, 770 TYPE_TEST 771 }) 772 public @interface LegacyNetworkType {} 773 774 // Deprecated constants for return values of startUsingNetworkFeature. They used to live 775 // in com.android.internal.telephony.PhoneConstants until they were made inaccessible. 776 private static final int DEPRECATED_PHONE_CONSTANT_APN_ALREADY_ACTIVE = 0; 777 private static final int DEPRECATED_PHONE_CONSTANT_APN_REQUEST_STARTED = 1; 778 private static final int DEPRECATED_PHONE_CONSTANT_APN_REQUEST_FAILED = 3; 779 780 /** {@hide} */ 781 public static final int MAX_RADIO_TYPE = TYPE_TEST; 782 783 /** {@hide} */ 784 public static final int MAX_NETWORK_TYPE = TYPE_TEST; 785 786 private static final int MIN_NETWORK_TYPE = TYPE_MOBILE; 787 788 /** 789 * If you want to set the default network preference,you can directly 790 * change the networkAttributes array in framework's config.xml. 791 * 792 * @deprecated Since we support so many more networks now, the single 793 * network default network preference can't really express 794 * the hierarchy. Instead, the default is defined by the 795 * networkAttributes in config.xml. You can determine 796 * the current value by calling {@link #getNetworkPreference()} 797 * from an App. 798 */ 799 @Deprecated 800 public static final int DEFAULT_NETWORK_PREFERENCE = TYPE_WIFI; 801 802 /** 803 * @hide 804 */ 805 public static final int REQUEST_ID_UNSET = 0; 806 807 /** 808 * Static unique request used as a tombstone for NetworkCallbacks that have been unregistered. 809 * This allows to distinguish when unregistering NetworkCallbacks those that were never 810 * registered from those that were already unregistered. 811 * @hide 812 */ 813 private static final NetworkRequest ALREADY_UNREGISTERED = 814 new NetworkRequest.Builder().clearCapabilities().build(); 815 816 /** 817 * A NetID indicating no Network is selected. 818 * Keep in sync with bionic/libc/dns/include/resolv_netid.h 819 * @hide 820 */ 821 public static final int NETID_UNSET = 0; 822 823 /** 824 * Flag to indicate that an app is not subject to any restrictions that could result in its 825 * network access blocked. 826 * 827 * @hide 828 */ 829 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 830 public static final int BLOCKED_REASON_NONE = 0; 831 832 /** 833 * Flag to indicate that an app is subject to Battery saver restrictions that would 834 * result in its network access being blocked. 835 * 836 * @hide 837 */ 838 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 839 public static final int BLOCKED_REASON_BATTERY_SAVER = 1 << 0; 840 841 /** 842 * Flag to indicate that an app is subject to Doze restrictions that would 843 * result in its network access being blocked. 844 * 845 * @hide 846 */ 847 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 848 public static final int BLOCKED_REASON_DOZE = 1 << 1; 849 850 /** 851 * Flag to indicate that an app is subject to App Standby restrictions that would 852 * result in its network access being blocked. 853 * 854 * @hide 855 */ 856 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 857 public static final int BLOCKED_REASON_APP_STANDBY = 1 << 2; 858 859 /** 860 * Flag to indicate that an app is subject to Restricted mode restrictions that would 861 * result in its network access being blocked. 862 * 863 * @hide 864 */ 865 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 866 public static final int BLOCKED_REASON_RESTRICTED_MODE = 1 << 3; 867 868 /** 869 * Flag to indicate that an app is blocked because it is subject to an always-on VPN but the VPN 870 * is not currently connected. 871 * 872 * @see DevicePolicyManager#setAlwaysOnVpnPackage(ComponentName, String, boolean) 873 * 874 * @hide 875 */ 876 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 877 public static final int BLOCKED_REASON_LOCKDOWN_VPN = 1 << 4; 878 879 /** 880 * Flag to indicate that an app is subject to Low Power Standby restrictions that would 881 * result in its network access being blocked. 882 * 883 * @hide 884 */ 885 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 886 public static final int BLOCKED_REASON_LOW_POWER_STANDBY = 1 << 5; 887 888 /** 889 * Flag to indicate that an app is subject to Data saver restrictions that would 890 * result in its metered network access being blocked. 891 * 892 * @hide 893 */ 894 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 895 public static final int BLOCKED_METERED_REASON_DATA_SAVER = 1 << 16; 896 897 /** 898 * Flag to indicate that an app is subject to user restrictions that would 899 * result in its metered network access being blocked. 900 * 901 * @hide 902 */ 903 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 904 public static final int BLOCKED_METERED_REASON_USER_RESTRICTED = 1 << 17; 905 906 /** 907 * Flag to indicate that an app is subject to Device admin restrictions that would 908 * result in its metered network access being blocked. 909 * 910 * @hide 911 */ 912 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 913 public static final int BLOCKED_METERED_REASON_ADMIN_DISABLED = 1 << 18; 914 915 /** 916 * @hide 917 */ 918 @Retention(RetentionPolicy.SOURCE) 919 @IntDef(flag = true, prefix = {"BLOCKED_"}, value = { 920 BLOCKED_REASON_NONE, 921 BLOCKED_REASON_BATTERY_SAVER, 922 BLOCKED_REASON_DOZE, 923 BLOCKED_REASON_APP_STANDBY, 924 BLOCKED_REASON_RESTRICTED_MODE, 925 BLOCKED_REASON_LOCKDOWN_VPN, 926 BLOCKED_REASON_LOW_POWER_STANDBY, 927 BLOCKED_METERED_REASON_DATA_SAVER, 928 BLOCKED_METERED_REASON_USER_RESTRICTED, 929 BLOCKED_METERED_REASON_ADMIN_DISABLED, 930 }) 931 public @interface BlockedReason {} 932 933 /** 934 * Set of blocked reasons that are only applicable on metered networks. 935 * 936 * @hide 937 */ 938 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 939 public static final int BLOCKED_METERED_REASON_MASK = 0xffff0000; 940 941 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 130143562) 942 private final IConnectivityManager mService; 943 944 // LINT.IfChange(firewall_chain) 945 /** 946 * Firewall chain for device idle (doze mode). 947 * Allowlist of apps that have network access in device idle. 948 * @hide 949 */ 950 @SystemApi(client = MODULE_LIBRARIES) 951 public static final int FIREWALL_CHAIN_DOZABLE = 1; 952 953 /** 954 * Firewall chain used for app standby. 955 * Denylist of apps that do not have network access. 956 * @hide 957 */ 958 @SystemApi(client = MODULE_LIBRARIES) 959 public static final int FIREWALL_CHAIN_STANDBY = 2; 960 961 /** 962 * Firewall chain used for battery saver. 963 * Allowlist of apps that have network access when battery saver is on. 964 * @hide 965 */ 966 @SystemApi(client = MODULE_LIBRARIES) 967 public static final int FIREWALL_CHAIN_POWERSAVE = 3; 968 969 /** 970 * Firewall chain used for restricted networking mode. 971 * Allowlist of apps that have access in restricted networking mode. 972 * @hide 973 */ 974 @SystemApi(client = MODULE_LIBRARIES) 975 public static final int FIREWALL_CHAIN_RESTRICTED = 4; 976 977 /** 978 * Firewall chain used for low power standby. 979 * Allowlist of apps that have access in low power standby. 980 * @hide 981 */ 982 @SystemApi(client = MODULE_LIBRARIES) 983 public static final int FIREWALL_CHAIN_LOW_POWER_STANDBY = 5; 984 985 /** 986 * Firewall chain used for lockdown VPN. 987 * Denylist of apps that cannot receive incoming packets except on loopback because they are 988 * subject to an always-on VPN which is not currently connected. 989 * 990 * @see #BLOCKED_REASON_LOCKDOWN_VPN 991 * @hide 992 */ 993 public static final int FIREWALL_CHAIN_LOCKDOWN_VPN = 6; 994 995 /** 996 * Firewall chain used for OEM-specific application restrictions. 997 * Denylist of apps that will not have network access due to OEM-specific restrictions. 998 * @hide 999 */ 1000 public static final int FIREWALL_CHAIN_OEM_DENY_1 = 7; 1001 1002 /** 1003 * Firewall chain used for OEM-specific application restrictions. 1004 * Denylist of apps that will not have network access due to OEM-specific restrictions. 1005 * @hide 1006 */ 1007 public static final int FIREWALL_CHAIN_OEM_DENY_2 = 8; 1008 1009 /** 1010 * Firewall chain used for OEM-specific application restrictions. 1011 * Denylist of apps that will not have network access due to OEM-specific restrictions. 1012 * @hide 1013 */ 1014 public static final int FIREWALL_CHAIN_OEM_DENY_3 = 9; 1015 1016 /** @hide */ 1017 @Retention(RetentionPolicy.SOURCE) 1018 @IntDef(flag = false, prefix = "FIREWALL_CHAIN_", value = { 1019 FIREWALL_CHAIN_DOZABLE, 1020 FIREWALL_CHAIN_STANDBY, 1021 FIREWALL_CHAIN_POWERSAVE, 1022 FIREWALL_CHAIN_RESTRICTED, 1023 FIREWALL_CHAIN_LOW_POWER_STANDBY, 1024 FIREWALL_CHAIN_LOCKDOWN_VPN, 1025 FIREWALL_CHAIN_OEM_DENY_1, 1026 FIREWALL_CHAIN_OEM_DENY_2, 1027 FIREWALL_CHAIN_OEM_DENY_3 1028 }) 1029 public @interface FirewallChain {} 1030 // LINT.ThenChange(packages/modules/Connectivity/service/native/include/Common.h) 1031 1032 /** 1033 * A firewall rule which allows or drops packets depending on existing policy. 1034 * Used by {@link #setUidFirewallRule(int, int, int)} to follow existing policy to handle 1035 * specific uid's packets in specific firewall chain. 1036 * @hide 1037 */ 1038 @SystemApi(client = MODULE_LIBRARIES) 1039 public static final int FIREWALL_RULE_DEFAULT = 0; 1040 1041 /** 1042 * A firewall rule which allows packets. Used by {@link #setUidFirewallRule(int, int, int)} to 1043 * allow specific uid's packets in specific firewall chain. 1044 * @hide 1045 */ 1046 @SystemApi(client = MODULE_LIBRARIES) 1047 public static final int FIREWALL_RULE_ALLOW = 1; 1048 1049 /** 1050 * A firewall rule which drops packets. Used by {@link #setUidFirewallRule(int, int, int)} to 1051 * drop specific uid's packets in specific firewall chain. 1052 * @hide 1053 */ 1054 @SystemApi(client = MODULE_LIBRARIES) 1055 public static final int FIREWALL_RULE_DENY = 2; 1056 1057 /** @hide */ 1058 @Retention(RetentionPolicy.SOURCE) 1059 @IntDef(flag = false, prefix = "FIREWALL_RULE_", value = { 1060 FIREWALL_RULE_DEFAULT, 1061 FIREWALL_RULE_ALLOW, 1062 FIREWALL_RULE_DENY 1063 }) 1064 public @interface FirewallRule {} 1065 1066 /** 1067 * A kludge to facilitate static access where a Context pointer isn't available, like in the 1068 * case of the static set/getProcessDefaultNetwork methods and from the Network class. 1069 * TODO: Remove this after deprecating the static methods in favor of non-static methods or 1070 * methods that take a Context argument. 1071 */ 1072 private static ConnectivityManager sInstance; 1073 1074 private final Context mContext; 1075 1076 @GuardedBy("mTetheringEventCallbacks") 1077 private TetheringManager mTetheringManager; 1078 getTetheringManager()1079 private TetheringManager getTetheringManager() { 1080 synchronized (mTetheringEventCallbacks) { 1081 if (mTetheringManager == null) { 1082 mTetheringManager = mContext.getSystemService(TetheringManager.class); 1083 } 1084 return mTetheringManager; 1085 } 1086 } 1087 1088 /** 1089 * Tests if a given integer represents a valid network type. 1090 * @param networkType the type to be tested 1091 * @return a boolean. {@code true} if the type is valid, else {@code false} 1092 * @deprecated All APIs accepting a network type are deprecated. There should be no need to 1093 * validate a network type. 1094 */ 1095 @Deprecated isNetworkTypeValid(int networkType)1096 public static boolean isNetworkTypeValid(int networkType) { 1097 return MIN_NETWORK_TYPE <= networkType && networkType <= MAX_NETWORK_TYPE; 1098 } 1099 1100 /** 1101 * Returns a non-localized string representing a given network type. 1102 * ONLY used for debugging output. 1103 * @param type the type needing naming 1104 * @return a String for the given type, or a string version of the type ("87") 1105 * if no name is known. 1106 * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead. 1107 * {@hide} 1108 */ 1109 @Deprecated 1110 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) getNetworkTypeName(int type)1111 public static String getNetworkTypeName(int type) { 1112 switch (type) { 1113 case TYPE_NONE: 1114 return "NONE"; 1115 case TYPE_MOBILE: 1116 return "MOBILE"; 1117 case TYPE_WIFI: 1118 return "WIFI"; 1119 case TYPE_MOBILE_MMS: 1120 return "MOBILE_MMS"; 1121 case TYPE_MOBILE_SUPL: 1122 return "MOBILE_SUPL"; 1123 case TYPE_MOBILE_DUN: 1124 return "MOBILE_DUN"; 1125 case TYPE_MOBILE_HIPRI: 1126 return "MOBILE_HIPRI"; 1127 case TYPE_WIMAX: 1128 return "WIMAX"; 1129 case TYPE_BLUETOOTH: 1130 return "BLUETOOTH"; 1131 case TYPE_DUMMY: 1132 return "DUMMY"; 1133 case TYPE_ETHERNET: 1134 return "ETHERNET"; 1135 case TYPE_MOBILE_FOTA: 1136 return "MOBILE_FOTA"; 1137 case TYPE_MOBILE_IMS: 1138 return "MOBILE_IMS"; 1139 case TYPE_MOBILE_CBS: 1140 return "MOBILE_CBS"; 1141 case TYPE_WIFI_P2P: 1142 return "WIFI_P2P"; 1143 case TYPE_MOBILE_IA: 1144 return "MOBILE_IA"; 1145 case TYPE_MOBILE_EMERGENCY: 1146 return "MOBILE_EMERGENCY"; 1147 case TYPE_PROXY: 1148 return "PROXY"; 1149 case TYPE_VPN: 1150 return "VPN"; 1151 default: 1152 return Integer.toString(type); 1153 } 1154 } 1155 1156 /** 1157 * @hide 1158 */ 1159 @SystemApi(client = MODULE_LIBRARIES) systemReady()1160 public void systemReady() { 1161 try { 1162 mService.systemReady(); 1163 } catch (RemoteException e) { 1164 throw e.rethrowFromSystemServer(); 1165 } 1166 } 1167 1168 /** 1169 * Checks if a given type uses the cellular data connection. 1170 * This should be replaced in the future by a network property. 1171 * @param networkType the type to check 1172 * @return a boolean - {@code true} if uses cellular network, else {@code false} 1173 * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead. 1174 * {@hide} 1175 */ 1176 @Deprecated 1177 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 130143562) isNetworkTypeMobile(int networkType)1178 public static boolean isNetworkTypeMobile(int networkType) { 1179 switch (networkType) { 1180 case TYPE_MOBILE: 1181 case TYPE_MOBILE_MMS: 1182 case TYPE_MOBILE_SUPL: 1183 case TYPE_MOBILE_DUN: 1184 case TYPE_MOBILE_HIPRI: 1185 case TYPE_MOBILE_FOTA: 1186 case TYPE_MOBILE_IMS: 1187 case TYPE_MOBILE_CBS: 1188 case TYPE_MOBILE_IA: 1189 case TYPE_MOBILE_EMERGENCY: 1190 return true; 1191 default: 1192 return false; 1193 } 1194 } 1195 1196 /** 1197 * Checks if the given network type is backed by a Wi-Fi radio. 1198 * 1199 * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead. 1200 * @hide 1201 */ 1202 @Deprecated isNetworkTypeWifi(int networkType)1203 public static boolean isNetworkTypeWifi(int networkType) { 1204 switch (networkType) { 1205 case TYPE_WIFI: 1206 case TYPE_WIFI_P2P: 1207 return true; 1208 default: 1209 return false; 1210 } 1211 } 1212 1213 /** 1214 * Preference for {@link ProfileNetworkPreference#setPreference(int)}. 1215 * {@see #setProfileNetworkPreferences(UserHandle, List, Executor, Runnable)} 1216 * Specify that the traffic for this user should by follow the default rules. 1217 * @hide 1218 */ 1219 @SystemApi(client = MODULE_LIBRARIES) 1220 public static final int PROFILE_NETWORK_PREFERENCE_DEFAULT = 0; 1221 1222 /** 1223 * Preference for {@link ProfileNetworkPreference#setPreference(int)}. 1224 * {@see #setProfileNetworkPreferences(UserHandle, List, Executor, Runnable)} 1225 * Specify that the traffic for this user should by default go on a network with 1226 * {@link NetworkCapabilities#NET_CAPABILITY_ENTERPRISE}, and on the system default network 1227 * if no such network is available. 1228 * @hide 1229 */ 1230 @SystemApi(client = MODULE_LIBRARIES) 1231 public static final int PROFILE_NETWORK_PREFERENCE_ENTERPRISE = 1; 1232 1233 /** 1234 * Preference for {@link ProfileNetworkPreference#setPreference(int)}. 1235 * {@see #setProfileNetworkPreferences(UserHandle, List, Executor, Runnable)} 1236 * Specify that the traffic for this user should by default go on a network with 1237 * {@link NetworkCapabilities#NET_CAPABILITY_ENTERPRISE} and if no such network is available 1238 * should not go on the system default network 1239 * @hide 1240 */ 1241 @SystemApi(client = MODULE_LIBRARIES) 1242 public static final int PROFILE_NETWORK_PREFERENCE_ENTERPRISE_NO_FALLBACK = 2; 1243 1244 /** @hide */ 1245 @Retention(RetentionPolicy.SOURCE) 1246 @IntDef(value = { 1247 PROFILE_NETWORK_PREFERENCE_DEFAULT, 1248 PROFILE_NETWORK_PREFERENCE_ENTERPRISE, 1249 PROFILE_NETWORK_PREFERENCE_ENTERPRISE_NO_FALLBACK 1250 }) 1251 public @interface ProfileNetworkPreferencePolicy { 1252 } 1253 1254 /** 1255 * Specifies the preferred network type. When the device has more 1256 * than one type available the preferred network type will be used. 1257 * 1258 * @param preference the network type to prefer over all others. It is 1259 * unspecified what happens to the old preferred network in the 1260 * overall ordering. 1261 * @deprecated Functionality has been removed as it no longer makes sense, 1262 * with many more than two networks - we'd need an array to express 1263 * preference. Instead we use dynamic network properties of 1264 * the networks to describe their precedence. 1265 */ 1266 @Deprecated setNetworkPreference(int preference)1267 public void setNetworkPreference(int preference) { 1268 } 1269 1270 /** 1271 * Retrieves the current preferred network type. 1272 * 1273 * @return an integer representing the preferred network type 1274 * 1275 * @deprecated Functionality has been removed as it no longer makes sense, 1276 * with many more than two networks - we'd need an array to express 1277 * preference. Instead we use dynamic network properties of 1278 * the networks to describe their precedence. 1279 */ 1280 @Deprecated 1281 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) getNetworkPreference()1282 public int getNetworkPreference() { 1283 return TYPE_NONE; 1284 } 1285 1286 /** 1287 * Returns details about the currently active default data network. When 1288 * connected, this network is the default route for outgoing connections. 1289 * You should always check {@link NetworkInfo#isConnected()} before initiating 1290 * network traffic. This may return {@code null} when there is no default 1291 * network. 1292 * Note that if the default network is a VPN, this method will return the 1293 * NetworkInfo for one of its underlying networks instead, or null if the 1294 * VPN agent did not specify any. Apps interested in learning about VPNs 1295 * should use {@link #getNetworkInfo(android.net.Network)} instead. 1296 * 1297 * @return a {@link NetworkInfo} object for the current default network 1298 * or {@code null} if no default network is currently active 1299 * @deprecated See {@link NetworkInfo}. 1300 */ 1301 @Deprecated 1302 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1303 @Nullable getActiveNetworkInfo()1304 public NetworkInfo getActiveNetworkInfo() { 1305 try { 1306 return mService.getActiveNetworkInfo(); 1307 } catch (RemoteException e) { 1308 throw e.rethrowFromSystemServer(); 1309 } 1310 } 1311 1312 /** 1313 * Returns a {@link Network} object corresponding to the currently active 1314 * default data network. In the event that the current active default data 1315 * network disconnects, the returned {@code Network} object will no longer 1316 * be usable. This will return {@code null} when there is no default 1317 * network, or when the default network is blocked. 1318 * 1319 * @return a {@link Network} object for the current default network or 1320 * {@code null} if no default network is currently active or if 1321 * the default network is blocked for the caller 1322 */ 1323 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1324 @Nullable getActiveNetwork()1325 public Network getActiveNetwork() { 1326 try { 1327 return mService.getActiveNetwork(); 1328 } catch (RemoteException e) { 1329 throw e.rethrowFromSystemServer(); 1330 } 1331 } 1332 1333 /** 1334 * Returns a {@link Network} object corresponding to the currently active 1335 * default data network for a specific UID. In the event that the default data 1336 * network disconnects, the returned {@code Network} object will no longer 1337 * be usable. This will return {@code null} when there is no default 1338 * network for the UID. 1339 * 1340 * @return a {@link Network} object for the current default network for the 1341 * given UID or {@code null} if no default network is currently active 1342 * 1343 * @hide 1344 */ 1345 @RequiresPermission(android.Manifest.permission.NETWORK_STACK) 1346 @Nullable getActiveNetworkForUid(int uid)1347 public Network getActiveNetworkForUid(int uid) { 1348 return getActiveNetworkForUid(uid, false); 1349 } 1350 1351 /** {@hide} */ getActiveNetworkForUid(int uid, boolean ignoreBlocked)1352 public Network getActiveNetworkForUid(int uid, boolean ignoreBlocked) { 1353 try { 1354 return mService.getActiveNetworkForUid(uid, ignoreBlocked); 1355 } catch (RemoteException e) { 1356 throw e.rethrowFromSystemServer(); 1357 } 1358 } 1359 1360 /** 1361 * Adds or removes a requirement for given UID ranges to use the VPN. 1362 * 1363 * If set to {@code true}, informs the system that the UIDs in the specified ranges must not 1364 * have any connectivity except if a VPN is connected and applies to the UIDs, or if the UIDs 1365 * otherwise have permission to bypass the VPN (e.g., because they have the 1366 * {@link android.Manifest.permission.CONNECTIVITY_USE_RESTRICTED_NETWORKS} permission, or when 1367 * using a socket protected by a method such as {@link VpnService#protect(DatagramSocket)}. If 1368 * set to {@code false}, a previously-added restriction is removed. 1369 * <p> 1370 * Each of the UID ranges specified by this method is added and removed as is, and no processing 1371 * is performed on the ranges to de-duplicate, merge, split, or intersect them. In order to 1372 * remove a previously-added range, the exact range must be removed as is. 1373 * <p> 1374 * The changes are applied asynchronously and may not have been applied by the time the method 1375 * returns. Apps will be notified about any changes that apply to them via 1376 * {@link NetworkCallback#onBlockedStatusChanged} callbacks called after the changes take 1377 * effect. 1378 * <p> 1379 * This method should be called only by the VPN code. 1380 * 1381 * @param ranges the UID ranges to restrict 1382 * @param requireVpn whether the specified UID ranges must use a VPN 1383 * 1384 * @hide 1385 */ 1386 @RequiresPermission(anyOf = { 1387 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 1388 android.Manifest.permission.NETWORK_STACK, 1389 android.Manifest.permission.NETWORK_SETTINGS}) 1390 @SystemApi(client = MODULE_LIBRARIES) setRequireVpnForUids(boolean requireVpn, @NonNull Collection<Range<Integer>> ranges)1391 public void setRequireVpnForUids(boolean requireVpn, 1392 @NonNull Collection<Range<Integer>> ranges) { 1393 Objects.requireNonNull(ranges); 1394 // The Range class is not parcelable. Convert to UidRange, which is what is used internally. 1395 // This method is not necessarily expected to be used outside the system server, so 1396 // parceling may not be necessary, but it could be used out-of-process, e.g., by the network 1397 // stack process, or by tests. 1398 UidRange[] rangesArray = new UidRange[ranges.size()]; 1399 int index = 0; 1400 for (Range<Integer> range : ranges) { 1401 rangesArray[index++] = new UidRange(range.getLower(), range.getUpper()); 1402 } 1403 try { 1404 mService.setRequireVpnForUids(requireVpn, rangesArray); 1405 } catch (RemoteException e) { 1406 throw e.rethrowFromSystemServer(); 1407 } 1408 } 1409 1410 /** 1411 * Informs ConnectivityService of whether the legacy lockdown VPN, as implemented by 1412 * LockdownVpnTracker, is in use. This is deprecated for new devices starting from Android 12 1413 * but is still supported for backwards compatibility. 1414 * <p> 1415 * This type of VPN is assumed always to use the system default network, and must always declare 1416 * exactly one underlying network, which is the network that was the default when the VPN 1417 * connected. 1418 * <p> 1419 * Calling this method with {@code true} enables legacy behaviour, specifically: 1420 * <ul> 1421 * <li>Any VPN that applies to userId 0 behaves specially with respect to deprecated 1422 * {@link #CONNECTIVITY_ACTION} broadcasts. Any such broadcasts will have the state in the 1423 * {@link #EXTRA_NETWORK_INFO} replaced by state of the VPN network. Also, any time the VPN 1424 * connects, a {@link #CONNECTIVITY_ACTION} broadcast will be sent for the network 1425 * underlying the VPN.</li> 1426 * <li>Deprecated APIs that return {@link NetworkInfo} objects will have their state 1427 * similarly replaced by the VPN network state.</li> 1428 * <li>Information on current network interfaces passed to NetworkStatsService will not 1429 * include any VPN interfaces.</li> 1430 * </ul> 1431 * 1432 * @param enabled whether legacy lockdown VPN is enabled or disabled 1433 * 1434 * @hide 1435 */ 1436 @RequiresPermission(anyOf = { 1437 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 1438 android.Manifest.permission.NETWORK_STACK, 1439 android.Manifest.permission.NETWORK_SETTINGS}) 1440 @SystemApi(client = MODULE_LIBRARIES) setLegacyLockdownVpnEnabled(boolean enabled)1441 public void setLegacyLockdownVpnEnabled(boolean enabled) { 1442 try { 1443 mService.setLegacyLockdownVpnEnabled(enabled); 1444 } catch (RemoteException e) { 1445 throw e.rethrowFromSystemServer(); 1446 } 1447 } 1448 1449 /** 1450 * Returns details about the currently active default data network 1451 * for a given uid. This is for internal use only to avoid spying 1452 * other apps. 1453 * 1454 * @return a {@link NetworkInfo} object for the current default network 1455 * for the given uid or {@code null} if no default network is 1456 * available for the specified uid. 1457 * 1458 * {@hide} 1459 */ 1460 @RequiresPermission(android.Manifest.permission.NETWORK_STACK) 1461 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) getActiveNetworkInfoForUid(int uid)1462 public NetworkInfo getActiveNetworkInfoForUid(int uid) { 1463 return getActiveNetworkInfoForUid(uid, false); 1464 } 1465 1466 /** {@hide} */ getActiveNetworkInfoForUid(int uid, boolean ignoreBlocked)1467 public NetworkInfo getActiveNetworkInfoForUid(int uid, boolean ignoreBlocked) { 1468 try { 1469 return mService.getActiveNetworkInfoForUid(uid, ignoreBlocked); 1470 } catch (RemoteException e) { 1471 throw e.rethrowFromSystemServer(); 1472 } 1473 } 1474 1475 /** 1476 * Returns connection status information about a particular 1477 * network type. 1478 * 1479 * @param networkType integer specifying which networkType in 1480 * which you're interested. 1481 * @return a {@link NetworkInfo} object for the requested 1482 * network type or {@code null} if the type is not 1483 * supported by the device. If {@code networkType} is 1484 * TYPE_VPN and a VPN is active for the calling app, 1485 * then this method will try to return one of the 1486 * underlying networks for the VPN or null if the 1487 * VPN agent didn't specify any. 1488 * 1489 * @deprecated This method does not support multiple connected networks 1490 * of the same type. Use {@link #getAllNetworks} and 1491 * {@link #getNetworkInfo(android.net.Network)} instead. 1492 */ 1493 @Deprecated 1494 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1495 @Nullable getNetworkInfo(int networkType)1496 public NetworkInfo getNetworkInfo(int networkType) { 1497 try { 1498 return mService.getNetworkInfo(networkType); 1499 } catch (RemoteException e) { 1500 throw e.rethrowFromSystemServer(); 1501 } 1502 } 1503 1504 /** 1505 * Returns connection status information about a particular 1506 * Network. 1507 * 1508 * @param network {@link Network} specifying which network 1509 * in which you're interested. 1510 * @return a {@link NetworkInfo} object for the requested 1511 * network or {@code null} if the {@code Network} 1512 * is not valid. 1513 * @deprecated See {@link NetworkInfo}. 1514 */ 1515 @Deprecated 1516 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1517 @Nullable getNetworkInfo(@ullable Network network)1518 public NetworkInfo getNetworkInfo(@Nullable Network network) { 1519 return getNetworkInfoForUid(network, Process.myUid(), false); 1520 } 1521 1522 /** {@hide} */ getNetworkInfoForUid(Network network, int uid, boolean ignoreBlocked)1523 public NetworkInfo getNetworkInfoForUid(Network network, int uid, boolean ignoreBlocked) { 1524 try { 1525 return mService.getNetworkInfoForUid(network, uid, ignoreBlocked); 1526 } catch (RemoteException e) { 1527 throw e.rethrowFromSystemServer(); 1528 } 1529 } 1530 1531 /** 1532 * Returns connection status information about all network 1533 * types supported by the device. 1534 * 1535 * @return an array of {@link NetworkInfo} objects. Check each 1536 * {@link NetworkInfo#getType} for which type each applies. 1537 * 1538 * @deprecated This method does not support multiple connected networks 1539 * of the same type. Use {@link #getAllNetworks} and 1540 * {@link #getNetworkInfo(android.net.Network)} instead. 1541 */ 1542 @Deprecated 1543 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1544 @NonNull getAllNetworkInfo()1545 public NetworkInfo[] getAllNetworkInfo() { 1546 try { 1547 return mService.getAllNetworkInfo(); 1548 } catch (RemoteException e) { 1549 throw e.rethrowFromSystemServer(); 1550 } 1551 } 1552 1553 /** 1554 * Return a list of {@link NetworkStateSnapshot}s, one for each network that is currently 1555 * connected. 1556 * @hide 1557 */ 1558 @SystemApi(client = MODULE_LIBRARIES) 1559 @RequiresPermission(anyOf = { 1560 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 1561 android.Manifest.permission.NETWORK_STACK, 1562 android.Manifest.permission.NETWORK_SETTINGS}) 1563 @NonNull getAllNetworkStateSnapshots()1564 public List<NetworkStateSnapshot> getAllNetworkStateSnapshots() { 1565 try { 1566 return mService.getAllNetworkStateSnapshots(); 1567 } catch (RemoteException e) { 1568 throw e.rethrowFromSystemServer(); 1569 } 1570 } 1571 1572 /** 1573 * Returns the {@link Network} object currently serving a given type, or 1574 * null if the given type is not connected. 1575 * 1576 * @hide 1577 * @deprecated This method does not support multiple connected networks 1578 * of the same type. Use {@link #getAllNetworks} and 1579 * {@link #getNetworkInfo(android.net.Network)} instead. 1580 */ 1581 @Deprecated 1582 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1583 @UnsupportedAppUsage getNetworkForType(int networkType)1584 public Network getNetworkForType(int networkType) { 1585 try { 1586 return mService.getNetworkForType(networkType); 1587 } catch (RemoteException e) { 1588 throw e.rethrowFromSystemServer(); 1589 } 1590 } 1591 1592 /** 1593 * Returns an array of all {@link Network} currently tracked by the 1594 * framework. 1595 * 1596 * @deprecated This method does not provide any notification of network state changes, forcing 1597 * apps to call it repeatedly. This is inefficient and prone to race conditions. 1598 * Apps should use methods such as 1599 * {@link #registerNetworkCallback(NetworkRequest, NetworkCallback)} instead. 1600 * Apps that desire to obtain information about networks that do not apply to them 1601 * can use {@link NetworkRequest.Builder#setIncludeOtherUidNetworks}. 1602 * 1603 * @return an array of {@link Network} objects. 1604 */ 1605 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1606 @NonNull 1607 @Deprecated getAllNetworks()1608 public Network[] getAllNetworks() { 1609 try { 1610 return mService.getAllNetworks(); 1611 } catch (RemoteException e) { 1612 throw e.rethrowFromSystemServer(); 1613 } 1614 } 1615 1616 /** 1617 * Returns an array of {@link NetworkCapabilities} objects, representing 1618 * the Networks that applications run by the given user will use by default. 1619 * @hide 1620 */ 1621 @UnsupportedAppUsage getDefaultNetworkCapabilitiesForUser(int userId)1622 public NetworkCapabilities[] getDefaultNetworkCapabilitiesForUser(int userId) { 1623 try { 1624 return mService.getDefaultNetworkCapabilitiesForUser( 1625 userId, mContext.getOpPackageName(), getAttributionTag()); 1626 } catch (RemoteException e) { 1627 throw e.rethrowFromSystemServer(); 1628 } 1629 } 1630 1631 /** 1632 * Returns the IP information for the current default network. 1633 * 1634 * @return a {@link LinkProperties} object describing the IP info 1635 * for the current default network, or {@code null} if there 1636 * is no current default network. 1637 * 1638 * {@hide} 1639 * @deprecated please use {@link #getLinkProperties(Network)} on the return 1640 * value of {@link #getActiveNetwork()} instead. In particular, 1641 * this method will return non-null LinkProperties even if the 1642 * app is blocked by policy from using this network. 1643 */ 1644 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1645 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 109783091) getActiveLinkProperties()1646 public LinkProperties getActiveLinkProperties() { 1647 try { 1648 return mService.getActiveLinkProperties(); 1649 } catch (RemoteException e) { 1650 throw e.rethrowFromSystemServer(); 1651 } 1652 } 1653 1654 /** 1655 * Returns the IP information for a given network type. 1656 * 1657 * @param networkType the network type of interest. 1658 * @return a {@link LinkProperties} object describing the IP info 1659 * for the given networkType, or {@code null} if there is 1660 * no current default network. 1661 * 1662 * {@hide} 1663 * @deprecated This method does not support multiple connected networks 1664 * of the same type. Use {@link #getAllNetworks}, 1665 * {@link #getNetworkInfo(android.net.Network)}, and 1666 * {@link #getLinkProperties(android.net.Network)} instead. 1667 */ 1668 @Deprecated 1669 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1670 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 130143562) getLinkProperties(int networkType)1671 public LinkProperties getLinkProperties(int networkType) { 1672 try { 1673 return mService.getLinkPropertiesForType(networkType); 1674 } catch (RemoteException e) { 1675 throw e.rethrowFromSystemServer(); 1676 } 1677 } 1678 1679 /** 1680 * Get the {@link LinkProperties} for the given {@link Network}. This 1681 * will return {@code null} if the network is unknown. 1682 * 1683 * @param network The {@link Network} object identifying the network in question. 1684 * @return The {@link LinkProperties} for the network, or {@code null}. 1685 */ 1686 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1687 @Nullable getLinkProperties(@ullable Network network)1688 public LinkProperties getLinkProperties(@Nullable Network network) { 1689 try { 1690 return mService.getLinkProperties(network); 1691 } catch (RemoteException e) { 1692 throw e.rethrowFromSystemServer(); 1693 } 1694 } 1695 1696 /** 1697 * Redact {@link LinkProperties} for a given package 1698 * 1699 * Returns an instance of the given {@link LinkProperties} appropriately redacted to send to the 1700 * given package, considering its permissions. 1701 * 1702 * @param lp A {@link LinkProperties} which will be redacted. 1703 * @param uid The target uid. 1704 * @param packageName The name of the package, for appops logging. 1705 * @return A redacted {@link LinkProperties} which is appropriate to send to the given uid, 1706 * or null if the uid lacks the ACCESS_NETWORK_STATE permission. 1707 * @hide 1708 */ 1709 @RequiresPermission(anyOf = { 1710 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 1711 android.Manifest.permission.NETWORK_STACK, 1712 android.Manifest.permission.NETWORK_SETTINGS}) 1713 @SystemApi(client = MODULE_LIBRARIES) 1714 @Nullable getRedactedLinkPropertiesForPackage(@onNull LinkProperties lp, int uid, @NonNull String packageName)1715 public LinkProperties getRedactedLinkPropertiesForPackage(@NonNull LinkProperties lp, int uid, 1716 @NonNull String packageName) { 1717 try { 1718 return mService.getRedactedLinkPropertiesForPackage( 1719 lp, uid, packageName, getAttributionTag()); 1720 } catch (RemoteException e) { 1721 throw e.rethrowFromSystemServer(); 1722 } 1723 } 1724 1725 /** 1726 * Get the {@link NetworkCapabilities} for the given {@link Network}, or null. 1727 * 1728 * This will remove any location sensitive data in the returned {@link NetworkCapabilities}. 1729 * Some {@link TransportInfo} instances like {@link android.net.wifi.WifiInfo} contain location 1730 * sensitive information. To retrieve this location sensitive information (subject to 1731 * the caller's location permissions), use a {@link NetworkCallback} with the 1732 * {@link NetworkCallback#FLAG_INCLUDE_LOCATION_INFO} flag instead. 1733 * 1734 * This method returns {@code null} if the network is unknown or if the |network| argument 1735 * is null. 1736 * 1737 * @param network The {@link Network} object identifying the network in question. 1738 * @return The {@link NetworkCapabilities} for the network, or {@code null}. 1739 */ 1740 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 1741 @Nullable getNetworkCapabilities(@ullable Network network)1742 public NetworkCapabilities getNetworkCapabilities(@Nullable Network network) { 1743 try { 1744 return mService.getNetworkCapabilities( 1745 network, mContext.getOpPackageName(), getAttributionTag()); 1746 } catch (RemoteException e) { 1747 throw e.rethrowFromSystemServer(); 1748 } 1749 } 1750 1751 /** 1752 * Redact {@link NetworkCapabilities} for a given package. 1753 * 1754 * Returns an instance of {@link NetworkCapabilities} that is appropriately redacted to send 1755 * to the given package, considering its permissions. If the passed capabilities contain 1756 * location-sensitive information, they will be redacted to the correct degree for the location 1757 * permissions of the app (COARSE or FINE), and will blame the UID accordingly for retrieving 1758 * that level of location. If the UID holds no location permission, the returned object will 1759 * contain no location-sensitive information and the UID is not blamed. 1760 * 1761 * @param nc A {@link NetworkCapabilities} instance which will be redacted. 1762 * @param uid The target uid. 1763 * @param packageName The name of the package, for appops logging. 1764 * @return A redacted {@link NetworkCapabilities} which is appropriate to send to the given uid, 1765 * or null if the uid lacks the ACCESS_NETWORK_STATE permission. 1766 * @hide 1767 */ 1768 @RequiresPermission(anyOf = { 1769 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 1770 android.Manifest.permission.NETWORK_STACK, 1771 android.Manifest.permission.NETWORK_SETTINGS}) 1772 @SystemApi(client = MODULE_LIBRARIES) 1773 @Nullable getRedactedNetworkCapabilitiesForPackage( @onNull NetworkCapabilities nc, int uid, @NonNull String packageName)1774 public NetworkCapabilities getRedactedNetworkCapabilitiesForPackage( 1775 @NonNull NetworkCapabilities nc, 1776 int uid, @NonNull String packageName) { 1777 try { 1778 return mService.getRedactedNetworkCapabilitiesForPackage(nc, uid, packageName, 1779 getAttributionTag()); 1780 } catch (RemoteException e) { 1781 throw e.rethrowFromSystemServer(); 1782 } 1783 } 1784 1785 /** 1786 * Gets a URL that can be used for resolving whether a captive portal is present. 1787 * 1. This URL should respond with a 204 response to a GET request to indicate no captive 1788 * portal is present. 1789 * 2. This URL must be HTTP as redirect responses are used to find captive portal 1790 * sign-in pages. Captive portals cannot respond to HTTPS requests with redirects. 1791 * 1792 * The system network validation may be using different strategies to detect captive portals, 1793 * so this method does not necessarily return a URL used by the system. It only returns a URL 1794 * that may be relevant for other components trying to detect captive portals. 1795 * 1796 * @hide 1797 * @deprecated This API returns URL which is not guaranteed to be one of the URLs used by the 1798 * system. 1799 */ 1800 @Deprecated 1801 @SystemApi 1802 @RequiresPermission(android.Manifest.permission.NETWORK_SETTINGS) getCaptivePortalServerUrl()1803 public String getCaptivePortalServerUrl() { 1804 try { 1805 return mService.getCaptivePortalServerUrl(); 1806 } catch (RemoteException e) { 1807 throw e.rethrowFromSystemServer(); 1808 } 1809 } 1810 1811 /** 1812 * Tells the underlying networking system that the caller wants to 1813 * begin using the named feature. The interpretation of {@code feature} 1814 * is completely up to each networking implementation. 1815 * 1816 * <p>This method requires the caller to hold either the 1817 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 1818 * or the ability to modify system settings as determined by 1819 * {@link android.provider.Settings.System#canWrite}.</p> 1820 * 1821 * @param networkType specifies which network the request pertains to 1822 * @param feature the name of the feature to be used 1823 * @return an integer value representing the outcome of the request. 1824 * The interpretation of this value is specific to each networking 1825 * implementation+feature combination, except that the value {@code -1} 1826 * always indicates failure. 1827 * 1828 * @deprecated Deprecated in favor of the cleaner 1829 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} API. 1830 * In {@link VERSION_CODES#M}, and above, this method is unsupported and will 1831 * throw {@code UnsupportedOperationException} if called. 1832 * @removed 1833 */ 1834 @Deprecated startUsingNetworkFeature(int networkType, String feature)1835 public int startUsingNetworkFeature(int networkType, String feature) { 1836 checkLegacyRoutingApiAccess(); 1837 NetworkCapabilities netCap = networkCapabilitiesForFeature(networkType, feature); 1838 if (netCap == null) { 1839 Log.d(TAG, "Can't satisfy startUsingNetworkFeature for " + networkType + ", " + 1840 feature); 1841 return DEPRECATED_PHONE_CONSTANT_APN_REQUEST_FAILED; 1842 } 1843 1844 NetworkRequest request = null; 1845 synchronized (sLegacyRequests) { 1846 LegacyRequest l = sLegacyRequests.get(netCap); 1847 if (l != null) { 1848 Log.d(TAG, "renewing startUsingNetworkFeature request " + l.networkRequest); 1849 renewRequestLocked(l); 1850 if (l.currentNetwork != null) { 1851 return DEPRECATED_PHONE_CONSTANT_APN_ALREADY_ACTIVE; 1852 } else { 1853 return DEPRECATED_PHONE_CONSTANT_APN_REQUEST_STARTED; 1854 } 1855 } 1856 1857 request = requestNetworkForFeatureLocked(netCap); 1858 } 1859 if (request != null) { 1860 Log.d(TAG, "starting startUsingNetworkFeature for request " + request); 1861 return DEPRECATED_PHONE_CONSTANT_APN_REQUEST_STARTED; 1862 } else { 1863 Log.d(TAG, " request Failed"); 1864 return DEPRECATED_PHONE_CONSTANT_APN_REQUEST_FAILED; 1865 } 1866 } 1867 1868 /** 1869 * Tells the underlying networking system that the caller is finished 1870 * using the named feature. The interpretation of {@code feature} 1871 * is completely up to each networking implementation. 1872 * 1873 * <p>This method requires the caller to hold either the 1874 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 1875 * or the ability to modify system settings as determined by 1876 * {@link android.provider.Settings.System#canWrite}.</p> 1877 * 1878 * @param networkType specifies which network the request pertains to 1879 * @param feature the name of the feature that is no longer needed 1880 * @return an integer value representing the outcome of the request. 1881 * The interpretation of this value is specific to each networking 1882 * implementation+feature combination, except that the value {@code -1} 1883 * always indicates failure. 1884 * 1885 * @deprecated Deprecated in favor of the cleaner 1886 * {@link #unregisterNetworkCallback(NetworkCallback)} API. 1887 * In {@link VERSION_CODES#M}, and above, this method is unsupported and will 1888 * throw {@code UnsupportedOperationException} if called. 1889 * @removed 1890 */ 1891 @Deprecated stopUsingNetworkFeature(int networkType, String feature)1892 public int stopUsingNetworkFeature(int networkType, String feature) { 1893 checkLegacyRoutingApiAccess(); 1894 NetworkCapabilities netCap = networkCapabilitiesForFeature(networkType, feature); 1895 if (netCap == null) { 1896 Log.d(TAG, "Can't satisfy stopUsingNetworkFeature for " + networkType + ", " + 1897 feature); 1898 return -1; 1899 } 1900 1901 if (removeRequestForFeature(netCap)) { 1902 Log.d(TAG, "stopUsingNetworkFeature for " + networkType + ", " + feature); 1903 } 1904 return 1; 1905 } 1906 1907 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) networkCapabilitiesForFeature(int networkType, String feature)1908 private NetworkCapabilities networkCapabilitiesForFeature(int networkType, String feature) { 1909 if (networkType == TYPE_MOBILE) { 1910 switch (feature) { 1911 case "enableCBS": 1912 return networkCapabilitiesForType(TYPE_MOBILE_CBS); 1913 case "enableDUN": 1914 case "enableDUNAlways": 1915 return networkCapabilitiesForType(TYPE_MOBILE_DUN); 1916 case "enableFOTA": 1917 return networkCapabilitiesForType(TYPE_MOBILE_FOTA); 1918 case "enableHIPRI": 1919 return networkCapabilitiesForType(TYPE_MOBILE_HIPRI); 1920 case "enableIMS": 1921 return networkCapabilitiesForType(TYPE_MOBILE_IMS); 1922 case "enableMMS": 1923 return networkCapabilitiesForType(TYPE_MOBILE_MMS); 1924 case "enableSUPL": 1925 return networkCapabilitiesForType(TYPE_MOBILE_SUPL); 1926 default: 1927 return null; 1928 } 1929 } else if (networkType == TYPE_WIFI && "p2p".equals(feature)) { 1930 return networkCapabilitiesForType(TYPE_WIFI_P2P); 1931 } 1932 return null; 1933 } 1934 legacyTypeForNetworkCapabilities(NetworkCapabilities netCap)1935 private int legacyTypeForNetworkCapabilities(NetworkCapabilities netCap) { 1936 if (netCap == null) return TYPE_NONE; 1937 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_CBS)) { 1938 return TYPE_MOBILE_CBS; 1939 } 1940 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_IMS)) { 1941 return TYPE_MOBILE_IMS; 1942 } 1943 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_FOTA)) { 1944 return TYPE_MOBILE_FOTA; 1945 } 1946 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_DUN)) { 1947 return TYPE_MOBILE_DUN; 1948 } 1949 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_SUPL)) { 1950 return TYPE_MOBILE_SUPL; 1951 } 1952 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_MMS)) { 1953 return TYPE_MOBILE_MMS; 1954 } 1955 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)) { 1956 return TYPE_MOBILE_HIPRI; 1957 } 1958 if (netCap.hasCapability(NetworkCapabilities.NET_CAPABILITY_WIFI_P2P)) { 1959 return TYPE_WIFI_P2P; 1960 } 1961 return TYPE_NONE; 1962 } 1963 1964 private static class LegacyRequest { 1965 NetworkCapabilities networkCapabilities; 1966 NetworkRequest networkRequest; 1967 int expireSequenceNumber; 1968 Network currentNetwork; 1969 int delay = -1; 1970 clearDnsBinding()1971 private void clearDnsBinding() { 1972 if (currentNetwork != null) { 1973 currentNetwork = null; 1974 setProcessDefaultNetworkForHostResolution(null); 1975 } 1976 } 1977 1978 NetworkCallback networkCallback = new NetworkCallback() { 1979 @Override 1980 public void onAvailable(Network network) { 1981 currentNetwork = network; 1982 Log.d(TAG, "startUsingNetworkFeature got Network:" + network); 1983 setProcessDefaultNetworkForHostResolution(network); 1984 } 1985 @Override 1986 public void onLost(Network network) { 1987 if (network.equals(currentNetwork)) clearDnsBinding(); 1988 Log.d(TAG, "startUsingNetworkFeature lost Network:" + network); 1989 } 1990 }; 1991 } 1992 1993 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 1994 private static final HashMap<NetworkCapabilities, LegacyRequest> sLegacyRequests = 1995 new HashMap<>(); 1996 findRequestForFeature(NetworkCapabilities netCap)1997 private NetworkRequest findRequestForFeature(NetworkCapabilities netCap) { 1998 synchronized (sLegacyRequests) { 1999 LegacyRequest l = sLegacyRequests.get(netCap); 2000 if (l != null) return l.networkRequest; 2001 } 2002 return null; 2003 } 2004 renewRequestLocked(LegacyRequest l)2005 private void renewRequestLocked(LegacyRequest l) { 2006 l.expireSequenceNumber++; 2007 Log.d(TAG, "renewing request to seqNum " + l.expireSequenceNumber); 2008 sendExpireMsgForFeature(l.networkCapabilities, l.expireSequenceNumber, l.delay); 2009 } 2010 expireRequest(NetworkCapabilities netCap, int sequenceNum)2011 private void expireRequest(NetworkCapabilities netCap, int sequenceNum) { 2012 int ourSeqNum = -1; 2013 synchronized (sLegacyRequests) { 2014 LegacyRequest l = sLegacyRequests.get(netCap); 2015 if (l == null) return; 2016 ourSeqNum = l.expireSequenceNumber; 2017 if (l.expireSequenceNumber == sequenceNum) removeRequestForFeature(netCap); 2018 } 2019 Log.d(TAG, "expireRequest with " + ourSeqNum + ", " + sequenceNum); 2020 } 2021 2022 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) requestNetworkForFeatureLocked(NetworkCapabilities netCap)2023 private NetworkRequest requestNetworkForFeatureLocked(NetworkCapabilities netCap) { 2024 int delay = -1; 2025 int type = legacyTypeForNetworkCapabilities(netCap); 2026 try { 2027 delay = mService.getRestoreDefaultNetworkDelay(type); 2028 } catch (RemoteException e) { 2029 throw e.rethrowFromSystemServer(); 2030 } 2031 LegacyRequest l = new LegacyRequest(); 2032 l.networkCapabilities = netCap; 2033 l.delay = delay; 2034 l.expireSequenceNumber = 0; 2035 l.networkRequest = sendRequestForNetwork( 2036 netCap, l.networkCallback, 0, REQUEST, type, getDefaultHandler()); 2037 if (l.networkRequest == null) return null; 2038 sLegacyRequests.put(netCap, l); 2039 sendExpireMsgForFeature(netCap, l.expireSequenceNumber, delay); 2040 return l.networkRequest; 2041 } 2042 sendExpireMsgForFeature(NetworkCapabilities netCap, int seqNum, int delay)2043 private void sendExpireMsgForFeature(NetworkCapabilities netCap, int seqNum, int delay) { 2044 if (delay >= 0) { 2045 Log.d(TAG, "sending expire msg with seqNum " + seqNum + " and delay " + delay); 2046 CallbackHandler handler = getDefaultHandler(); 2047 Message msg = handler.obtainMessage(EXPIRE_LEGACY_REQUEST, seqNum, 0, netCap); 2048 handler.sendMessageDelayed(msg, delay); 2049 } 2050 } 2051 2052 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) removeRequestForFeature(NetworkCapabilities netCap)2053 private boolean removeRequestForFeature(NetworkCapabilities netCap) { 2054 final LegacyRequest l; 2055 synchronized (sLegacyRequests) { 2056 l = sLegacyRequests.remove(netCap); 2057 } 2058 if (l == null) return false; 2059 unregisterNetworkCallback(l.networkCallback); 2060 l.clearDnsBinding(); 2061 return true; 2062 } 2063 2064 private static final SparseIntArray sLegacyTypeToTransport = new SparseIntArray(); 2065 static { sLegacyTypeToTransport.put(TYPE_MOBILE, NetworkCapabilities.TRANSPORT_CELLULAR)2066 sLegacyTypeToTransport.put(TYPE_MOBILE, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_MOBILE_CBS, NetworkCapabilities.TRANSPORT_CELLULAR)2067 sLegacyTypeToTransport.put(TYPE_MOBILE_CBS, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_MOBILE_DUN, NetworkCapabilities.TRANSPORT_CELLULAR)2068 sLegacyTypeToTransport.put(TYPE_MOBILE_DUN, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_MOBILE_FOTA, NetworkCapabilities.TRANSPORT_CELLULAR)2069 sLegacyTypeToTransport.put(TYPE_MOBILE_FOTA, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_MOBILE_HIPRI, NetworkCapabilities.TRANSPORT_CELLULAR)2070 sLegacyTypeToTransport.put(TYPE_MOBILE_HIPRI, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_MOBILE_IMS, NetworkCapabilities.TRANSPORT_CELLULAR)2071 sLegacyTypeToTransport.put(TYPE_MOBILE_IMS, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_MOBILE_MMS, NetworkCapabilities.TRANSPORT_CELLULAR)2072 sLegacyTypeToTransport.put(TYPE_MOBILE_MMS, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_MOBILE_SUPL, NetworkCapabilities.TRANSPORT_CELLULAR)2073 sLegacyTypeToTransport.put(TYPE_MOBILE_SUPL, NetworkCapabilities.TRANSPORT_CELLULAR); sLegacyTypeToTransport.put(TYPE_WIFI, NetworkCapabilities.TRANSPORT_WIFI)2074 sLegacyTypeToTransport.put(TYPE_WIFI, NetworkCapabilities.TRANSPORT_WIFI); sLegacyTypeToTransport.put(TYPE_WIFI_P2P, NetworkCapabilities.TRANSPORT_WIFI)2075 sLegacyTypeToTransport.put(TYPE_WIFI_P2P, NetworkCapabilities.TRANSPORT_WIFI); sLegacyTypeToTransport.put(TYPE_BLUETOOTH, NetworkCapabilities.TRANSPORT_BLUETOOTH)2076 sLegacyTypeToTransport.put(TYPE_BLUETOOTH, NetworkCapabilities.TRANSPORT_BLUETOOTH); sLegacyTypeToTransport.put(TYPE_ETHERNET, NetworkCapabilities.TRANSPORT_ETHERNET)2077 sLegacyTypeToTransport.put(TYPE_ETHERNET, NetworkCapabilities.TRANSPORT_ETHERNET); 2078 } 2079 2080 private static final SparseIntArray sLegacyTypeToCapability = new SparseIntArray(); 2081 static { sLegacyTypeToCapability.put(TYPE_MOBILE_CBS, NetworkCapabilities.NET_CAPABILITY_CBS)2082 sLegacyTypeToCapability.put(TYPE_MOBILE_CBS, NetworkCapabilities.NET_CAPABILITY_CBS); sLegacyTypeToCapability.put(TYPE_MOBILE_DUN, NetworkCapabilities.NET_CAPABILITY_DUN)2083 sLegacyTypeToCapability.put(TYPE_MOBILE_DUN, NetworkCapabilities.NET_CAPABILITY_DUN); sLegacyTypeToCapability.put(TYPE_MOBILE_FOTA, NetworkCapabilities.NET_CAPABILITY_FOTA)2084 sLegacyTypeToCapability.put(TYPE_MOBILE_FOTA, NetworkCapabilities.NET_CAPABILITY_FOTA); sLegacyTypeToCapability.put(TYPE_MOBILE_IMS, NetworkCapabilities.NET_CAPABILITY_IMS)2085 sLegacyTypeToCapability.put(TYPE_MOBILE_IMS, NetworkCapabilities.NET_CAPABILITY_IMS); sLegacyTypeToCapability.put(TYPE_MOBILE_MMS, NetworkCapabilities.NET_CAPABILITY_MMS)2086 sLegacyTypeToCapability.put(TYPE_MOBILE_MMS, NetworkCapabilities.NET_CAPABILITY_MMS); sLegacyTypeToCapability.put(TYPE_MOBILE_SUPL, NetworkCapabilities.NET_CAPABILITY_SUPL)2087 sLegacyTypeToCapability.put(TYPE_MOBILE_SUPL, NetworkCapabilities.NET_CAPABILITY_SUPL); sLegacyTypeToCapability.put(TYPE_WIFI_P2P, NetworkCapabilities.NET_CAPABILITY_WIFI_P2P)2088 sLegacyTypeToCapability.put(TYPE_WIFI_P2P, NetworkCapabilities.NET_CAPABILITY_WIFI_P2P); 2089 } 2090 2091 /** 2092 * Given a legacy type (TYPE_WIFI, ...) returns a NetworkCapabilities 2093 * instance suitable for registering a request or callback. Throws an 2094 * IllegalArgumentException if no mapping from the legacy type to 2095 * NetworkCapabilities is known. 2096 * 2097 * @deprecated Types are deprecated. Use {@link NetworkCallback} or {@link NetworkRequest} 2098 * to find the network instead. 2099 * @hide 2100 */ networkCapabilitiesForType(int type)2101 public static NetworkCapabilities networkCapabilitiesForType(int type) { 2102 final NetworkCapabilities nc = new NetworkCapabilities(); 2103 2104 // Map from type to transports. 2105 final int NOT_FOUND = -1; 2106 final int transport = sLegacyTypeToTransport.get(type, NOT_FOUND); 2107 if (transport == NOT_FOUND) { 2108 throw new IllegalArgumentException("unknown legacy type: " + type); 2109 } 2110 nc.addTransportType(transport); 2111 2112 // Map from type to capabilities. 2113 nc.addCapability(sLegacyTypeToCapability.get( 2114 type, NetworkCapabilities.NET_CAPABILITY_INTERNET)); 2115 nc.maybeMarkCapabilitiesRestricted(); 2116 return nc; 2117 } 2118 2119 /** @hide */ 2120 public static class PacketKeepaliveCallback { 2121 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) PacketKeepaliveCallback()2122 public PacketKeepaliveCallback() { 2123 } 2124 /** The requested keepalive was successfully started. */ 2125 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) onStarted()2126 public void onStarted() {} 2127 /** The keepalive was successfully stopped. */ 2128 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) onStopped()2129 public void onStopped() {} 2130 /** An error occurred. */ 2131 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) onError(int error)2132 public void onError(int error) {} 2133 } 2134 2135 /** 2136 * Allows applications to request that the system periodically send specific packets on their 2137 * behalf, using hardware offload to save battery power. 2138 * 2139 * To request that the system send keepalives, call one of the methods that return a 2140 * {@link ConnectivityManager.PacketKeepalive} object, such as {@link #startNattKeepalive}, 2141 * passing in a non-null callback. If the callback is successfully started, the callback's 2142 * {@code onStarted} method will be called. If an error occurs, {@code onError} will be called, 2143 * specifying one of the {@code ERROR_*} constants in this class. 2144 * 2145 * To stop an existing keepalive, call {@link PacketKeepalive#stop}. The system will call 2146 * {@link PacketKeepaliveCallback#onStopped} if the operation was successful or 2147 * {@link PacketKeepaliveCallback#onError} if an error occurred. 2148 * 2149 * @deprecated Use {@link SocketKeepalive} instead. 2150 * 2151 * @hide 2152 */ 2153 public class PacketKeepalive { 2154 2155 private static final String TAG = "PacketKeepalive"; 2156 2157 /** @hide */ 2158 public static final int SUCCESS = 0; 2159 2160 /** @hide */ 2161 public static final int NO_KEEPALIVE = -1; 2162 2163 /** @hide */ 2164 public static final int BINDER_DIED = -10; 2165 2166 /** The specified {@code Network} is not connected. */ 2167 public static final int ERROR_INVALID_NETWORK = -20; 2168 /** The specified IP addresses are invalid. For example, the specified source IP address is 2169 * not configured on the specified {@code Network}. */ 2170 public static final int ERROR_INVALID_IP_ADDRESS = -21; 2171 /** The requested port is invalid. */ 2172 public static final int ERROR_INVALID_PORT = -22; 2173 /** The packet length is invalid (e.g., too long). */ 2174 public static final int ERROR_INVALID_LENGTH = -23; 2175 /** The packet transmission interval is invalid (e.g., too short). */ 2176 public static final int ERROR_INVALID_INTERVAL = -24; 2177 2178 /** The hardware does not support this request. */ 2179 public static final int ERROR_HARDWARE_UNSUPPORTED = -30; 2180 /** The hardware returned an error. */ 2181 public static final int ERROR_HARDWARE_ERROR = -31; 2182 2183 /** The NAT-T destination port for IPsec */ 2184 public static final int NATT_PORT = 4500; 2185 2186 /** The minimum interval in seconds between keepalive packet transmissions */ 2187 public static final int MIN_INTERVAL = 10; 2188 2189 private final Network mNetwork; 2190 private final ISocketKeepaliveCallback mCallback; 2191 private final ExecutorService mExecutor; 2192 2193 private volatile Integer mSlot; 2194 2195 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) stop()2196 public void stop() { 2197 try { 2198 mExecutor.execute(() -> { 2199 try { 2200 if (mSlot != null) { 2201 mService.stopKeepalive(mNetwork, mSlot); 2202 } 2203 } catch (RemoteException e) { 2204 Log.e(TAG, "Error stopping packet keepalive: ", e); 2205 throw e.rethrowFromSystemServer(); 2206 } 2207 }); 2208 } catch (RejectedExecutionException e) { 2209 // The internal executor has already stopped due to previous event. 2210 } 2211 } 2212 PacketKeepalive(Network network, PacketKeepaliveCallback callback)2213 private PacketKeepalive(Network network, PacketKeepaliveCallback callback) { 2214 Objects.requireNonNull(network, "network cannot be null"); 2215 Objects.requireNonNull(callback, "callback cannot be null"); 2216 mNetwork = network; 2217 mExecutor = Executors.newSingleThreadExecutor(); 2218 mCallback = new ISocketKeepaliveCallback.Stub() { 2219 @Override 2220 public void onStarted(int slot) { 2221 final long token = Binder.clearCallingIdentity(); 2222 try { 2223 mExecutor.execute(() -> { 2224 mSlot = slot; 2225 callback.onStarted(); 2226 }); 2227 } finally { 2228 Binder.restoreCallingIdentity(token); 2229 } 2230 } 2231 2232 @Override 2233 public void onStopped() { 2234 final long token = Binder.clearCallingIdentity(); 2235 try { 2236 mExecutor.execute(() -> { 2237 mSlot = null; 2238 callback.onStopped(); 2239 }); 2240 } finally { 2241 Binder.restoreCallingIdentity(token); 2242 } 2243 mExecutor.shutdown(); 2244 } 2245 2246 @Override 2247 public void onError(int error) { 2248 final long token = Binder.clearCallingIdentity(); 2249 try { 2250 mExecutor.execute(() -> { 2251 mSlot = null; 2252 callback.onError(error); 2253 }); 2254 } finally { 2255 Binder.restoreCallingIdentity(token); 2256 } 2257 mExecutor.shutdown(); 2258 } 2259 2260 @Override 2261 public void onDataReceived() { 2262 // PacketKeepalive is only used for Nat-T keepalive and as such does not invoke 2263 // this callback when data is received. 2264 } 2265 }; 2266 } 2267 } 2268 2269 /** 2270 * Starts an IPsec NAT-T keepalive packet with the specified parameters. 2271 * 2272 * @deprecated Use {@link #createSocketKeepalive} instead. 2273 * 2274 * @hide 2275 */ 2276 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) startNattKeepalive( Network network, int intervalSeconds, PacketKeepaliveCallback callback, InetAddress srcAddr, int srcPort, InetAddress dstAddr)2277 public PacketKeepalive startNattKeepalive( 2278 Network network, int intervalSeconds, PacketKeepaliveCallback callback, 2279 InetAddress srcAddr, int srcPort, InetAddress dstAddr) { 2280 final PacketKeepalive k = new PacketKeepalive(network, callback); 2281 try { 2282 mService.startNattKeepalive(network, intervalSeconds, k.mCallback, 2283 srcAddr.getHostAddress(), srcPort, dstAddr.getHostAddress()); 2284 } catch (RemoteException e) { 2285 Log.e(TAG, "Error starting packet keepalive: ", e); 2286 throw e.rethrowFromSystemServer(); 2287 } 2288 return k; 2289 } 2290 2291 // Construct an invalid fd. createInvalidFd()2292 private ParcelFileDescriptor createInvalidFd() { 2293 final int invalidFd = -1; 2294 return ParcelFileDescriptor.adoptFd(invalidFd); 2295 } 2296 2297 /** 2298 * Request that keepalives be started on a IPsec NAT-T socket. 2299 * 2300 * @param network The {@link Network} the socket is on. 2301 * @param socket The socket that needs to be kept alive. 2302 * @param source The source address of the {@link UdpEncapsulationSocket}. 2303 * @param destination The destination address of the {@link UdpEncapsulationSocket}. 2304 * @param executor The executor on which callback will be invoked. The provided {@link Executor} 2305 * must run callback sequentially, otherwise the order of callbacks cannot be 2306 * guaranteed. 2307 * @param callback A {@link SocketKeepalive.Callback}. Used for notifications about keepalive 2308 * changes. Must be extended by applications that use this API. 2309 * 2310 * @return A {@link SocketKeepalive} object that can be used to control the keepalive on the 2311 * given socket. 2312 **/ createSocketKeepalive(@onNull Network network, @NonNull UdpEncapsulationSocket socket, @NonNull InetAddress source, @NonNull InetAddress destination, @NonNull @CallbackExecutor Executor executor, @NonNull Callback callback)2313 public @NonNull SocketKeepalive createSocketKeepalive(@NonNull Network network, 2314 @NonNull UdpEncapsulationSocket socket, 2315 @NonNull InetAddress source, 2316 @NonNull InetAddress destination, 2317 @NonNull @CallbackExecutor Executor executor, 2318 @NonNull Callback callback) { 2319 ParcelFileDescriptor dup; 2320 try { 2321 // Dup is needed here as the pfd inside the socket is owned by the IpSecService, 2322 // which cannot be obtained by the app process. 2323 dup = ParcelFileDescriptor.dup(socket.getFileDescriptor()); 2324 } catch (IOException ignored) { 2325 // Construct an invalid fd, so that if the user later calls start(), it will fail with 2326 // ERROR_INVALID_SOCKET. 2327 dup = createInvalidFd(); 2328 } 2329 return new NattSocketKeepalive(mService, network, dup, socket.getResourceId(), source, 2330 destination, executor, callback); 2331 } 2332 2333 /** 2334 * Request that keepalives be started on a IPsec NAT-T socket file descriptor. Directly called 2335 * by system apps which don't use IpSecService to create {@link UdpEncapsulationSocket}. 2336 * 2337 * @param network The {@link Network} the socket is on. 2338 * @param pfd The {@link ParcelFileDescriptor} that needs to be kept alive. The provided 2339 * {@link ParcelFileDescriptor} must be bound to a port and the keepalives will be sent 2340 * from that port. 2341 * @param source The source address of the {@link UdpEncapsulationSocket}. 2342 * @param destination The destination address of the {@link UdpEncapsulationSocket}. The 2343 * keepalive packets will always be sent to port 4500 of the given {@code destination}. 2344 * @param executor The executor on which callback will be invoked. The provided {@link Executor} 2345 * must run callback sequentially, otherwise the order of callbacks cannot be 2346 * guaranteed. 2347 * @param callback A {@link SocketKeepalive.Callback}. Used for notifications about keepalive 2348 * changes. Must be extended by applications that use this API. 2349 * 2350 * @return A {@link SocketKeepalive} object that can be used to control the keepalive on the 2351 * given socket. 2352 * @hide 2353 */ 2354 @SystemApi 2355 @RequiresPermission(android.Manifest.permission.PACKET_KEEPALIVE_OFFLOAD) createNattKeepalive(@onNull Network network, @NonNull ParcelFileDescriptor pfd, @NonNull InetAddress source, @NonNull InetAddress destination, @NonNull @CallbackExecutor Executor executor, @NonNull Callback callback)2356 public @NonNull SocketKeepalive createNattKeepalive(@NonNull Network network, 2357 @NonNull ParcelFileDescriptor pfd, 2358 @NonNull InetAddress source, 2359 @NonNull InetAddress destination, 2360 @NonNull @CallbackExecutor Executor executor, 2361 @NonNull Callback callback) { 2362 ParcelFileDescriptor dup; 2363 try { 2364 // TODO: Consider remove unnecessary dup. 2365 dup = pfd.dup(); 2366 } catch (IOException ignored) { 2367 // Construct an invalid fd, so that if the user later calls start(), it will fail with 2368 // ERROR_INVALID_SOCKET. 2369 dup = createInvalidFd(); 2370 } 2371 return new NattSocketKeepalive(mService, network, dup, 2372 -1 /* Unused */, source, destination, executor, callback); 2373 } 2374 2375 /** 2376 * Request that keepalives be started on a TCP socket. 2377 * The socket must be established. 2378 * 2379 * @param network The {@link Network} the socket is on. 2380 * @param socket The socket that needs to be kept alive. 2381 * @param executor The executor on which callback will be invoked. This implementation assumes 2382 * the provided {@link Executor} runs the callbacks in sequence with no 2383 * concurrency. Failing this, no guarantee of correctness can be made. It is 2384 * the responsibility of the caller to ensure the executor provides this 2385 * guarantee. A simple way of creating such an executor is with the standard 2386 * tool {@code Executors.newSingleThreadExecutor}. 2387 * @param callback A {@link SocketKeepalive.Callback}. Used for notifications about keepalive 2388 * changes. Must be extended by applications that use this API. 2389 * 2390 * @return A {@link SocketKeepalive} object that can be used to control the keepalive on the 2391 * given socket. 2392 * @hide 2393 */ 2394 @SystemApi 2395 @RequiresPermission(android.Manifest.permission.PACKET_KEEPALIVE_OFFLOAD) createSocketKeepalive(@onNull Network network, @NonNull Socket socket, @NonNull Executor executor, @NonNull Callback callback)2396 public @NonNull SocketKeepalive createSocketKeepalive(@NonNull Network network, 2397 @NonNull Socket socket, 2398 @NonNull Executor executor, 2399 @NonNull Callback callback) { 2400 ParcelFileDescriptor dup; 2401 try { 2402 dup = ParcelFileDescriptor.fromSocket(socket); 2403 } catch (UncheckedIOException ignored) { 2404 // Construct an invalid fd, so that if the user later calls start(), it will fail with 2405 // ERROR_INVALID_SOCKET. 2406 dup = createInvalidFd(); 2407 } 2408 return new TcpSocketKeepalive(mService, network, dup, executor, callback); 2409 } 2410 2411 /** 2412 * Ensure that a network route exists to deliver traffic to the specified 2413 * host via the specified network interface. An attempt to add a route that 2414 * already exists is ignored, but treated as successful. 2415 * 2416 * <p>This method requires the caller to hold either the 2417 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 2418 * or the ability to modify system settings as determined by 2419 * {@link android.provider.Settings.System#canWrite}.</p> 2420 * 2421 * @param networkType the type of the network over which traffic to the specified 2422 * host is to be routed 2423 * @param hostAddress the IP address of the host to which the route is desired 2424 * @return {@code true} on success, {@code false} on failure 2425 * 2426 * @deprecated Deprecated in favor of the 2427 * {@link #requestNetwork(NetworkRequest, NetworkCallback)}, 2428 * {@link #bindProcessToNetwork} and {@link Network#getSocketFactory} API. 2429 * In {@link VERSION_CODES#M}, and above, this method is unsupported and will 2430 * throw {@code UnsupportedOperationException} if called. 2431 * @removed 2432 */ 2433 @Deprecated requestRouteToHost(int networkType, int hostAddress)2434 public boolean requestRouteToHost(int networkType, int hostAddress) { 2435 return requestRouteToHostAddress(networkType, NetworkUtils.intToInetAddress(hostAddress)); 2436 } 2437 2438 /** 2439 * Ensure that a network route exists to deliver traffic to the specified 2440 * host via the specified network interface. An attempt to add a route that 2441 * already exists is ignored, but treated as successful. 2442 * 2443 * <p>This method requires the caller to hold either the 2444 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 2445 * or the ability to modify system settings as determined by 2446 * {@link android.provider.Settings.System#canWrite}.</p> 2447 * 2448 * @param networkType the type of the network over which traffic to the specified 2449 * host is to be routed 2450 * @param hostAddress the IP address of the host to which the route is desired 2451 * @return {@code true} on success, {@code false} on failure 2452 * @hide 2453 * @deprecated Deprecated in favor of the {@link #requestNetwork} and 2454 * {@link #bindProcessToNetwork} API. 2455 */ 2456 @Deprecated 2457 @UnsupportedAppUsage 2458 @SystemApi(client = MODULE_LIBRARIES) requestRouteToHostAddress(int networkType, InetAddress hostAddress)2459 public boolean requestRouteToHostAddress(int networkType, InetAddress hostAddress) { 2460 checkLegacyRoutingApiAccess(); 2461 try { 2462 return mService.requestRouteToHostAddress(networkType, hostAddress.getAddress(), 2463 mContext.getOpPackageName(), getAttributionTag()); 2464 } catch (RemoteException e) { 2465 throw e.rethrowFromSystemServer(); 2466 } 2467 } 2468 2469 /** 2470 * @return the context's attribution tag 2471 */ 2472 // TODO: Remove method and replace with direct call once R code is pushed to AOSP getAttributionTag()2473 private @Nullable String getAttributionTag() { 2474 return mContext.getAttributionTag(); 2475 } 2476 2477 /** 2478 * Returns the value of the setting for background data usage. If false, 2479 * applications should not use the network if the application is not in the 2480 * foreground. Developers should respect this setting, and check the value 2481 * of this before performing any background data operations. 2482 * <p> 2483 * All applications that have background services that use the network 2484 * should listen to {@link #ACTION_BACKGROUND_DATA_SETTING_CHANGED}. 2485 * <p> 2486 * @deprecated As of {@link VERSION_CODES#ICE_CREAM_SANDWICH}, availability of 2487 * background data depends on several combined factors, and this method will 2488 * always return {@code true}. Instead, when background data is unavailable, 2489 * {@link #getActiveNetworkInfo()} will now appear disconnected. 2490 * 2491 * @return Whether background data usage is allowed. 2492 */ 2493 @Deprecated getBackgroundDataSetting()2494 public boolean getBackgroundDataSetting() { 2495 // assume that background data is allowed; final authority is 2496 // NetworkInfo which may be blocked. 2497 return true; 2498 } 2499 2500 /** 2501 * Sets the value of the setting for background data usage. 2502 * 2503 * @param allowBackgroundData Whether an application should use data while 2504 * it is in the background. 2505 * 2506 * @attr ref android.Manifest.permission#CHANGE_BACKGROUND_DATA_SETTING 2507 * @see #getBackgroundDataSetting() 2508 * @hide 2509 */ 2510 @Deprecated 2511 @UnsupportedAppUsage setBackgroundDataSetting(boolean allowBackgroundData)2512 public void setBackgroundDataSetting(boolean allowBackgroundData) { 2513 // ignored 2514 } 2515 2516 /** 2517 * @hide 2518 * @deprecated Talk to TelephonyManager directly 2519 */ 2520 @Deprecated 2521 @UnsupportedAppUsage getMobileDataEnabled()2522 public boolean getMobileDataEnabled() { 2523 TelephonyManager tm = mContext.getSystemService(TelephonyManager.class); 2524 if (tm != null) { 2525 int subId = SubscriptionManager.getDefaultDataSubscriptionId(); 2526 Log.d("ConnectivityManager", "getMobileDataEnabled()+ subId=" + subId); 2527 boolean retVal = tm.createForSubscriptionId(subId).isDataEnabled(); 2528 Log.d("ConnectivityManager", "getMobileDataEnabled()- subId=" + subId 2529 + " retVal=" + retVal); 2530 return retVal; 2531 } 2532 Log.d("ConnectivityManager", "getMobileDataEnabled()- remote exception retVal=false"); 2533 return false; 2534 } 2535 2536 /** 2537 * Callback for use with {@link ConnectivityManager#addDefaultNetworkActiveListener} 2538 * to find out when the system default network has gone in to a high power state. 2539 */ 2540 public interface OnNetworkActiveListener { 2541 /** 2542 * Called on the main thread of the process to report that the current data network 2543 * has become active, and it is now a good time to perform any pending network 2544 * operations. Note that this listener only tells you when the network becomes 2545 * active; if at any other time you want to know whether it is active (and thus okay 2546 * to initiate network traffic), you can retrieve its instantaneous state with 2547 * {@link ConnectivityManager#isDefaultNetworkActive}. 2548 */ onNetworkActive()2549 void onNetworkActive(); 2550 } 2551 2552 @GuardedBy("mNetworkActivityListeners") 2553 private final ArrayMap<OnNetworkActiveListener, INetworkActivityListener> 2554 mNetworkActivityListeners = new ArrayMap<>(); 2555 2556 /** 2557 * Start listening to reports when the system's default data network is active, meaning it is 2558 * a good time to perform network traffic. Use {@link #isDefaultNetworkActive()} 2559 * to determine the current state of the system's default network after registering the 2560 * listener. 2561 * <p> 2562 * If the process default network has been set with 2563 * {@link ConnectivityManager#bindProcessToNetwork} this function will not 2564 * reflect the process's default, but the system default. 2565 * 2566 * @param l The listener to be told when the network is active. 2567 */ addDefaultNetworkActiveListener(final OnNetworkActiveListener l)2568 public void addDefaultNetworkActiveListener(final OnNetworkActiveListener l) { 2569 final INetworkActivityListener rl = new INetworkActivityListener.Stub() { 2570 @Override 2571 public void onNetworkActive() throws RemoteException { 2572 l.onNetworkActive(); 2573 } 2574 }; 2575 2576 synchronized (mNetworkActivityListeners) { 2577 try { 2578 mService.registerNetworkActivityListener(rl); 2579 mNetworkActivityListeners.put(l, rl); 2580 } catch (RemoteException e) { 2581 throw e.rethrowFromSystemServer(); 2582 } 2583 } 2584 } 2585 2586 /** 2587 * Remove network active listener previously registered with 2588 * {@link #addDefaultNetworkActiveListener}. 2589 * 2590 * @param l Previously registered listener. 2591 */ removeDefaultNetworkActiveListener(@onNull OnNetworkActiveListener l)2592 public void removeDefaultNetworkActiveListener(@NonNull OnNetworkActiveListener l) { 2593 synchronized (mNetworkActivityListeners) { 2594 final INetworkActivityListener rl = mNetworkActivityListeners.get(l); 2595 if (rl == null) { 2596 throw new IllegalArgumentException("Listener was not registered."); 2597 } 2598 try { 2599 mService.unregisterNetworkActivityListener(rl); 2600 mNetworkActivityListeners.remove(l); 2601 } catch (RemoteException e) { 2602 throw e.rethrowFromSystemServer(); 2603 } 2604 } 2605 } 2606 2607 /** 2608 * Return whether the data network is currently active. An active network means that 2609 * it is currently in a high power state for performing data transmission. On some 2610 * types of networks, it may be expensive to move and stay in such a state, so it is 2611 * more power efficient to batch network traffic together when the radio is already in 2612 * this state. This method tells you whether right now is currently a good time to 2613 * initiate network traffic, as the network is already active. 2614 */ isDefaultNetworkActive()2615 public boolean isDefaultNetworkActive() { 2616 try { 2617 return mService.isDefaultNetworkActive(); 2618 } catch (RemoteException e) { 2619 throw e.rethrowFromSystemServer(); 2620 } 2621 } 2622 2623 /** 2624 * {@hide} 2625 */ ConnectivityManager(Context context, IConnectivityManager service)2626 public ConnectivityManager(Context context, IConnectivityManager service) { 2627 mContext = Objects.requireNonNull(context, "missing context"); 2628 mService = Objects.requireNonNull(service, "missing IConnectivityManager"); 2629 sInstance = this; 2630 } 2631 2632 /** {@hide} */ 2633 @UnsupportedAppUsage from(Context context)2634 public static ConnectivityManager from(Context context) { 2635 return (ConnectivityManager) context.getSystemService(Context.CONNECTIVITY_SERVICE); 2636 } 2637 2638 /** @hide */ getDefaultRequest()2639 public NetworkRequest getDefaultRequest() { 2640 try { 2641 // This is not racy as the default request is final in ConnectivityService. 2642 return mService.getDefaultRequest(); 2643 } catch (RemoteException e) { 2644 throw e.rethrowFromSystemServer(); 2645 } 2646 } 2647 2648 /** 2649 * Check if the package is a allowed to write settings. This also accounts that such an access 2650 * happened. 2651 * 2652 * @return {@code true} iff the package is allowed to write settings. 2653 */ 2654 // TODO: Remove method and replace with direct call once R code is pushed to AOSP checkAndNoteWriteSettingsOperation(@onNull Context context, int uid, @NonNull String callingPackage, @Nullable String callingAttributionTag, boolean throwException)2655 private static boolean checkAndNoteWriteSettingsOperation(@NonNull Context context, int uid, 2656 @NonNull String callingPackage, @Nullable String callingAttributionTag, 2657 boolean throwException) { 2658 return Settings.checkAndNoteWriteSettingsOperation(context, uid, callingPackage, 2659 callingAttributionTag, throwException); 2660 } 2661 2662 /** 2663 * @deprecated - use getSystemService. This is a kludge to support static access in certain 2664 * situations where a Context pointer is unavailable. 2665 * @hide 2666 */ 2667 @Deprecated getInstanceOrNull()2668 static ConnectivityManager getInstanceOrNull() { 2669 return sInstance; 2670 } 2671 2672 /** 2673 * @deprecated - use getSystemService. This is a kludge to support static access in certain 2674 * situations where a Context pointer is unavailable. 2675 * @hide 2676 */ 2677 @Deprecated 2678 @UnsupportedAppUsage getInstance()2679 private static ConnectivityManager getInstance() { 2680 if (getInstanceOrNull() == null) { 2681 throw new IllegalStateException("No ConnectivityManager yet constructed"); 2682 } 2683 return getInstanceOrNull(); 2684 } 2685 2686 /** 2687 * Get the set of tetherable, available interfaces. This list is limited by 2688 * device configuration and current interface existence. 2689 * 2690 * @return an array of 0 or more Strings of tetherable interface names. 2691 * 2692 * @deprecated Use {@link TetheringEventCallback#onTetherableInterfacesChanged(List)} instead. 2693 * {@hide} 2694 */ 2695 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 2696 @UnsupportedAppUsage 2697 @Deprecated getTetherableIfaces()2698 public String[] getTetherableIfaces() { 2699 return getTetheringManager().getTetherableIfaces(); 2700 } 2701 2702 /** 2703 * Get the set of tethered interfaces. 2704 * 2705 * @return an array of 0 or more String of currently tethered interface names. 2706 * 2707 * @deprecated Use {@link TetheringEventCallback#onTetherableInterfacesChanged(List)} instead. 2708 * {@hide} 2709 */ 2710 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 2711 @UnsupportedAppUsage 2712 @Deprecated getTetheredIfaces()2713 public String[] getTetheredIfaces() { 2714 return getTetheringManager().getTetheredIfaces(); 2715 } 2716 2717 /** 2718 * Get the set of interface names which attempted to tether but 2719 * failed. Re-attempting to tether may cause them to reset to the Tethered 2720 * state. Alternatively, causing the interface to be destroyed and recreated 2721 * may cause them to reset to the available state. 2722 * {@link ConnectivityManager#getLastTetherError} can be used to get more 2723 * information on the cause of the errors. 2724 * 2725 * @return an array of 0 or more String indicating the interface names 2726 * which failed to tether. 2727 * 2728 * @deprecated Use {@link TetheringEventCallback#onError(String, int)} instead. 2729 * {@hide} 2730 */ 2731 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 2732 @UnsupportedAppUsage 2733 @Deprecated getTetheringErroredIfaces()2734 public String[] getTetheringErroredIfaces() { 2735 return getTetheringManager().getTetheringErroredIfaces(); 2736 } 2737 2738 /** 2739 * Get the set of tethered dhcp ranges. 2740 * 2741 * @deprecated This method is not supported. 2742 * TODO: remove this function when all of clients are removed. 2743 * {@hide} 2744 */ 2745 @RequiresPermission(android.Manifest.permission.NETWORK_SETTINGS) 2746 @Deprecated getTetheredDhcpRanges()2747 public String[] getTetheredDhcpRanges() { 2748 throw new UnsupportedOperationException("getTetheredDhcpRanges is not supported"); 2749 } 2750 2751 /** 2752 * Attempt to tether the named interface. This will setup a dhcp server 2753 * on the interface, forward and NAT IP packets and forward DNS requests 2754 * to the best active upstream network interface. Note that if no upstream 2755 * IP network interface is available, dhcp will still run and traffic will be 2756 * allowed between the tethered devices and this device, though upstream net 2757 * access will of course fail until an upstream network interface becomes 2758 * active. 2759 * 2760 * <p>This method requires the caller to hold either the 2761 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 2762 * or the ability to modify system settings as determined by 2763 * {@link android.provider.Settings.System#canWrite}.</p> 2764 * 2765 * <p>WARNING: New clients should not use this function. The only usages should be in PanService 2766 * and WifiStateMachine which need direct access. All other clients should use 2767 * {@link #startTethering} and {@link #stopTethering} which encapsulate proper provisioning 2768 * logic.</p> 2769 * 2770 * @param iface the interface name to tether. 2771 * @return error a {@code TETHER_ERROR} value indicating success or failure type 2772 * @deprecated Use {@link TetheringManager#startTethering} instead 2773 * 2774 * {@hide} 2775 */ 2776 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 2777 @Deprecated tether(String iface)2778 public int tether(String iface) { 2779 return getTetheringManager().tether(iface); 2780 } 2781 2782 /** 2783 * Stop tethering the named interface. 2784 * 2785 * <p>This method requires the caller to hold either the 2786 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 2787 * or the ability to modify system settings as determined by 2788 * {@link android.provider.Settings.System#canWrite}.</p> 2789 * 2790 * <p>WARNING: New clients should not use this function. The only usages should be in PanService 2791 * and WifiStateMachine which need direct access. All other clients should use 2792 * {@link #startTethering} and {@link #stopTethering} which encapsulate proper provisioning 2793 * logic.</p> 2794 * 2795 * @param iface the interface name to untether. 2796 * @return error a {@code TETHER_ERROR} value indicating success or failure type 2797 * 2798 * {@hide} 2799 */ 2800 @UnsupportedAppUsage 2801 @Deprecated untether(String iface)2802 public int untether(String iface) { 2803 return getTetheringManager().untether(iface); 2804 } 2805 2806 /** 2807 * Check if the device allows for tethering. It may be disabled via 2808 * {@code ro.tether.denied} system property, Settings.TETHER_SUPPORTED or 2809 * due to device configuration. 2810 * 2811 * <p>If this app does not have permission to use this API, it will always 2812 * return false rather than throw an exception.</p> 2813 * 2814 * <p>If the device has a hotspot provisioning app, the caller is required to hold the 2815 * {@link android.Manifest.permission.TETHER_PRIVILEGED} permission.</p> 2816 * 2817 * <p>Otherwise, this method requires the caller to hold the ability to modify system 2818 * settings as determined by {@link android.provider.Settings.System#canWrite}.</p> 2819 * 2820 * @return a boolean - {@code true} indicating Tethering is supported. 2821 * 2822 * @deprecated Use {@link TetheringEventCallback#onTetheringSupported(boolean)} instead. 2823 * {@hide} 2824 */ 2825 @SystemApi 2826 @RequiresPermission(anyOf = {android.Manifest.permission.TETHER_PRIVILEGED, 2827 android.Manifest.permission.WRITE_SETTINGS}) isTetheringSupported()2828 public boolean isTetheringSupported() { 2829 return getTetheringManager().isTetheringSupported(); 2830 } 2831 2832 /** 2833 * Callback for use with {@link #startTethering} to find out whether tethering succeeded. 2834 * 2835 * @deprecated Use {@link TetheringManager.StartTetheringCallback} instead. 2836 * @hide 2837 */ 2838 @SystemApi 2839 @Deprecated 2840 public static abstract class OnStartTetheringCallback { 2841 /** 2842 * Called when tethering has been successfully started. 2843 */ onTetheringStarted()2844 public void onTetheringStarted() {} 2845 2846 /** 2847 * Called when starting tethering failed. 2848 */ onTetheringFailed()2849 public void onTetheringFailed() {} 2850 } 2851 2852 /** 2853 * Convenient overload for 2854 * {@link #startTethering(int, boolean, OnStartTetheringCallback, Handler)} which passes a null 2855 * handler to run on the current thread's {@link Looper}. 2856 * 2857 * @deprecated Use {@link TetheringManager#startTethering} instead. 2858 * @hide 2859 */ 2860 @SystemApi 2861 @Deprecated 2862 @RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED) startTethering(int type, boolean showProvisioningUi, final OnStartTetheringCallback callback)2863 public void startTethering(int type, boolean showProvisioningUi, 2864 final OnStartTetheringCallback callback) { 2865 startTethering(type, showProvisioningUi, callback, null); 2866 } 2867 2868 /** 2869 * Runs tether provisioning for the given type if needed and then starts tethering if 2870 * the check succeeds. If no carrier provisioning is required for tethering, tethering is 2871 * enabled immediately. If provisioning fails, tethering will not be enabled. It also 2872 * schedules tether provisioning re-checks if appropriate. 2873 * 2874 * @param type The type of tethering to start. Must be one of 2875 * {@link ConnectivityManager.TETHERING_WIFI}, 2876 * {@link ConnectivityManager.TETHERING_USB}, or 2877 * {@link ConnectivityManager.TETHERING_BLUETOOTH}. 2878 * @param showProvisioningUi a boolean indicating to show the provisioning app UI if there 2879 * is one. This should be true the first time this function is called and also any time 2880 * the user can see this UI. It gives users information from their carrier about the 2881 * check failing and how they can sign up for tethering if possible. 2882 * @param callback an {@link OnStartTetheringCallback} which will be called to notify the caller 2883 * of the result of trying to tether. 2884 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 2885 * 2886 * @deprecated Use {@link TetheringManager#startTethering} instead. 2887 * @hide 2888 */ 2889 @SystemApi 2890 @Deprecated 2891 @RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED) startTethering(int type, boolean showProvisioningUi, final OnStartTetheringCallback callback, Handler handler)2892 public void startTethering(int type, boolean showProvisioningUi, 2893 final OnStartTetheringCallback callback, Handler handler) { 2894 Objects.requireNonNull(callback, "OnStartTetheringCallback cannot be null."); 2895 2896 final Executor executor = new Executor() { 2897 @Override 2898 public void execute(Runnable command) { 2899 if (handler == null) { 2900 command.run(); 2901 } else { 2902 handler.post(command); 2903 } 2904 } 2905 }; 2906 2907 final StartTetheringCallback tetheringCallback = new StartTetheringCallback() { 2908 @Override 2909 public void onTetheringStarted() { 2910 callback.onTetheringStarted(); 2911 } 2912 2913 @Override 2914 public void onTetheringFailed(final int error) { 2915 callback.onTetheringFailed(); 2916 } 2917 }; 2918 2919 final TetheringRequest request = new TetheringRequest.Builder(type) 2920 .setShouldShowEntitlementUi(showProvisioningUi).build(); 2921 2922 getTetheringManager().startTethering(request, executor, tetheringCallback); 2923 } 2924 2925 /** 2926 * Stops tethering for the given type. Also cancels any provisioning rechecks for that type if 2927 * applicable. 2928 * 2929 * @param type The type of tethering to stop. Must be one of 2930 * {@link ConnectivityManager.TETHERING_WIFI}, 2931 * {@link ConnectivityManager.TETHERING_USB}, or 2932 * {@link ConnectivityManager.TETHERING_BLUETOOTH}. 2933 * 2934 * @deprecated Use {@link TetheringManager#stopTethering} instead. 2935 * @hide 2936 */ 2937 @SystemApi 2938 @Deprecated 2939 @RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED) stopTethering(int type)2940 public void stopTethering(int type) { 2941 getTetheringManager().stopTethering(type); 2942 } 2943 2944 /** 2945 * Callback for use with {@link registerTetheringEventCallback} to find out tethering 2946 * upstream status. 2947 * 2948 * @deprecated Use {@link TetheringManager#OnTetheringEventCallback} instead. 2949 * @hide 2950 */ 2951 @SystemApi 2952 @Deprecated 2953 public abstract static class OnTetheringEventCallback { 2954 2955 /** 2956 * Called when tethering upstream changed. This can be called multiple times and can be 2957 * called any time. 2958 * 2959 * @param network the {@link Network} of tethering upstream. Null means tethering doesn't 2960 * have any upstream. 2961 */ onUpstreamChanged(@ullable Network network)2962 public void onUpstreamChanged(@Nullable Network network) {} 2963 } 2964 2965 @GuardedBy("mTetheringEventCallbacks") 2966 private final ArrayMap<OnTetheringEventCallback, TetheringEventCallback> 2967 mTetheringEventCallbacks = new ArrayMap<>(); 2968 2969 /** 2970 * Start listening to tethering change events. Any new added callback will receive the last 2971 * tethering status right away. If callback is registered when tethering has no upstream or 2972 * disabled, {@link OnTetheringEventCallback#onUpstreamChanged} will immediately be called 2973 * with a null argument. The same callback object cannot be registered twice. 2974 * 2975 * @param executor the executor on which callback will be invoked. 2976 * @param callback the callback to be called when tethering has change events. 2977 * 2978 * @deprecated Use {@link TetheringManager#registerTetheringEventCallback} instead. 2979 * @hide 2980 */ 2981 @SystemApi 2982 @Deprecated 2983 @RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED) registerTetheringEventCallback( @onNull @allbackExecutor Executor executor, @NonNull final OnTetheringEventCallback callback)2984 public void registerTetheringEventCallback( 2985 @NonNull @CallbackExecutor Executor executor, 2986 @NonNull final OnTetheringEventCallback callback) { 2987 Objects.requireNonNull(callback, "OnTetheringEventCallback cannot be null."); 2988 2989 final TetheringEventCallback tetherCallback = 2990 new TetheringEventCallback() { 2991 @Override 2992 public void onUpstreamChanged(@Nullable Network network) { 2993 callback.onUpstreamChanged(network); 2994 } 2995 }; 2996 2997 synchronized (mTetheringEventCallbacks) { 2998 mTetheringEventCallbacks.put(callback, tetherCallback); 2999 getTetheringManager().registerTetheringEventCallback(executor, tetherCallback); 3000 } 3001 } 3002 3003 /** 3004 * Remove tethering event callback previously registered with 3005 * {@link #registerTetheringEventCallback}. 3006 * 3007 * @param callback previously registered callback. 3008 * 3009 * @deprecated Use {@link TetheringManager#unregisterTetheringEventCallback} instead. 3010 * @hide 3011 */ 3012 @SystemApi 3013 @Deprecated 3014 @RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED) unregisterTetheringEventCallback( @onNull final OnTetheringEventCallback callback)3015 public void unregisterTetheringEventCallback( 3016 @NonNull final OnTetheringEventCallback callback) { 3017 Objects.requireNonNull(callback, "The callback must be non-null"); 3018 synchronized (mTetheringEventCallbacks) { 3019 final TetheringEventCallback tetherCallback = 3020 mTetheringEventCallbacks.remove(callback); 3021 getTetheringManager().unregisterTetheringEventCallback(tetherCallback); 3022 } 3023 } 3024 3025 3026 /** 3027 * Get the list of regular expressions that define any tetherable 3028 * USB network interfaces. If USB tethering is not supported by the 3029 * device, this list should be empty. 3030 * 3031 * @return an array of 0 or more regular expression Strings defining 3032 * what interfaces are considered tetherable usb interfaces. 3033 * 3034 * @deprecated Use {@link TetheringEventCallback#onTetherableInterfaceRegexpsChanged} instead. 3035 * {@hide} 3036 */ 3037 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 3038 @UnsupportedAppUsage 3039 @Deprecated getTetherableUsbRegexs()3040 public String[] getTetherableUsbRegexs() { 3041 return getTetheringManager().getTetherableUsbRegexs(); 3042 } 3043 3044 /** 3045 * Get the list of regular expressions that define any tetherable 3046 * Wifi network interfaces. If Wifi tethering is not supported by the 3047 * device, this list should be empty. 3048 * 3049 * @return an array of 0 or more regular expression Strings defining 3050 * what interfaces are considered tetherable wifi interfaces. 3051 * 3052 * @deprecated Use {@link TetheringEventCallback#onTetherableInterfaceRegexpsChanged} instead. 3053 * {@hide} 3054 */ 3055 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 3056 @UnsupportedAppUsage 3057 @Deprecated getTetherableWifiRegexs()3058 public String[] getTetherableWifiRegexs() { 3059 return getTetheringManager().getTetherableWifiRegexs(); 3060 } 3061 3062 /** 3063 * Get the list of regular expressions that define any tetherable 3064 * Bluetooth network interfaces. If Bluetooth tethering is not supported by the 3065 * device, this list should be empty. 3066 * 3067 * @return an array of 0 or more regular expression Strings defining 3068 * what interfaces are considered tetherable bluetooth interfaces. 3069 * 3070 * @deprecated Use {@link TetheringEventCallback#onTetherableInterfaceRegexpsChanged( 3071 *TetheringManager.TetheringInterfaceRegexps)} instead. 3072 * {@hide} 3073 */ 3074 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 3075 @UnsupportedAppUsage 3076 @Deprecated getTetherableBluetoothRegexs()3077 public String[] getTetherableBluetoothRegexs() { 3078 return getTetheringManager().getTetherableBluetoothRegexs(); 3079 } 3080 3081 /** 3082 * Attempt to both alter the mode of USB and Tethering of USB. A 3083 * utility method to deal with some of the complexity of USB - will 3084 * attempt to switch to Rndis and subsequently tether the resulting 3085 * interface on {@code true} or turn off tethering and switch off 3086 * Rndis on {@code false}. 3087 * 3088 * <p>This method requires the caller to hold either the 3089 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 3090 * or the ability to modify system settings as determined by 3091 * {@link android.provider.Settings.System#canWrite}.</p> 3092 * 3093 * @param enable a boolean - {@code true} to enable tethering 3094 * @return error a {@code TETHER_ERROR} value indicating success or failure type 3095 * @deprecated Use {@link TetheringManager#startTethering} instead 3096 * 3097 * {@hide} 3098 */ 3099 @UnsupportedAppUsage 3100 @Deprecated setUsbTethering(boolean enable)3101 public int setUsbTethering(boolean enable) { 3102 return getTetheringManager().setUsbTethering(enable); 3103 } 3104 3105 /** 3106 * @deprecated Use {@link TetheringManager#TETHER_ERROR_NO_ERROR}. 3107 * {@hide} 3108 */ 3109 @SystemApi 3110 @Deprecated 3111 public static final int TETHER_ERROR_NO_ERROR = 0; 3112 /** 3113 * @deprecated Use {@link TetheringManager#TETHER_ERROR_UNKNOWN_IFACE}. 3114 * {@hide} 3115 */ 3116 @Deprecated 3117 public static final int TETHER_ERROR_UNKNOWN_IFACE = 3118 TetheringManager.TETHER_ERROR_UNKNOWN_IFACE; 3119 /** 3120 * @deprecated Use {@link TetheringManager#TETHER_ERROR_SERVICE_UNAVAIL}. 3121 * {@hide} 3122 */ 3123 @Deprecated 3124 public static final int TETHER_ERROR_SERVICE_UNAVAIL = 3125 TetheringManager.TETHER_ERROR_SERVICE_UNAVAIL; 3126 /** 3127 * @deprecated Use {@link TetheringManager#TETHER_ERROR_UNSUPPORTED}. 3128 * {@hide} 3129 */ 3130 @Deprecated 3131 public static final int TETHER_ERROR_UNSUPPORTED = TetheringManager.TETHER_ERROR_UNSUPPORTED; 3132 /** 3133 * @deprecated Use {@link TetheringManager#TETHER_ERROR_UNAVAIL_IFACE}. 3134 * {@hide} 3135 */ 3136 @Deprecated 3137 public static final int TETHER_ERROR_UNAVAIL_IFACE = 3138 TetheringManager.TETHER_ERROR_UNAVAIL_IFACE; 3139 /** 3140 * @deprecated Use {@link TetheringManager#TETHER_ERROR_INTERNAL_ERROR}. 3141 * {@hide} 3142 */ 3143 @Deprecated 3144 public static final int TETHER_ERROR_MASTER_ERROR = 3145 TetheringManager.TETHER_ERROR_INTERNAL_ERROR; 3146 /** 3147 * @deprecated Use {@link TetheringManager#TETHER_ERROR_TETHER_IFACE_ERROR}. 3148 * {@hide} 3149 */ 3150 @Deprecated 3151 public static final int TETHER_ERROR_TETHER_IFACE_ERROR = 3152 TetheringManager.TETHER_ERROR_TETHER_IFACE_ERROR; 3153 /** 3154 * @deprecated Use {@link TetheringManager#TETHER_ERROR_UNTETHER_IFACE_ERROR}. 3155 * {@hide} 3156 */ 3157 @Deprecated 3158 public static final int TETHER_ERROR_UNTETHER_IFACE_ERROR = 3159 TetheringManager.TETHER_ERROR_UNTETHER_IFACE_ERROR; 3160 /** 3161 * @deprecated Use {@link TetheringManager#TETHER_ERROR_ENABLE_FORWARDING_ERROR}. 3162 * {@hide} 3163 */ 3164 @Deprecated 3165 public static final int TETHER_ERROR_ENABLE_NAT_ERROR = 3166 TetheringManager.TETHER_ERROR_ENABLE_FORWARDING_ERROR; 3167 /** 3168 * @deprecated Use {@link TetheringManager#TETHER_ERROR_DISABLE_FORWARDING_ERROR}. 3169 * {@hide} 3170 */ 3171 @Deprecated 3172 public static final int TETHER_ERROR_DISABLE_NAT_ERROR = 3173 TetheringManager.TETHER_ERROR_DISABLE_FORWARDING_ERROR; 3174 /** 3175 * @deprecated Use {@link TetheringManager#TETHER_ERROR_IFACE_CFG_ERROR}. 3176 * {@hide} 3177 */ 3178 @Deprecated 3179 public static final int TETHER_ERROR_IFACE_CFG_ERROR = 3180 TetheringManager.TETHER_ERROR_IFACE_CFG_ERROR; 3181 /** 3182 * @deprecated Use {@link TetheringManager#TETHER_ERROR_PROVISIONING_FAILED}. 3183 * {@hide} 3184 */ 3185 @SystemApi 3186 @Deprecated 3187 public static final int TETHER_ERROR_PROVISION_FAILED = 11; 3188 /** 3189 * @deprecated Use {@link TetheringManager#TETHER_ERROR_DHCPSERVER_ERROR}. 3190 * {@hide} 3191 */ 3192 @Deprecated 3193 public static final int TETHER_ERROR_DHCPSERVER_ERROR = 3194 TetheringManager.TETHER_ERROR_DHCPSERVER_ERROR; 3195 /** 3196 * @deprecated Use {@link TetheringManager#TETHER_ERROR_ENTITLEMENT_UNKNOWN}. 3197 * {@hide} 3198 */ 3199 @SystemApi 3200 @Deprecated 3201 public static final int TETHER_ERROR_ENTITLEMENT_UNKONWN = 13; 3202 3203 /** 3204 * Get a more detailed error code after a Tethering or Untethering 3205 * request asynchronously failed. 3206 * 3207 * @param iface The name of the interface of interest 3208 * @return error The error code of the last error tethering or untethering the named 3209 * interface 3210 * 3211 * @deprecated Use {@link TetheringEventCallback#onError(String, int)} instead. 3212 * {@hide} 3213 */ 3214 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 3215 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 3216 @Deprecated getLastTetherError(String iface)3217 public int getLastTetherError(String iface) { 3218 int error = getTetheringManager().getLastTetherError(iface); 3219 if (error == TetheringManager.TETHER_ERROR_UNKNOWN_TYPE) { 3220 // TETHER_ERROR_UNKNOWN_TYPE was introduced with TetheringManager and has never been 3221 // returned by ConnectivityManager. Convert it to the legacy TETHER_ERROR_UNKNOWN_IFACE 3222 // instead. 3223 error = TetheringManager.TETHER_ERROR_UNKNOWN_IFACE; 3224 } 3225 return error; 3226 } 3227 3228 /** @hide */ 3229 @Retention(RetentionPolicy.SOURCE) 3230 @IntDef(value = { 3231 TETHER_ERROR_NO_ERROR, 3232 TETHER_ERROR_PROVISION_FAILED, 3233 TETHER_ERROR_ENTITLEMENT_UNKONWN, 3234 }) 3235 public @interface EntitlementResultCode { 3236 } 3237 3238 /** 3239 * Callback for use with {@link #getLatestTetheringEntitlementResult} to find out whether 3240 * entitlement succeeded. 3241 * 3242 * @deprecated Use {@link TetheringManager#OnTetheringEntitlementResultListener} instead. 3243 * @hide 3244 */ 3245 @SystemApi 3246 @Deprecated 3247 public interface OnTetheringEntitlementResultListener { 3248 /** 3249 * Called to notify entitlement result. 3250 * 3251 * @param resultCode an int value of entitlement result. It may be one of 3252 * {@link #TETHER_ERROR_NO_ERROR}, 3253 * {@link #TETHER_ERROR_PROVISION_FAILED}, or 3254 * {@link #TETHER_ERROR_ENTITLEMENT_UNKONWN}. 3255 */ onTetheringEntitlementResult(@ntitlementResultCode int resultCode)3256 void onTetheringEntitlementResult(@EntitlementResultCode int resultCode); 3257 } 3258 3259 /** 3260 * Get the last value of the entitlement check on this downstream. If the cached value is 3261 * {@link #TETHER_ERROR_NO_ERROR} or showEntitlementUi argument is false, it just return the 3262 * cached value. Otherwise, a UI-based entitlement check would be performed. It is not 3263 * guaranteed that the UI-based entitlement check will complete in any specific time period 3264 * and may in fact never complete. Any successful entitlement check the platform performs for 3265 * any reason will update the cached value. 3266 * 3267 * @param type the downstream type of tethering. Must be one of 3268 * {@link #TETHERING_WIFI}, 3269 * {@link #TETHERING_USB}, or 3270 * {@link #TETHERING_BLUETOOTH}. 3271 * @param showEntitlementUi a boolean indicating whether to run UI-based entitlement check. 3272 * @param executor the executor on which callback will be invoked. 3273 * @param listener an {@link OnTetheringEntitlementResultListener} which will be called to 3274 * notify the caller of the result of entitlement check. The listener may be called zero 3275 * or one time. 3276 * @deprecated Use {@link TetheringManager#requestLatestTetheringEntitlementResult} instead. 3277 * {@hide} 3278 */ 3279 @SystemApi 3280 @Deprecated 3281 @RequiresPermission(android.Manifest.permission.TETHER_PRIVILEGED) getLatestTetheringEntitlementResult(int type, boolean showEntitlementUi, @NonNull @CallbackExecutor Executor executor, @NonNull final OnTetheringEntitlementResultListener listener)3282 public void getLatestTetheringEntitlementResult(int type, boolean showEntitlementUi, 3283 @NonNull @CallbackExecutor Executor executor, 3284 @NonNull final OnTetheringEntitlementResultListener listener) { 3285 Objects.requireNonNull(listener, "TetheringEntitlementResultListener cannot be null."); 3286 ResultReceiver wrappedListener = new ResultReceiver(null) { 3287 @Override 3288 protected void onReceiveResult(int resultCode, Bundle resultData) { 3289 final long token = Binder.clearCallingIdentity(); 3290 try { 3291 executor.execute(() -> { 3292 listener.onTetheringEntitlementResult(resultCode); 3293 }); 3294 } finally { 3295 Binder.restoreCallingIdentity(token); 3296 } 3297 } 3298 }; 3299 3300 getTetheringManager().requestLatestTetheringEntitlementResult(type, wrappedListener, 3301 showEntitlementUi); 3302 } 3303 3304 /** 3305 * Report network connectivity status. This is currently used only 3306 * to alter status bar UI. 3307 * <p>This method requires the caller to hold the permission 3308 * {@link android.Manifest.permission#STATUS_BAR}. 3309 * 3310 * @param networkType The type of network you want to report on 3311 * @param percentage The quality of the connection 0 is bad, 100 is good 3312 * @deprecated Types are deprecated. Use {@link #reportNetworkConnectivity} instead. 3313 * {@hide} 3314 */ reportInetCondition(int networkType, int percentage)3315 public void reportInetCondition(int networkType, int percentage) { 3316 printStackTrace(); 3317 try { 3318 mService.reportInetCondition(networkType, percentage); 3319 } catch (RemoteException e) { 3320 throw e.rethrowFromSystemServer(); 3321 } 3322 } 3323 3324 /** 3325 * Report a problem network to the framework. This provides a hint to the system 3326 * that there might be connectivity problems on this network and may cause 3327 * the framework to re-evaluate network connectivity and/or switch to another 3328 * network. 3329 * 3330 * @param network The {@link Network} the application was attempting to use 3331 * or {@code null} to indicate the current default network. 3332 * @deprecated Use {@link #reportNetworkConnectivity} which allows reporting both 3333 * working and non-working connectivity. 3334 */ 3335 @Deprecated reportBadNetwork(@ullable Network network)3336 public void reportBadNetwork(@Nullable Network network) { 3337 printStackTrace(); 3338 try { 3339 // One of these will be ignored because it matches system's current state. 3340 // The other will trigger the necessary reevaluation. 3341 mService.reportNetworkConnectivity(network, true); 3342 mService.reportNetworkConnectivity(network, false); 3343 } catch (RemoteException e) { 3344 throw e.rethrowFromSystemServer(); 3345 } 3346 } 3347 3348 /** 3349 * Report to the framework whether a network has working connectivity. 3350 * This provides a hint to the system that a particular network is providing 3351 * working connectivity or not. In response the framework may re-evaluate 3352 * the network's connectivity and might take further action thereafter. 3353 * 3354 * @param network The {@link Network} the application was attempting to use 3355 * or {@code null} to indicate the current default network. 3356 * @param hasConnectivity {@code true} if the application was able to successfully access the 3357 * Internet using {@code network} or {@code false} if not. 3358 */ reportNetworkConnectivity(@ullable Network network, boolean hasConnectivity)3359 public void reportNetworkConnectivity(@Nullable Network network, boolean hasConnectivity) { 3360 printStackTrace(); 3361 try { 3362 mService.reportNetworkConnectivity(network, hasConnectivity); 3363 } catch (RemoteException e) { 3364 throw e.rethrowFromSystemServer(); 3365 } 3366 } 3367 3368 /** 3369 * Set a network-independent global HTTP proxy. 3370 * 3371 * This sets an HTTP proxy that applies to all networks and overrides any network-specific 3372 * proxy. If set, HTTP libraries that are proxy-aware will use this global proxy when 3373 * accessing any network, regardless of what the settings for that network are. 3374 * 3375 * Note that HTTP proxies are by nature typically network-dependent, and setting a global 3376 * proxy is likely to break networking on multiple networks. This method is only meant 3377 * for device policy clients looking to do general internal filtering or similar use cases. 3378 * 3379 * {@see #getGlobalProxy} 3380 * {@see LinkProperties#getHttpProxy} 3381 * 3382 * @param p A {@link ProxyInfo} object defining the new global HTTP proxy. Calling this 3383 * method with a {@code null} value will clear the global HTTP proxy. 3384 * @hide 3385 */ 3386 // Used by Device Policy Manager to set the global proxy. 3387 @SystemApi(client = MODULE_LIBRARIES) 3388 @RequiresPermission(android.Manifest.permission.NETWORK_STACK) setGlobalProxy(@ullable final ProxyInfo p)3389 public void setGlobalProxy(@Nullable final ProxyInfo p) { 3390 try { 3391 mService.setGlobalProxy(p); 3392 } catch (RemoteException e) { 3393 throw e.rethrowFromSystemServer(); 3394 } 3395 } 3396 3397 /** 3398 * Retrieve any network-independent global HTTP proxy. 3399 * 3400 * @return {@link ProxyInfo} for the current global HTTP proxy or {@code null} 3401 * if no global HTTP proxy is set. 3402 * @hide 3403 */ 3404 @SystemApi(client = MODULE_LIBRARIES) 3405 @Nullable getGlobalProxy()3406 public ProxyInfo getGlobalProxy() { 3407 try { 3408 return mService.getGlobalProxy(); 3409 } catch (RemoteException e) { 3410 throw e.rethrowFromSystemServer(); 3411 } 3412 } 3413 3414 /** 3415 * Retrieve the global HTTP proxy, or if no global HTTP proxy is set, a 3416 * network-specific HTTP proxy. If {@code network} is null, the 3417 * network-specific proxy returned is the proxy of the default active 3418 * network. 3419 * 3420 * @return {@link ProxyInfo} for the current global HTTP proxy, or if no 3421 * global HTTP proxy is set, {@code ProxyInfo} for {@code network}, 3422 * or when {@code network} is {@code null}, 3423 * the {@code ProxyInfo} for the default active network. Returns 3424 * {@code null} when no proxy applies or the caller doesn't have 3425 * permission to use {@code network}. 3426 * @hide 3427 */ getProxyForNetwork(Network network)3428 public ProxyInfo getProxyForNetwork(Network network) { 3429 try { 3430 return mService.getProxyForNetwork(network); 3431 } catch (RemoteException e) { 3432 throw e.rethrowFromSystemServer(); 3433 } 3434 } 3435 3436 /** 3437 * Get the current default HTTP proxy settings. If a global proxy is set it will be returned, 3438 * otherwise if this process is bound to a {@link Network} using 3439 * {@link #bindProcessToNetwork} then that {@code Network}'s proxy is returned, otherwise 3440 * the default network's proxy is returned. 3441 * 3442 * @return the {@link ProxyInfo} for the current HTTP proxy, or {@code null} if no 3443 * HTTP proxy is active. 3444 */ 3445 @Nullable getDefaultProxy()3446 public ProxyInfo getDefaultProxy() { 3447 return getProxyForNetwork(getBoundNetworkForProcess()); 3448 } 3449 3450 /** 3451 * Returns true if the hardware supports the given network type 3452 * else it returns false. This doesn't indicate we have coverage 3453 * or are authorized onto a network, just whether or not the 3454 * hardware supports it. For example a GSM phone without a SIM 3455 * should still return {@code true} for mobile data, but a wifi only 3456 * tablet would return {@code false}. 3457 * 3458 * @param networkType The network type we'd like to check 3459 * @return {@code true} if supported, else {@code false} 3460 * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead. 3461 * @hide 3462 */ 3463 @Deprecated 3464 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) 3465 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 130143562) isNetworkSupported(int networkType)3466 public boolean isNetworkSupported(int networkType) { 3467 try { 3468 return mService.isNetworkSupported(networkType); 3469 } catch (RemoteException e) { 3470 throw e.rethrowFromSystemServer(); 3471 } 3472 } 3473 3474 /** 3475 * Returns if the currently active data network is metered. A network is 3476 * classified as metered when the user is sensitive to heavy data usage on 3477 * that connection due to monetary costs, data limitations or 3478 * battery/performance issues. You should check this before doing large 3479 * data transfers, and warn the user or delay the operation until another 3480 * network is available. 3481 * 3482 * @return {@code true} if large transfers should be avoided, otherwise 3483 * {@code false}. 3484 */ 3485 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) isActiveNetworkMetered()3486 public boolean isActiveNetworkMetered() { 3487 try { 3488 return mService.isActiveNetworkMetered(); 3489 } catch (RemoteException e) { 3490 throw e.rethrowFromSystemServer(); 3491 } 3492 } 3493 3494 /** 3495 * Set sign in error notification to visible or invisible 3496 * 3497 * @hide 3498 * @deprecated Doesn't properly deal with multiple connected networks of the same type. 3499 */ 3500 @Deprecated setProvisioningNotificationVisible(boolean visible, int networkType, String action)3501 public void setProvisioningNotificationVisible(boolean visible, int networkType, 3502 String action) { 3503 try { 3504 mService.setProvisioningNotificationVisible(visible, networkType, action); 3505 } catch (RemoteException e) { 3506 throw e.rethrowFromSystemServer(); 3507 } 3508 } 3509 3510 /** 3511 * Set the value for enabling/disabling airplane mode 3512 * 3513 * @param enable whether to enable airplane mode or not 3514 * 3515 * @hide 3516 */ 3517 @RequiresPermission(anyOf = { 3518 android.Manifest.permission.NETWORK_AIRPLANE_MODE, 3519 android.Manifest.permission.NETWORK_SETTINGS, 3520 android.Manifest.permission.NETWORK_SETUP_WIZARD, 3521 android.Manifest.permission.NETWORK_STACK}) 3522 @SystemApi setAirplaneMode(boolean enable)3523 public void setAirplaneMode(boolean enable) { 3524 try { 3525 mService.setAirplaneMode(enable); 3526 } catch (RemoteException e) { 3527 throw e.rethrowFromSystemServer(); 3528 } 3529 } 3530 3531 /** 3532 * Registers the specified {@link NetworkProvider}. 3533 * Each listener must only be registered once. The listener can be unregistered with 3534 * {@link #unregisterNetworkProvider}. 3535 * 3536 * @param provider the provider to register 3537 * @return the ID of the provider. This ID must be used by the provider when registering 3538 * {@link android.net.NetworkAgent}s. 3539 * @hide 3540 */ 3541 @SystemApi 3542 @RequiresPermission(anyOf = { 3543 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 3544 android.Manifest.permission.NETWORK_FACTORY}) registerNetworkProvider(@onNull NetworkProvider provider)3545 public int registerNetworkProvider(@NonNull NetworkProvider provider) { 3546 if (provider.getProviderId() != NetworkProvider.ID_NONE) { 3547 throw new IllegalStateException("NetworkProviders can only be registered once"); 3548 } 3549 3550 try { 3551 int providerId = mService.registerNetworkProvider(provider.getMessenger(), 3552 provider.getName()); 3553 provider.setProviderId(providerId); 3554 } catch (RemoteException e) { 3555 throw e.rethrowFromSystemServer(); 3556 } 3557 return provider.getProviderId(); 3558 } 3559 3560 /** 3561 * Unregisters the specified NetworkProvider. 3562 * 3563 * @param provider the provider to unregister 3564 * @hide 3565 */ 3566 @SystemApi 3567 @RequiresPermission(anyOf = { 3568 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 3569 android.Manifest.permission.NETWORK_FACTORY}) unregisterNetworkProvider(@onNull NetworkProvider provider)3570 public void unregisterNetworkProvider(@NonNull NetworkProvider provider) { 3571 try { 3572 mService.unregisterNetworkProvider(provider.getMessenger()); 3573 } catch (RemoteException e) { 3574 throw e.rethrowFromSystemServer(); 3575 } 3576 provider.setProviderId(NetworkProvider.ID_NONE); 3577 } 3578 3579 /** 3580 * Register or update a network offer with ConnectivityService. 3581 * 3582 * ConnectivityService keeps track of offers made by the various providers and matches 3583 * them to networking requests made by apps or the system. A callback identifies an offer 3584 * uniquely, and later calls with the same callback update the offer. The provider supplies a 3585 * score and the capabilities of the network it might be able to bring up ; these act as 3586 * filters used by ConnectivityService to only send those requests that can be fulfilled by the 3587 * provider. 3588 * 3589 * The provider is under no obligation to be able to bring up the network it offers at any 3590 * given time. Instead, this mechanism is meant to limit requests received by providers 3591 * to those they actually have a chance to fulfill, as providers don't have a way to compare 3592 * the quality of the network satisfying a given request to their own offer. 3593 * 3594 * An offer can be updated by calling this again with the same callback object. This is 3595 * similar to calling unofferNetwork and offerNetwork again, but will only update the 3596 * provider with the changes caused by the changes in the offer. 3597 * 3598 * @param provider The provider making this offer. 3599 * @param score The prospective score of the network. 3600 * @param caps The prospective capabilities of the network. 3601 * @param callback The callback to call when this offer is needed or unneeded. 3602 * @hide exposed via the NetworkProvider class. 3603 */ 3604 @RequiresPermission(anyOf = { 3605 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 3606 android.Manifest.permission.NETWORK_FACTORY}) offerNetwork(@onNull final int providerId, @NonNull final NetworkScore score, @NonNull final NetworkCapabilities caps, @NonNull final INetworkOfferCallback callback)3607 public void offerNetwork(@NonNull final int providerId, 3608 @NonNull final NetworkScore score, @NonNull final NetworkCapabilities caps, 3609 @NonNull final INetworkOfferCallback callback) { 3610 try { 3611 mService.offerNetwork(providerId, 3612 Objects.requireNonNull(score, "null score"), 3613 Objects.requireNonNull(caps, "null caps"), 3614 Objects.requireNonNull(callback, "null callback")); 3615 } catch (RemoteException e) { 3616 throw e.rethrowFromSystemServer(); 3617 } 3618 } 3619 3620 /** 3621 * Withdraw a network offer made with {@link #offerNetwork}. 3622 * 3623 * @param callback The callback passed at registration time. This must be the same object 3624 * that was passed to {@link #offerNetwork} 3625 * @hide exposed via the NetworkProvider class. 3626 */ unofferNetwork(@onNull final INetworkOfferCallback callback)3627 public void unofferNetwork(@NonNull final INetworkOfferCallback callback) { 3628 try { 3629 mService.unofferNetwork(Objects.requireNonNull(callback)); 3630 } catch (RemoteException e) { 3631 throw e.rethrowFromSystemServer(); 3632 } 3633 } 3634 /** @hide exposed via the NetworkProvider class. */ 3635 @RequiresPermission(anyOf = { 3636 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 3637 android.Manifest.permission.NETWORK_FACTORY}) declareNetworkRequestUnfulfillable(@onNull NetworkRequest request)3638 public void declareNetworkRequestUnfulfillable(@NonNull NetworkRequest request) { 3639 try { 3640 mService.declareNetworkRequestUnfulfillable(request); 3641 } catch (RemoteException e) { 3642 throw e.rethrowFromSystemServer(); 3643 } 3644 } 3645 3646 /** 3647 * @hide 3648 * Register a NetworkAgent with ConnectivityService. 3649 * @return Network corresponding to NetworkAgent. 3650 */ 3651 @RequiresPermission(anyOf = { 3652 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 3653 android.Manifest.permission.NETWORK_FACTORY}) registerNetworkAgent(INetworkAgent na, NetworkInfo ni, LinkProperties lp, NetworkCapabilities nc, @NonNull NetworkScore score, NetworkAgentConfig config, int providerId)3654 public Network registerNetworkAgent(INetworkAgent na, NetworkInfo ni, LinkProperties lp, 3655 NetworkCapabilities nc, @NonNull NetworkScore score, NetworkAgentConfig config, 3656 int providerId) { 3657 try { 3658 return mService.registerNetworkAgent(na, ni, lp, nc, score, config, providerId); 3659 } catch (RemoteException e) { 3660 throw e.rethrowFromSystemServer(); 3661 } 3662 } 3663 3664 /** 3665 * Base class for {@code NetworkRequest} callbacks. Used for notifications about network 3666 * changes. Should be extended by applications wanting notifications. 3667 * 3668 * A {@code NetworkCallback} is registered by calling 3669 * {@link #requestNetwork(NetworkRequest, NetworkCallback)}, 3670 * {@link #registerNetworkCallback(NetworkRequest, NetworkCallback)}, 3671 * or {@link #registerDefaultNetworkCallback(NetworkCallback)}. A {@code NetworkCallback} is 3672 * unregistered by calling {@link #unregisterNetworkCallback(NetworkCallback)}. 3673 * A {@code NetworkCallback} should be registered at most once at any time. 3674 * A {@code NetworkCallback} that has been unregistered can be registered again. 3675 */ 3676 public static class NetworkCallback { 3677 /** 3678 * No flags associated with this callback. 3679 * @hide 3680 */ 3681 public static final int FLAG_NONE = 0; 3682 3683 /** 3684 * Inclusion of this flag means location-sensitive redaction requests keeping location info. 3685 * 3686 * Some objects like {@link NetworkCapabilities} may contain location-sensitive information. 3687 * Prior to Android 12, this information is always returned to apps holding the appropriate 3688 * permission, possibly noting that the app has used location. 3689 * <p>In Android 12 and above, by default the sent objects do not contain any location 3690 * information, even if the app holds the necessary permissions, and the system does not 3691 * take note of location usage by the app. Apps can request that location information is 3692 * included, in which case the system will check location permission and the location 3693 * toggle state, and take note of location usage by the app if any such information is 3694 * returned. 3695 * 3696 * Use this flag to include any location sensitive data in {@link NetworkCapabilities} sent 3697 * via {@link #onCapabilitiesChanged(Network, NetworkCapabilities)}. 3698 * <p> 3699 * These include: 3700 * <li> Some transport info instances (retrieved via 3701 * {@link NetworkCapabilities#getTransportInfo()}) like {@link android.net.wifi.WifiInfo} 3702 * contain location sensitive information. 3703 * <li> OwnerUid (retrieved via {@link NetworkCapabilities#getOwnerUid()} is location 3704 * sensitive for wifi suggestor apps (i.e using 3705 * {@link android.net.wifi.WifiNetworkSuggestion WifiNetworkSuggestion}).</li> 3706 * </p> 3707 * <p> 3708 * Note: 3709 * <li> Retrieving this location sensitive information (subject to app's location 3710 * permissions) will be noted by system. </li> 3711 * <li> Without this flag any {@link NetworkCapabilities} provided via the callback does 3712 * not include location sensitive information. 3713 */ 3714 // Note: Some existing fields which are location sensitive may still be included without 3715 // this flag if the app targets SDK < S (to maintain backwards compatibility). 3716 public static final int FLAG_INCLUDE_LOCATION_INFO = 1 << 0; 3717 3718 /** @hide */ 3719 @Retention(RetentionPolicy.SOURCE) 3720 @IntDef(flag = true, prefix = "FLAG_", value = { 3721 FLAG_NONE, 3722 FLAG_INCLUDE_LOCATION_INFO 3723 }) 3724 public @interface Flag { } 3725 3726 /** 3727 * All the valid flags for error checking. 3728 */ 3729 private static final int VALID_FLAGS = FLAG_INCLUDE_LOCATION_INFO; 3730 NetworkCallback()3731 public NetworkCallback() { 3732 this(FLAG_NONE); 3733 } 3734 NetworkCallback(@lag int flags)3735 public NetworkCallback(@Flag int flags) { 3736 if ((flags & VALID_FLAGS) != flags) { 3737 throw new IllegalArgumentException("Invalid flags"); 3738 } 3739 mFlags = flags; 3740 } 3741 3742 /** 3743 * Called when the framework connects to a new network to evaluate whether it satisfies this 3744 * request. If evaluation succeeds, this callback may be followed by an {@link #onAvailable} 3745 * callback. There is no guarantee that this new network will satisfy any requests, or that 3746 * the network will stay connected for longer than the time necessary to evaluate it. 3747 * <p> 3748 * Most applications <b>should not</b> act on this callback, and should instead use 3749 * {@link #onAvailable}. This callback is intended for use by applications that can assist 3750 * the framework in properly evaluating the network — for example, an application that 3751 * can automatically log in to a captive portal without user intervention. 3752 * 3753 * @param network The {@link Network} of the network that is being evaluated. 3754 * 3755 * @hide 3756 */ onPreCheck(@onNull Network network)3757 public void onPreCheck(@NonNull Network network) {} 3758 3759 /** 3760 * Called when the framework connects and has declared a new network ready for use. 3761 * This callback may be called more than once if the {@link Network} that is 3762 * satisfying the request changes. 3763 * 3764 * @param network The {@link Network} of the satisfying network. 3765 * @param networkCapabilities The {@link NetworkCapabilities} of the satisfying network. 3766 * @param linkProperties The {@link LinkProperties} of the satisfying network. 3767 * @param blocked Whether access to the {@link Network} is blocked due to system policy. 3768 * @hide 3769 */ onAvailable(@onNull Network network, @NonNull NetworkCapabilities networkCapabilities, @NonNull LinkProperties linkProperties, @BlockedReason int blocked)3770 public final void onAvailable(@NonNull Network network, 3771 @NonNull NetworkCapabilities networkCapabilities, 3772 @NonNull LinkProperties linkProperties, @BlockedReason int blocked) { 3773 // Internally only this method is called when a new network is available, and 3774 // it calls the callback in the same way and order that older versions used 3775 // to call so as not to change the behavior. 3776 onAvailable(network, networkCapabilities, linkProperties, blocked != 0); 3777 onBlockedStatusChanged(network, blocked); 3778 } 3779 3780 /** 3781 * Legacy variant of onAvailable that takes a boolean blocked reason. 3782 * 3783 * This method has never been public API, but it's not final, so there may be apps that 3784 * implemented it and rely on it being called. Do our best not to break them. 3785 * Note: such apps will also get a second call to onBlockedStatusChanged immediately after 3786 * this method is called. There does not seem to be a way to avoid this. 3787 * TODO: add a compat check to move apps off this method, and eventually stop calling it. 3788 * 3789 * @hide 3790 */ onAvailable(@onNull Network network, @NonNull NetworkCapabilities networkCapabilities, @NonNull LinkProperties linkProperties, boolean blocked)3791 public void onAvailable(@NonNull Network network, 3792 @NonNull NetworkCapabilities networkCapabilities, 3793 @NonNull LinkProperties linkProperties, boolean blocked) { 3794 onAvailable(network); 3795 if (!networkCapabilities.hasCapability( 3796 NetworkCapabilities.NET_CAPABILITY_NOT_SUSPENDED)) { 3797 onNetworkSuspended(network); 3798 } 3799 onCapabilitiesChanged(network, networkCapabilities); 3800 onLinkPropertiesChanged(network, linkProperties); 3801 // No call to onBlockedStatusChanged here. That is done by the caller. 3802 } 3803 3804 /** 3805 * Called when the framework connects and has declared a new network ready for use. 3806 * 3807 * <p>For callbacks registered with {@link #registerNetworkCallback}, multiple networks may 3808 * be available at the same time, and onAvailable will be called for each of these as they 3809 * appear. 3810 * 3811 * <p>For callbacks registered with {@link #requestNetwork} and 3812 * {@link #registerDefaultNetworkCallback}, this means the network passed as an argument 3813 * is the new best network for this request and is now tracked by this callback ; this 3814 * callback will no longer receive method calls about other networks that may have been 3815 * passed to this method previously. The previously-best network may have disconnected, or 3816 * it may still be around and the newly-best network may simply be better. 3817 * 3818 * <p>Starting with {@link android.os.Build.VERSION_CODES#O}, this will always immediately 3819 * be followed by a call to {@link #onCapabilitiesChanged(Network, NetworkCapabilities)} 3820 * then by a call to {@link #onLinkPropertiesChanged(Network, LinkProperties)}, and a call 3821 * to {@link #onBlockedStatusChanged(Network, boolean)}. 3822 * 3823 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or 3824 * {@link #getLinkProperties(Network)} or other synchronous ConnectivityManager methods in 3825 * this callback as this is prone to race conditions (there is no guarantee the objects 3826 * returned by these methods will be current). Instead, wait for a call to 3827 * {@link #onCapabilitiesChanged(Network, NetworkCapabilities)} and 3828 * {@link #onLinkPropertiesChanged(Network, LinkProperties)} whose arguments are guaranteed 3829 * to be well-ordered with respect to other callbacks. 3830 * 3831 * @param network The {@link Network} of the satisfying network. 3832 */ onAvailable(@onNull Network network)3833 public void onAvailable(@NonNull Network network) {} 3834 3835 /** 3836 * Called when the network is about to be lost, typically because there are no outstanding 3837 * requests left for it. This may be paired with a {@link NetworkCallback#onAvailable} call 3838 * with the new replacement network for graceful handover. This method is not guaranteed 3839 * to be called before {@link NetworkCallback#onLost} is called, for example in case a 3840 * network is suddenly disconnected. 3841 * 3842 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or 3843 * {@link #getLinkProperties(Network)} or other synchronous ConnectivityManager methods in 3844 * this callback as this is prone to race conditions ; calling these methods while in a 3845 * callback may return an outdated or even a null object. 3846 * 3847 * @param network The {@link Network} that is about to be lost. 3848 * @param maxMsToLive The time in milliseconds the system intends to keep the network 3849 * connected for graceful handover; note that the network may still 3850 * suffer a hard loss at any time. 3851 */ onLosing(@onNull Network network, int maxMsToLive)3852 public void onLosing(@NonNull Network network, int maxMsToLive) {} 3853 3854 /** 3855 * Called when a network disconnects or otherwise no longer satisfies this request or 3856 * callback. 3857 * 3858 * <p>If the callback was registered with requestNetwork() or 3859 * registerDefaultNetworkCallback(), it will only be invoked against the last network 3860 * returned by onAvailable() when that network is lost and no other network satisfies 3861 * the criteria of the request. 3862 * 3863 * <p>If the callback was registered with registerNetworkCallback() it will be called for 3864 * each network which no longer satisfies the criteria of the callback. 3865 * 3866 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or 3867 * {@link #getLinkProperties(Network)} or other synchronous ConnectivityManager methods in 3868 * this callback as this is prone to race conditions ; calling these methods while in a 3869 * callback may return an outdated or even a null object. 3870 * 3871 * @param network The {@link Network} lost. 3872 */ onLost(@onNull Network network)3873 public void onLost(@NonNull Network network) {} 3874 3875 /** 3876 * Called if no network is found within the timeout time specified in 3877 * {@link #requestNetwork(NetworkRequest, NetworkCallback, int)} call or if the 3878 * requested network request cannot be fulfilled (whether or not a timeout was 3879 * specified). When this callback is invoked the associated 3880 * {@link NetworkRequest} will have already been removed and released, as if 3881 * {@link #unregisterNetworkCallback(NetworkCallback)} had been called. 3882 */ onUnavailable()3883 public void onUnavailable() {} 3884 3885 /** 3886 * Called when the network corresponding to this request changes capabilities but still 3887 * satisfies the requested criteria. 3888 * 3889 * <p>Starting with {@link android.os.Build.VERSION_CODES#O} this method is guaranteed 3890 * to be called immediately after {@link #onAvailable}. 3891 * 3892 * <p>Do NOT call {@link #getLinkProperties(Network)} or other synchronous 3893 * ConnectivityManager methods in this callback as this is prone to race conditions : 3894 * calling these methods while in a callback may return an outdated or even a null object. 3895 * 3896 * @param network The {@link Network} whose capabilities have changed. 3897 * @param networkCapabilities The new {@link NetworkCapabilities} for this 3898 * network. 3899 */ onCapabilitiesChanged(@onNull Network network, @NonNull NetworkCapabilities networkCapabilities)3900 public void onCapabilitiesChanged(@NonNull Network network, 3901 @NonNull NetworkCapabilities networkCapabilities) {} 3902 3903 /** 3904 * Called when the network corresponding to this request changes {@link LinkProperties}. 3905 * 3906 * <p>Starting with {@link android.os.Build.VERSION_CODES#O} this method is guaranteed 3907 * to be called immediately after {@link #onAvailable}. 3908 * 3909 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or other synchronous 3910 * ConnectivityManager methods in this callback as this is prone to race conditions : 3911 * calling these methods while in a callback may return an outdated or even a null object. 3912 * 3913 * @param network The {@link Network} whose link properties have changed. 3914 * @param linkProperties The new {@link LinkProperties} for this network. 3915 */ onLinkPropertiesChanged(@onNull Network network, @NonNull LinkProperties linkProperties)3916 public void onLinkPropertiesChanged(@NonNull Network network, 3917 @NonNull LinkProperties linkProperties) {} 3918 3919 /** 3920 * Called when the network the framework connected to for this request suspends data 3921 * transmission temporarily. 3922 * 3923 * <p>This generally means that while the TCP connections are still live temporarily 3924 * network data fails to transfer. To give a specific example, this is used on cellular 3925 * networks to mask temporary outages when driving through a tunnel, etc. In general this 3926 * means read operations on sockets on this network will block once the buffers are 3927 * drained, and write operations will block once the buffers are full. 3928 * 3929 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or 3930 * {@link #getLinkProperties(Network)} or other synchronous ConnectivityManager methods in 3931 * this callback as this is prone to race conditions (there is no guarantee the objects 3932 * returned by these methods will be current). 3933 * 3934 * @hide 3935 */ onNetworkSuspended(@onNull Network network)3936 public void onNetworkSuspended(@NonNull Network network) {} 3937 3938 /** 3939 * Called when the network the framework connected to for this request 3940 * returns from a {@link NetworkInfo.State#SUSPENDED} state. This should always be 3941 * preceded by a matching {@link NetworkCallback#onNetworkSuspended} call. 3942 3943 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or 3944 * {@link #getLinkProperties(Network)} or other synchronous ConnectivityManager methods in 3945 * this callback as this is prone to race conditions : calling these methods while in a 3946 * callback may return an outdated or even a null object. 3947 * 3948 * @hide 3949 */ onNetworkResumed(@onNull Network network)3950 public void onNetworkResumed(@NonNull Network network) {} 3951 3952 /** 3953 * Called when access to the specified network is blocked or unblocked. 3954 * 3955 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or 3956 * {@link #getLinkProperties(Network)} or other synchronous ConnectivityManager methods in 3957 * this callback as this is prone to race conditions : calling these methods while in a 3958 * callback may return an outdated or even a null object. 3959 * 3960 * @param network The {@link Network} whose blocked status has changed. 3961 * @param blocked The blocked status of this {@link Network}. 3962 */ onBlockedStatusChanged(@onNull Network network, boolean blocked)3963 public void onBlockedStatusChanged(@NonNull Network network, boolean blocked) {} 3964 3965 /** 3966 * Called when access to the specified network is blocked or unblocked, or the reason for 3967 * access being blocked changes. 3968 * 3969 * If a NetworkCallback object implements this method, 3970 * {@link #onBlockedStatusChanged(Network, boolean)} will not be called. 3971 * 3972 * <p>Do NOT call {@link #getNetworkCapabilities(Network)} or 3973 * {@link #getLinkProperties(Network)} or other synchronous ConnectivityManager methods in 3974 * this callback as this is prone to race conditions : calling these methods while in a 3975 * callback may return an outdated or even a null object. 3976 * 3977 * @param network The {@link Network} whose blocked status has changed. 3978 * @param blocked The blocked status of this {@link Network}. 3979 * @hide 3980 */ 3981 @SystemApi(client = MODULE_LIBRARIES) onBlockedStatusChanged(@onNull Network network, @BlockedReason int blocked)3982 public void onBlockedStatusChanged(@NonNull Network network, @BlockedReason int blocked) { 3983 onBlockedStatusChanged(network, blocked != 0); 3984 } 3985 3986 private NetworkRequest networkRequest; 3987 private final int mFlags; 3988 } 3989 3990 /** 3991 * Constant error codes used by ConnectivityService to communicate about failures and errors 3992 * across a Binder boundary. 3993 * @hide 3994 */ 3995 public interface Errors { 3996 int TOO_MANY_REQUESTS = 1; 3997 } 3998 3999 /** @hide */ 4000 public static class TooManyRequestsException extends RuntimeException {} 4001 convertServiceException(ServiceSpecificException e)4002 private static RuntimeException convertServiceException(ServiceSpecificException e) { 4003 switch (e.errorCode) { 4004 case Errors.TOO_MANY_REQUESTS: 4005 return new TooManyRequestsException(); 4006 default: 4007 Log.w(TAG, "Unknown service error code " + e.errorCode); 4008 return new RuntimeException(e); 4009 } 4010 } 4011 4012 /** @hide */ 4013 public static final int CALLBACK_PRECHECK = 1; 4014 /** @hide */ 4015 public static final int CALLBACK_AVAILABLE = 2; 4016 /** @hide arg1 = TTL */ 4017 public static final int CALLBACK_LOSING = 3; 4018 /** @hide */ 4019 public static final int CALLBACK_LOST = 4; 4020 /** @hide */ 4021 public static final int CALLBACK_UNAVAIL = 5; 4022 /** @hide */ 4023 public static final int CALLBACK_CAP_CHANGED = 6; 4024 /** @hide */ 4025 public static final int CALLBACK_IP_CHANGED = 7; 4026 /** @hide obj = NetworkCapabilities, arg1 = seq number */ 4027 private static final int EXPIRE_LEGACY_REQUEST = 8; 4028 /** @hide */ 4029 public static final int CALLBACK_SUSPENDED = 9; 4030 /** @hide */ 4031 public static final int CALLBACK_RESUMED = 10; 4032 /** @hide */ 4033 public static final int CALLBACK_BLK_CHANGED = 11; 4034 4035 /** @hide */ getCallbackName(int whichCallback)4036 public static String getCallbackName(int whichCallback) { 4037 switch (whichCallback) { 4038 case CALLBACK_PRECHECK: return "CALLBACK_PRECHECK"; 4039 case CALLBACK_AVAILABLE: return "CALLBACK_AVAILABLE"; 4040 case CALLBACK_LOSING: return "CALLBACK_LOSING"; 4041 case CALLBACK_LOST: return "CALLBACK_LOST"; 4042 case CALLBACK_UNAVAIL: return "CALLBACK_UNAVAIL"; 4043 case CALLBACK_CAP_CHANGED: return "CALLBACK_CAP_CHANGED"; 4044 case CALLBACK_IP_CHANGED: return "CALLBACK_IP_CHANGED"; 4045 case EXPIRE_LEGACY_REQUEST: return "EXPIRE_LEGACY_REQUEST"; 4046 case CALLBACK_SUSPENDED: return "CALLBACK_SUSPENDED"; 4047 case CALLBACK_RESUMED: return "CALLBACK_RESUMED"; 4048 case CALLBACK_BLK_CHANGED: return "CALLBACK_BLK_CHANGED"; 4049 default: 4050 return Integer.toString(whichCallback); 4051 } 4052 } 4053 4054 private class CallbackHandler extends Handler { 4055 private static final String TAG = "ConnectivityManager.CallbackHandler"; 4056 private static final boolean DBG = false; 4057 CallbackHandler(Looper looper)4058 CallbackHandler(Looper looper) { 4059 super(looper); 4060 } 4061 CallbackHandler(Handler handler)4062 CallbackHandler(Handler handler) { 4063 this(Objects.requireNonNull(handler, "Handler cannot be null.").getLooper()); 4064 } 4065 4066 @Override handleMessage(Message message)4067 public void handleMessage(Message message) { 4068 if (message.what == EXPIRE_LEGACY_REQUEST) { 4069 expireRequest((NetworkCapabilities) message.obj, message.arg1); 4070 return; 4071 } 4072 4073 final NetworkRequest request = getObject(message, NetworkRequest.class); 4074 final Network network = getObject(message, Network.class); 4075 final NetworkCallback callback; 4076 synchronized (sCallbacks) { 4077 callback = sCallbacks.get(request); 4078 if (callback == null) { 4079 Log.w(TAG, 4080 "callback not found for " + getCallbackName(message.what) + " message"); 4081 return; 4082 } 4083 if (message.what == CALLBACK_UNAVAIL) { 4084 sCallbacks.remove(request); 4085 callback.networkRequest = ALREADY_UNREGISTERED; 4086 } 4087 } 4088 if (DBG) { 4089 Log.d(TAG, getCallbackName(message.what) + " for network " + network); 4090 } 4091 4092 switch (message.what) { 4093 case CALLBACK_PRECHECK: { 4094 callback.onPreCheck(network); 4095 break; 4096 } 4097 case CALLBACK_AVAILABLE: { 4098 NetworkCapabilities cap = getObject(message, NetworkCapabilities.class); 4099 LinkProperties lp = getObject(message, LinkProperties.class); 4100 callback.onAvailable(network, cap, lp, message.arg1); 4101 break; 4102 } 4103 case CALLBACK_LOSING: { 4104 callback.onLosing(network, message.arg1); 4105 break; 4106 } 4107 case CALLBACK_LOST: { 4108 callback.onLost(network); 4109 break; 4110 } 4111 case CALLBACK_UNAVAIL: { 4112 callback.onUnavailable(); 4113 break; 4114 } 4115 case CALLBACK_CAP_CHANGED: { 4116 NetworkCapabilities cap = getObject(message, NetworkCapabilities.class); 4117 callback.onCapabilitiesChanged(network, cap); 4118 break; 4119 } 4120 case CALLBACK_IP_CHANGED: { 4121 LinkProperties lp = getObject(message, LinkProperties.class); 4122 callback.onLinkPropertiesChanged(network, lp); 4123 break; 4124 } 4125 case CALLBACK_SUSPENDED: { 4126 callback.onNetworkSuspended(network); 4127 break; 4128 } 4129 case CALLBACK_RESUMED: { 4130 callback.onNetworkResumed(network); 4131 break; 4132 } 4133 case CALLBACK_BLK_CHANGED: { 4134 callback.onBlockedStatusChanged(network, message.arg1); 4135 } 4136 } 4137 } 4138 getObject(Message msg, Class<T> c)4139 private <T> T getObject(Message msg, Class<T> c) { 4140 return (T) msg.getData().getParcelable(c.getSimpleName()); 4141 } 4142 } 4143 getDefaultHandler()4144 private CallbackHandler getDefaultHandler() { 4145 synchronized (sCallbacks) { 4146 if (sCallbackHandler == null) { 4147 sCallbackHandler = new CallbackHandler(ConnectivityThread.getInstanceLooper()); 4148 } 4149 return sCallbackHandler; 4150 } 4151 } 4152 4153 private static final HashMap<NetworkRequest, NetworkCallback> sCallbacks = new HashMap<>(); 4154 private static CallbackHandler sCallbackHandler; 4155 sendRequestForNetwork(int asUid, NetworkCapabilities need, NetworkCallback callback, int timeoutMs, NetworkRequest.Type reqType, int legacyType, CallbackHandler handler)4156 private NetworkRequest sendRequestForNetwork(int asUid, NetworkCapabilities need, 4157 NetworkCallback callback, int timeoutMs, NetworkRequest.Type reqType, int legacyType, 4158 CallbackHandler handler) { 4159 printStackTrace(); 4160 checkCallbackNotNull(callback); 4161 if (reqType != TRACK_DEFAULT && reqType != TRACK_SYSTEM_DEFAULT && need == null) { 4162 throw new IllegalArgumentException("null NetworkCapabilities"); 4163 } 4164 final NetworkRequest request; 4165 final String callingPackageName = mContext.getOpPackageName(); 4166 try { 4167 synchronized(sCallbacks) { 4168 if (callback.networkRequest != null 4169 && callback.networkRequest != ALREADY_UNREGISTERED) { 4170 // TODO: throw exception instead and enforce 1:1 mapping of callbacks 4171 // and requests (http://b/20701525). 4172 Log.e(TAG, "NetworkCallback was already registered"); 4173 } 4174 Messenger messenger = new Messenger(handler); 4175 Binder binder = new Binder(); 4176 final int callbackFlags = callback.mFlags; 4177 if (reqType == LISTEN) { 4178 request = mService.listenForNetwork( 4179 need, messenger, binder, callbackFlags, callingPackageName, 4180 getAttributionTag()); 4181 } else { 4182 request = mService.requestNetwork( 4183 asUid, need, reqType.ordinal(), messenger, timeoutMs, binder, 4184 legacyType, callbackFlags, callingPackageName, getAttributionTag()); 4185 } 4186 if (request != null) { 4187 sCallbacks.put(request, callback); 4188 } 4189 callback.networkRequest = request; 4190 } 4191 } catch (RemoteException e) { 4192 throw e.rethrowFromSystemServer(); 4193 } catch (ServiceSpecificException e) { 4194 throw convertServiceException(e); 4195 } 4196 return request; 4197 } 4198 sendRequestForNetwork(NetworkCapabilities need, NetworkCallback callback, int timeoutMs, NetworkRequest.Type reqType, int legacyType, CallbackHandler handler)4199 private NetworkRequest sendRequestForNetwork(NetworkCapabilities need, NetworkCallback callback, 4200 int timeoutMs, NetworkRequest.Type reqType, int legacyType, CallbackHandler handler) { 4201 return sendRequestForNetwork(Process.INVALID_UID, need, callback, timeoutMs, reqType, 4202 legacyType, handler); 4203 } 4204 4205 /** 4206 * Helper function to request a network with a particular legacy type. 4207 * 4208 * This API is only for use in internal system code that requests networks with legacy type and 4209 * relies on CONNECTIVITY_ACTION broadcasts instead of NetworkCallbacks. New caller should use 4210 * {@link #requestNetwork(NetworkRequest, NetworkCallback, Handler)} instead. 4211 * 4212 * @param request {@link NetworkRequest} describing this request. 4213 * @param timeoutMs The time in milliseconds to attempt looking for a suitable network 4214 * before {@link NetworkCallback#onUnavailable()} is called. The timeout must 4215 * be a positive value (i.e. >0). 4216 * @param legacyType to specify the network type(#TYPE_*). 4217 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4218 * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note 4219 * the callback must not be shared - it uniquely specifies this request. 4220 * 4221 * @hide 4222 */ 4223 @SystemApi 4224 @RequiresPermission(NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK) requestNetwork(@onNull NetworkRequest request, int timeoutMs, int legacyType, @NonNull Handler handler, @NonNull NetworkCallback networkCallback)4225 public void requestNetwork(@NonNull NetworkRequest request, 4226 int timeoutMs, int legacyType, @NonNull Handler handler, 4227 @NonNull NetworkCallback networkCallback) { 4228 if (legacyType == TYPE_NONE) { 4229 throw new IllegalArgumentException("TYPE_NONE is meaningless legacy type"); 4230 } 4231 CallbackHandler cbHandler = new CallbackHandler(handler); 4232 NetworkCapabilities nc = request.networkCapabilities; 4233 sendRequestForNetwork(nc, networkCallback, timeoutMs, REQUEST, legacyType, cbHandler); 4234 } 4235 4236 /** 4237 * Request a network to satisfy a set of {@link NetworkCapabilities}. 4238 * 4239 * <p>This method will attempt to find the best network that matches the passed 4240 * {@link NetworkRequest}, and to bring up one that does if none currently satisfies the 4241 * criteria. The platform will evaluate which network is the best at its own discretion. 4242 * Throughput, latency, cost per byte, policy, user preference and other considerations 4243 * may be factored in the decision of what is considered the best network. 4244 * 4245 * <p>As long as this request is outstanding, the platform will try to maintain the best network 4246 * matching this request, while always attempting to match the request to a better network if 4247 * possible. If a better match is found, the platform will switch this request to the now-best 4248 * network and inform the app of the newly best network by invoking 4249 * {@link NetworkCallback#onAvailable(Network)} on the provided callback. Note that the platform 4250 * will not try to maintain any other network than the best one currently matching the request: 4251 * a network not matching any network request may be disconnected at any time. 4252 * 4253 * <p>For example, an application could use this method to obtain a connected cellular network 4254 * even if the device currently has a data connection over Ethernet. This may cause the cellular 4255 * radio to consume additional power. Or, an application could inform the system that it wants 4256 * a network supporting sending MMSes and have the system let it know about the currently best 4257 * MMS-supporting network through the provided {@link NetworkCallback}. 4258 * 4259 * <p>The status of the request can be followed by listening to the various callbacks described 4260 * in {@link NetworkCallback}. The {@link Network} object passed to the callback methods can be 4261 * used to direct traffic to the network (although accessing some networks may be subject to 4262 * holding specific permissions). Callers will learn about the specific characteristics of the 4263 * network through 4264 * {@link NetworkCallback#onCapabilitiesChanged(Network, NetworkCapabilities)} and 4265 * {@link NetworkCallback#onLinkPropertiesChanged(Network, LinkProperties)}. The methods of the 4266 * provided {@link NetworkCallback} will only be invoked due to changes in the best network 4267 * matching the request at any given time; therefore when a better network matching the request 4268 * becomes available, the {@link NetworkCallback#onAvailable(Network)} method is called 4269 * with the new network after which no further updates are given about the previously-best 4270 * network, unless it becomes the best again at some later time. All callbacks are invoked 4271 * in order on the same thread, which by default is a thread created by the framework running 4272 * in the app. 4273 * {@see #requestNetwork(NetworkRequest, NetworkCallback, Handler)} to change where the 4274 * callbacks are invoked. 4275 * 4276 * <p>This{@link NetworkRequest} will live until released via 4277 * {@link #unregisterNetworkCallback(NetworkCallback)} or the calling application exits, at 4278 * which point the system may let go of the network at any time. 4279 * 4280 * <p>A version of this method which takes a timeout is 4281 * {@link #requestNetwork(NetworkRequest, NetworkCallback, int)}, that an app can use to only 4282 * wait for a limited amount of time for the network to become unavailable. 4283 * 4284 * <p>It is presently unsupported to request a network with mutable 4285 * {@link NetworkCapabilities} such as 4286 * {@link NetworkCapabilities#NET_CAPABILITY_VALIDATED} or 4287 * {@link NetworkCapabilities#NET_CAPABILITY_CAPTIVE_PORTAL} 4288 * as these {@code NetworkCapabilities} represent states that a particular 4289 * network may never attain, and whether a network will attain these states 4290 * is unknown prior to bringing up the network so the framework does not 4291 * know how to go about satisfying a request with these capabilities. 4292 * 4293 * <p>This method requires the caller to hold either the 4294 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 4295 * or the ability to modify system settings as determined by 4296 * {@link android.provider.Settings.System#canWrite}.</p> 4297 * 4298 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4299 * number of outstanding requests to 100 per app (identified by their UID), shared with 4300 * all variants of this method, of {@link #registerNetworkCallback} as well as 4301 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4302 * Requesting a network with this method will count toward this limit. If this limit is 4303 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4304 * make sure to unregister the callbacks with 4305 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4306 * 4307 * @param request {@link NetworkRequest} describing this request. 4308 * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note 4309 * the callback must not be shared - it uniquely specifies this request. 4310 * The callback is invoked on the default internal Handler. 4311 * @throws IllegalArgumentException if {@code request} contains invalid network capabilities. 4312 * @throws SecurityException if missing the appropriate permissions. 4313 * @throws RuntimeException if the app already has too many callbacks registered. 4314 */ requestNetwork(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback)4315 public void requestNetwork(@NonNull NetworkRequest request, 4316 @NonNull NetworkCallback networkCallback) { 4317 requestNetwork(request, networkCallback, getDefaultHandler()); 4318 } 4319 4320 /** 4321 * Request a network to satisfy a set of {@link NetworkCapabilities}. 4322 * 4323 * This method behaves identically to {@link #requestNetwork(NetworkRequest, NetworkCallback)} 4324 * but runs all the callbacks on the passed Handler. 4325 * 4326 * <p>This method has the same permission requirements as 4327 * {@link #requestNetwork(NetworkRequest, NetworkCallback)}, is subject to the same limitations, 4328 * and throws the same exceptions in the same conditions. 4329 * 4330 * @param request {@link NetworkRequest} describing this request. 4331 * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note 4332 * the callback must not be shared - it uniquely specifies this request. 4333 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4334 */ requestNetwork(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback, @NonNull Handler handler)4335 public void requestNetwork(@NonNull NetworkRequest request, 4336 @NonNull NetworkCallback networkCallback, @NonNull Handler handler) { 4337 CallbackHandler cbHandler = new CallbackHandler(handler); 4338 NetworkCapabilities nc = request.networkCapabilities; 4339 sendRequestForNetwork(nc, networkCallback, 0, REQUEST, TYPE_NONE, cbHandler); 4340 } 4341 4342 /** 4343 * Request a network to satisfy a set of {@link NetworkCapabilities}, limited 4344 * by a timeout. 4345 * 4346 * This function behaves identically to the non-timed-out version 4347 * {@link #requestNetwork(NetworkRequest, NetworkCallback)}, but if a suitable network 4348 * is not found within the given time (in milliseconds) the 4349 * {@link NetworkCallback#onUnavailable()} callback is called. The request can still be 4350 * released normally by calling {@link #unregisterNetworkCallback(NetworkCallback)} but does 4351 * not have to be released if timed-out (it is automatically released). Unregistering a 4352 * request that timed out is not an error. 4353 * 4354 * <p>Do not use this method to poll for the existence of specific networks (e.g. with a small 4355 * timeout) - {@link #registerNetworkCallback(NetworkRequest, NetworkCallback)} is provided 4356 * for that purpose. Calling this method will attempt to bring up the requested network. 4357 * 4358 * <p>This method has the same permission requirements as 4359 * {@link #requestNetwork(NetworkRequest, NetworkCallback)}, is subject to the same limitations, 4360 * and throws the same exceptions in the same conditions. 4361 * 4362 * @param request {@link NetworkRequest} describing this request. 4363 * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note 4364 * the callback must not be shared - it uniquely specifies this request. 4365 * @param timeoutMs The time in milliseconds to attempt looking for a suitable network 4366 * before {@link NetworkCallback#onUnavailable()} is called. The timeout must 4367 * be a positive value (i.e. >0). 4368 */ requestNetwork(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback, int timeoutMs)4369 public void requestNetwork(@NonNull NetworkRequest request, 4370 @NonNull NetworkCallback networkCallback, int timeoutMs) { 4371 checkTimeout(timeoutMs); 4372 NetworkCapabilities nc = request.networkCapabilities; 4373 sendRequestForNetwork(nc, networkCallback, timeoutMs, REQUEST, TYPE_NONE, 4374 getDefaultHandler()); 4375 } 4376 4377 /** 4378 * Request a network to satisfy a set of {@link NetworkCapabilities}, limited 4379 * by a timeout. 4380 * 4381 * This method behaves identically to 4382 * {@link #requestNetwork(NetworkRequest, NetworkCallback, int)} but runs all the callbacks 4383 * on the passed Handler. 4384 * 4385 * <p>This method has the same permission requirements as 4386 * {@link #requestNetwork(NetworkRequest, NetworkCallback)}, is subject to the same limitations, 4387 * and throws the same exceptions in the same conditions. 4388 * 4389 * @param request {@link NetworkRequest} describing this request. 4390 * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note 4391 * the callback must not be shared - it uniquely specifies this request. 4392 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4393 * @param timeoutMs The time in milliseconds to attempt looking for a suitable network 4394 * before {@link NetworkCallback#onUnavailable} is called. 4395 */ requestNetwork(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback, @NonNull Handler handler, int timeoutMs)4396 public void requestNetwork(@NonNull NetworkRequest request, 4397 @NonNull NetworkCallback networkCallback, @NonNull Handler handler, int timeoutMs) { 4398 checkTimeout(timeoutMs); 4399 CallbackHandler cbHandler = new CallbackHandler(handler); 4400 NetworkCapabilities nc = request.networkCapabilities; 4401 sendRequestForNetwork(nc, networkCallback, timeoutMs, REQUEST, TYPE_NONE, cbHandler); 4402 } 4403 4404 /** 4405 * The lookup key for a {@link Network} object included with the intent after 4406 * successfully finding a network for the applications request. Retrieve it with 4407 * {@link android.content.Intent#getParcelableExtra(String)}. 4408 * <p> 4409 * Note that if you intend to invoke {@link Network#openConnection(java.net.URL)} 4410 * then you must get a ConnectivityManager instance before doing so. 4411 */ 4412 public static final String EXTRA_NETWORK = "android.net.extra.NETWORK"; 4413 4414 /** 4415 * The lookup key for a {@link NetworkRequest} object included with the intent after 4416 * successfully finding a network for the applications request. Retrieve it with 4417 * {@link android.content.Intent#getParcelableExtra(String)}. 4418 */ 4419 public static final String EXTRA_NETWORK_REQUEST = "android.net.extra.NETWORK_REQUEST"; 4420 4421 4422 /** 4423 * Request a network to satisfy a set of {@link NetworkCapabilities}. 4424 * 4425 * This function behaves identically to the version that takes a NetworkCallback, but instead 4426 * of {@link NetworkCallback} a {@link PendingIntent} is used. This means 4427 * the request may outlive the calling application and get called back when a suitable 4428 * network is found. 4429 * <p> 4430 * The operation is an Intent broadcast that goes to a broadcast receiver that 4431 * you registered with {@link Context#registerReceiver} or through the 4432 * <receiver> tag in an AndroidManifest.xml file 4433 * <p> 4434 * The operation Intent is delivered with two extras, a {@link Network} typed 4435 * extra called {@link #EXTRA_NETWORK} and a {@link NetworkRequest} 4436 * typed extra called {@link #EXTRA_NETWORK_REQUEST} containing 4437 * the original requests parameters. It is important to create a new, 4438 * {@link NetworkCallback} based request before completing the processing of the 4439 * Intent to reserve the network or it will be released shortly after the Intent 4440 * is processed. 4441 * <p> 4442 * If there is already a request for this Intent registered (with the equality of 4443 * two Intents defined by {@link Intent#filterEquals}), then it will be removed and 4444 * replaced by this one, effectively releasing the previous {@link NetworkRequest}. 4445 * <p> 4446 * The request may be released normally by calling 4447 * {@link #releaseNetworkRequest(android.app.PendingIntent)}. 4448 * <p>It is presently unsupported to request a network with either 4449 * {@link NetworkCapabilities#NET_CAPABILITY_VALIDATED} or 4450 * {@link NetworkCapabilities#NET_CAPABILITY_CAPTIVE_PORTAL} 4451 * as these {@code NetworkCapabilities} represent states that a particular 4452 * network may never attain, and whether a network will attain these states 4453 * is unknown prior to bringing up the network so the framework does not 4454 * know how to go about satisfying a request with these capabilities. 4455 * 4456 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4457 * number of outstanding requests to 100 per app (identified by their UID), shared with 4458 * all variants of this method, of {@link #registerNetworkCallback} as well as 4459 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4460 * Requesting a network with this method will count toward this limit. If this limit is 4461 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4462 * make sure to unregister the callbacks with {@link #unregisterNetworkCallback(PendingIntent)} 4463 * or {@link #releaseNetworkRequest(PendingIntent)}. 4464 * 4465 * <p>This method requires the caller to hold either the 4466 * {@link android.Manifest.permission#CHANGE_NETWORK_STATE} permission 4467 * or the ability to modify system settings as determined by 4468 * {@link android.provider.Settings.System#canWrite}.</p> 4469 * 4470 * @param request {@link NetworkRequest} describing this request. 4471 * @param operation Action to perform when the network is available (corresponds 4472 * to the {@link NetworkCallback#onAvailable} call. Typically 4473 * comes from {@link PendingIntent#getBroadcast}. Cannot be null. 4474 * @throws IllegalArgumentException if {@code request} contains invalid network capabilities. 4475 * @throws SecurityException if missing the appropriate permissions. 4476 * @throws RuntimeException if the app already has too many callbacks registered. 4477 */ requestNetwork(@onNull NetworkRequest request, @NonNull PendingIntent operation)4478 public void requestNetwork(@NonNull NetworkRequest request, 4479 @NonNull PendingIntent operation) { 4480 printStackTrace(); 4481 checkPendingIntentNotNull(operation); 4482 try { 4483 mService.pendingRequestForNetwork( 4484 request.networkCapabilities, operation, mContext.getOpPackageName(), 4485 getAttributionTag()); 4486 } catch (RemoteException e) { 4487 throw e.rethrowFromSystemServer(); 4488 } catch (ServiceSpecificException e) { 4489 throw convertServiceException(e); 4490 } 4491 } 4492 4493 /** 4494 * Removes a request made via {@link #requestNetwork(NetworkRequest, android.app.PendingIntent)} 4495 * <p> 4496 * This method has the same behavior as 4497 * {@link #unregisterNetworkCallback(android.app.PendingIntent)} with respect to 4498 * releasing network resources and disconnecting. 4499 * 4500 * @param operation A PendingIntent equal (as defined by {@link Intent#filterEquals}) to the 4501 * PendingIntent passed to 4502 * {@link #requestNetwork(NetworkRequest, android.app.PendingIntent)} with the 4503 * corresponding NetworkRequest you'd like to remove. Cannot be null. 4504 */ releaseNetworkRequest(@onNull PendingIntent operation)4505 public void releaseNetworkRequest(@NonNull PendingIntent operation) { 4506 printStackTrace(); 4507 checkPendingIntentNotNull(operation); 4508 try { 4509 mService.releasePendingNetworkRequest(operation); 4510 } catch (RemoteException e) { 4511 throw e.rethrowFromSystemServer(); 4512 } 4513 } 4514 checkPendingIntentNotNull(PendingIntent intent)4515 private static void checkPendingIntentNotNull(PendingIntent intent) { 4516 Objects.requireNonNull(intent, "PendingIntent cannot be null."); 4517 } 4518 checkCallbackNotNull(NetworkCallback callback)4519 private static void checkCallbackNotNull(NetworkCallback callback) { 4520 Objects.requireNonNull(callback, "null NetworkCallback"); 4521 } 4522 checkTimeout(int timeoutMs)4523 private static void checkTimeout(int timeoutMs) { 4524 if (timeoutMs <= 0) { 4525 throw new IllegalArgumentException("timeoutMs must be strictly positive."); 4526 } 4527 } 4528 4529 /** 4530 * Registers to receive notifications about all networks which satisfy the given 4531 * {@link NetworkRequest}. The callbacks will continue to be called until 4532 * either the application exits or {@link #unregisterNetworkCallback(NetworkCallback)} is 4533 * called. 4534 * 4535 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4536 * number of outstanding requests to 100 per app (identified by their UID), shared with 4537 * all variants of this method, of {@link #requestNetwork} as well as 4538 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4539 * Requesting a network with this method will count toward this limit. If this limit is 4540 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4541 * make sure to unregister the callbacks with 4542 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4543 * 4544 * @param request {@link NetworkRequest} describing this request. 4545 * @param networkCallback The {@link NetworkCallback} that the system will call as suitable 4546 * networks change state. 4547 * The callback is invoked on the default internal Handler. 4548 * @throws RuntimeException if the app already has too many callbacks registered. 4549 */ 4550 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) registerNetworkCallback(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback)4551 public void registerNetworkCallback(@NonNull NetworkRequest request, 4552 @NonNull NetworkCallback networkCallback) { 4553 registerNetworkCallback(request, networkCallback, getDefaultHandler()); 4554 } 4555 4556 /** 4557 * Registers to receive notifications about all networks which satisfy the given 4558 * {@link NetworkRequest}. The callbacks will continue to be called until 4559 * either the application exits or {@link #unregisterNetworkCallback(NetworkCallback)} is 4560 * called. 4561 * 4562 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4563 * number of outstanding requests to 100 per app (identified by their UID), shared with 4564 * all variants of this method, of {@link #requestNetwork} as well as 4565 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4566 * Requesting a network with this method will count toward this limit. If this limit is 4567 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4568 * make sure to unregister the callbacks with 4569 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4570 * 4571 * 4572 * @param request {@link NetworkRequest} describing this request. 4573 * @param networkCallback The {@link NetworkCallback} that the system will call as suitable 4574 * networks change state. 4575 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4576 * @throws RuntimeException if the app already has too many callbacks registered. 4577 */ 4578 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) registerNetworkCallback(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback, @NonNull Handler handler)4579 public void registerNetworkCallback(@NonNull NetworkRequest request, 4580 @NonNull NetworkCallback networkCallback, @NonNull Handler handler) { 4581 CallbackHandler cbHandler = new CallbackHandler(handler); 4582 NetworkCapabilities nc = request.networkCapabilities; 4583 sendRequestForNetwork(nc, networkCallback, 0, LISTEN, TYPE_NONE, cbHandler); 4584 } 4585 4586 /** 4587 * Registers a PendingIntent to be sent when a network is available which satisfies the given 4588 * {@link NetworkRequest}. 4589 * 4590 * This function behaves identically to the version that takes a NetworkCallback, but instead 4591 * of {@link NetworkCallback} a {@link PendingIntent} is used. This means 4592 * the request may outlive the calling application and get called back when a suitable 4593 * network is found. 4594 * <p> 4595 * The operation is an Intent broadcast that goes to a broadcast receiver that 4596 * you registered with {@link Context#registerReceiver} or through the 4597 * <receiver> tag in an AndroidManifest.xml file 4598 * <p> 4599 * The operation Intent is delivered with two extras, a {@link Network} typed 4600 * extra called {@link #EXTRA_NETWORK} and a {@link NetworkRequest} 4601 * typed extra called {@link #EXTRA_NETWORK_REQUEST} containing 4602 * the original requests parameters. 4603 * <p> 4604 * If there is already a request for this Intent registered (with the equality of 4605 * two Intents defined by {@link Intent#filterEquals}), then it will be removed and 4606 * replaced by this one, effectively releasing the previous {@link NetworkRequest}. 4607 * <p> 4608 * The request may be released normally by calling 4609 * {@link #unregisterNetworkCallback(android.app.PendingIntent)}. 4610 * 4611 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4612 * number of outstanding requests to 100 per app (identified by their UID), shared with 4613 * all variants of this method, of {@link #requestNetwork} as well as 4614 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4615 * Requesting a network with this method will count toward this limit. If this limit is 4616 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4617 * make sure to unregister the callbacks with {@link #unregisterNetworkCallback(PendingIntent)} 4618 * or {@link #releaseNetworkRequest(PendingIntent)}. 4619 * 4620 * @param request {@link NetworkRequest} describing this request. 4621 * @param operation Action to perform when the network is available (corresponds 4622 * to the {@link NetworkCallback#onAvailable} call. Typically 4623 * comes from {@link PendingIntent#getBroadcast}. Cannot be null. 4624 * @throws RuntimeException if the app already has too many callbacks registered. 4625 */ 4626 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) registerNetworkCallback(@onNull NetworkRequest request, @NonNull PendingIntent operation)4627 public void registerNetworkCallback(@NonNull NetworkRequest request, 4628 @NonNull PendingIntent operation) { 4629 printStackTrace(); 4630 checkPendingIntentNotNull(operation); 4631 try { 4632 mService.pendingListenForNetwork( 4633 request.networkCapabilities, operation, mContext.getOpPackageName(), 4634 getAttributionTag()); 4635 } catch (RemoteException e) { 4636 throw e.rethrowFromSystemServer(); 4637 } catch (ServiceSpecificException e) { 4638 throw convertServiceException(e); 4639 } 4640 } 4641 4642 /** 4643 * Registers to receive notifications about changes in the application's default network. This 4644 * may be a physical network or a virtual network, such as a VPN that applies to the 4645 * application. The callbacks will continue to be called until either the application exits or 4646 * {@link #unregisterNetworkCallback(NetworkCallback)} is called. 4647 * 4648 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4649 * number of outstanding requests to 100 per app (identified by their UID), shared with 4650 * all variants of this method, of {@link #requestNetwork} as well as 4651 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4652 * Requesting a network with this method will count toward this limit. If this limit is 4653 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4654 * make sure to unregister the callbacks with 4655 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4656 * 4657 * @param networkCallback The {@link NetworkCallback} that the system will call as the 4658 * application's default network changes. 4659 * The callback is invoked on the default internal Handler. 4660 * @throws RuntimeException if the app already has too many callbacks registered. 4661 */ 4662 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) registerDefaultNetworkCallback(@onNull NetworkCallback networkCallback)4663 public void registerDefaultNetworkCallback(@NonNull NetworkCallback networkCallback) { 4664 registerDefaultNetworkCallback(networkCallback, getDefaultHandler()); 4665 } 4666 4667 /** 4668 * Registers to receive notifications about changes in the application's default network. This 4669 * may be a physical network or a virtual network, such as a VPN that applies to the 4670 * application. The callbacks will continue to be called until either the application exits or 4671 * {@link #unregisterNetworkCallback(NetworkCallback)} is called. 4672 * 4673 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4674 * number of outstanding requests to 100 per app (identified by their UID), shared with 4675 * all variants of this method, of {@link #requestNetwork} as well as 4676 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4677 * Requesting a network with this method will count toward this limit. If this limit is 4678 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4679 * make sure to unregister the callbacks with 4680 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4681 * 4682 * @param networkCallback The {@link NetworkCallback} that the system will call as the 4683 * application's default network changes. 4684 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4685 * @throws RuntimeException if the app already has too many callbacks registered. 4686 */ 4687 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) registerDefaultNetworkCallback(@onNull NetworkCallback networkCallback, @NonNull Handler handler)4688 public void registerDefaultNetworkCallback(@NonNull NetworkCallback networkCallback, 4689 @NonNull Handler handler) { 4690 registerDefaultNetworkCallbackForUid(Process.INVALID_UID, networkCallback, handler); 4691 } 4692 4693 /** 4694 * Registers to receive notifications about changes in the default network for the specified 4695 * UID. This may be a physical network or a virtual network, such as a VPN that applies to the 4696 * UID. The callbacks will continue to be called until either the application exits or 4697 * {@link #unregisterNetworkCallback(NetworkCallback)} is called. 4698 * 4699 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4700 * number of outstanding requests to 100 per app (identified by their UID), shared with 4701 * all variants of this method, of {@link #requestNetwork} as well as 4702 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4703 * Requesting a network with this method will count toward this limit. If this limit is 4704 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4705 * make sure to unregister the callbacks with 4706 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4707 * 4708 * @param uid the UID for which to track default network changes. 4709 * @param networkCallback The {@link NetworkCallback} that the system will call as the 4710 * UID's default network changes. 4711 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4712 * @throws RuntimeException if the app already has too many callbacks registered. 4713 * @hide 4714 */ 4715 @SystemApi(client = MODULE_LIBRARIES) 4716 @SuppressLint({"ExecutorRegistration", "PairedRegistration"}) 4717 @RequiresPermission(anyOf = { 4718 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 4719 android.Manifest.permission.NETWORK_SETTINGS}) registerDefaultNetworkCallbackForUid(int uid, @NonNull NetworkCallback networkCallback, @NonNull Handler handler)4720 public void registerDefaultNetworkCallbackForUid(int uid, 4721 @NonNull NetworkCallback networkCallback, @NonNull Handler handler) { 4722 CallbackHandler cbHandler = new CallbackHandler(handler); 4723 sendRequestForNetwork(uid, null /* need */, networkCallback, 0 /* timeoutMs */, 4724 TRACK_DEFAULT, TYPE_NONE, cbHandler); 4725 } 4726 4727 /** 4728 * Registers to receive notifications about changes in the system default network. The callbacks 4729 * will continue to be called until either the application exits or 4730 * {@link #unregisterNetworkCallback(NetworkCallback)} is called. 4731 * 4732 * This method should not be used to determine networking state seen by applications, because in 4733 * many cases, most or even all application traffic may not use the default network directly, 4734 * and traffic from different applications may go on different networks by default. As an 4735 * example, if a VPN is connected, traffic from all applications might be sent through the VPN 4736 * and not onto the system default network. Applications or system components desiring to do 4737 * determine network state as seen by applications should use other methods such as 4738 * {@link #registerDefaultNetworkCallback(NetworkCallback, Handler)}. 4739 * 4740 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4741 * number of outstanding requests to 100 per app (identified by their UID), shared with 4742 * all variants of this method, of {@link #requestNetwork} as well as 4743 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4744 * Requesting a network with this method will count toward this limit. If this limit is 4745 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4746 * make sure to unregister the callbacks with 4747 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4748 * 4749 * @param networkCallback The {@link NetworkCallback} that the system will call as the 4750 * system default network changes. 4751 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4752 * @throws RuntimeException if the app already has too many callbacks registered. 4753 * 4754 * @hide 4755 */ 4756 @SystemApi(client = MODULE_LIBRARIES) 4757 @SuppressLint({"ExecutorRegistration", "PairedRegistration"}) 4758 @RequiresPermission(anyOf = { 4759 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 4760 android.Manifest.permission.NETWORK_SETTINGS}) registerSystemDefaultNetworkCallback(@onNull NetworkCallback networkCallback, @NonNull Handler handler)4761 public void registerSystemDefaultNetworkCallback(@NonNull NetworkCallback networkCallback, 4762 @NonNull Handler handler) { 4763 CallbackHandler cbHandler = new CallbackHandler(handler); 4764 sendRequestForNetwork(null /* NetworkCapabilities need */, networkCallback, 0, 4765 TRACK_SYSTEM_DEFAULT, TYPE_NONE, cbHandler); 4766 } 4767 4768 /** 4769 * Registers to receive notifications about the best matching network which satisfy the given 4770 * {@link NetworkRequest}. The callbacks will continue to be called until 4771 * either the application exits or {@link #unregisterNetworkCallback(NetworkCallback)} is 4772 * called. 4773 * 4774 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 4775 * number of outstanding requests to 100 per app (identified by their UID), shared with 4776 * {@link #registerNetworkCallback} and its variants and {@link #requestNetwork} as well as 4777 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 4778 * Requesting a network with this method will count toward this limit. If this limit is 4779 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 4780 * make sure to unregister the callbacks with 4781 * {@link #unregisterNetworkCallback(NetworkCallback)}. 4782 * 4783 * 4784 * @param request {@link NetworkRequest} describing this request. 4785 * @param networkCallback The {@link NetworkCallback} that the system will call as suitable 4786 * networks change state. 4787 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 4788 * @throws RuntimeException if the app already has too many callbacks registered. 4789 */ 4790 @SuppressLint("ExecutorRegistration") registerBestMatchingNetworkCallback(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback, @NonNull Handler handler)4791 public void registerBestMatchingNetworkCallback(@NonNull NetworkRequest request, 4792 @NonNull NetworkCallback networkCallback, @NonNull Handler handler) { 4793 final NetworkCapabilities nc = request.networkCapabilities; 4794 final CallbackHandler cbHandler = new CallbackHandler(handler); 4795 sendRequestForNetwork(nc, networkCallback, 0, LISTEN_FOR_BEST, TYPE_NONE, cbHandler); 4796 } 4797 4798 /** 4799 * Requests bandwidth update for a given {@link Network} and returns whether the update request 4800 * is accepted by ConnectivityService. Once accepted, ConnectivityService will poll underlying 4801 * network connection for updated bandwidth information. The caller will be notified via 4802 * {@link ConnectivityManager.NetworkCallback} if there is an update. Notice that this 4803 * method assumes that the caller has previously called 4804 * {@link #registerNetworkCallback(NetworkRequest, NetworkCallback)} to listen for network 4805 * changes. 4806 * 4807 * @param network {@link Network} specifying which network you're interested. 4808 * @return {@code true} on success, {@code false} if the {@link Network} is no longer valid. 4809 */ requestBandwidthUpdate(@onNull Network network)4810 public boolean requestBandwidthUpdate(@NonNull Network network) { 4811 try { 4812 return mService.requestBandwidthUpdate(network); 4813 } catch (RemoteException e) { 4814 throw e.rethrowFromSystemServer(); 4815 } 4816 } 4817 4818 /** 4819 * Unregisters a {@code NetworkCallback} and possibly releases networks originating from 4820 * {@link #requestNetwork(NetworkRequest, NetworkCallback)} and 4821 * {@link #registerNetworkCallback(NetworkRequest, NetworkCallback)} calls. 4822 * If the given {@code NetworkCallback} had previously been used with 4823 * {@code #requestNetwork}, any networks that had been connected to only to satisfy that request 4824 * will be disconnected. 4825 * 4826 * Notifications that would have triggered that {@code NetworkCallback} will immediately stop 4827 * triggering it as soon as this call returns. 4828 * 4829 * @param networkCallback The {@link NetworkCallback} used when making the request. 4830 */ unregisterNetworkCallback(@onNull NetworkCallback networkCallback)4831 public void unregisterNetworkCallback(@NonNull NetworkCallback networkCallback) { 4832 printStackTrace(); 4833 checkCallbackNotNull(networkCallback); 4834 final List<NetworkRequest> reqs = new ArrayList<>(); 4835 // Find all requests associated to this callback and stop callback triggers immediately. 4836 // Callback is reusable immediately. http://b/20701525, http://b/35921499. 4837 synchronized (sCallbacks) { 4838 if (networkCallback.networkRequest == null) { 4839 throw new IllegalArgumentException("NetworkCallback was not registered"); 4840 } 4841 if (networkCallback.networkRequest == ALREADY_UNREGISTERED) { 4842 Log.d(TAG, "NetworkCallback was already unregistered"); 4843 return; 4844 } 4845 for (Map.Entry<NetworkRequest, NetworkCallback> e : sCallbacks.entrySet()) { 4846 if (e.getValue() == networkCallback) { 4847 reqs.add(e.getKey()); 4848 } 4849 } 4850 // TODO: throw exception if callback was registered more than once (http://b/20701525). 4851 for (NetworkRequest r : reqs) { 4852 try { 4853 mService.releaseNetworkRequest(r); 4854 } catch (RemoteException e) { 4855 throw e.rethrowFromSystemServer(); 4856 } 4857 // Only remove mapping if rpc was successful. 4858 sCallbacks.remove(r); 4859 } 4860 networkCallback.networkRequest = ALREADY_UNREGISTERED; 4861 } 4862 } 4863 4864 /** 4865 * Unregisters a callback previously registered via 4866 * {@link #registerNetworkCallback(NetworkRequest, android.app.PendingIntent)}. 4867 * 4868 * @param operation A PendingIntent equal (as defined by {@link Intent#filterEquals}) to the 4869 * PendingIntent passed to 4870 * {@link #registerNetworkCallback(NetworkRequest, android.app.PendingIntent)}. 4871 * Cannot be null. 4872 */ unregisterNetworkCallback(@onNull PendingIntent operation)4873 public void unregisterNetworkCallback(@NonNull PendingIntent operation) { 4874 releaseNetworkRequest(operation); 4875 } 4876 4877 /** 4878 * Informs the system whether it should switch to {@code network} regardless of whether it is 4879 * validated or not. If {@code accept} is true, and the network was explicitly selected by the 4880 * user (e.g., by selecting a Wi-Fi network in the Settings app), then the network will become 4881 * the system default network regardless of any other network that's currently connected. If 4882 * {@code always} is true, then the choice is remembered, so that the next time the user 4883 * connects to this network, the system will switch to it. 4884 * 4885 * @param network The network to accept. 4886 * @param accept Whether to accept the network even if unvalidated. 4887 * @param always Whether to remember this choice in the future. 4888 * 4889 * @hide 4890 */ 4891 @SystemApi(client = MODULE_LIBRARIES) 4892 @RequiresPermission(anyOf = { 4893 android.Manifest.permission.NETWORK_SETTINGS, 4894 android.Manifest.permission.NETWORK_SETUP_WIZARD, 4895 android.Manifest.permission.NETWORK_STACK, 4896 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK}) setAcceptUnvalidated(@onNull Network network, boolean accept, boolean always)4897 public void setAcceptUnvalidated(@NonNull Network network, boolean accept, boolean always) { 4898 try { 4899 mService.setAcceptUnvalidated(network, accept, always); 4900 } catch (RemoteException e) { 4901 throw e.rethrowFromSystemServer(); 4902 } 4903 } 4904 4905 /** 4906 * Informs the system whether it should consider the network as validated even if it only has 4907 * partial connectivity. If {@code accept} is true, then the network will be considered as 4908 * validated even if connectivity is only partial. If {@code always} is true, then the choice 4909 * is remembered, so that the next time the user connects to this network, the system will 4910 * switch to it. 4911 * 4912 * @param network The network to accept. 4913 * @param accept Whether to consider the network as validated even if it has partial 4914 * connectivity. 4915 * @param always Whether to remember this choice in the future. 4916 * 4917 * @hide 4918 */ 4919 @SystemApi(client = MODULE_LIBRARIES) 4920 @RequiresPermission(anyOf = { 4921 android.Manifest.permission.NETWORK_SETTINGS, 4922 android.Manifest.permission.NETWORK_SETUP_WIZARD, 4923 android.Manifest.permission.NETWORK_STACK, 4924 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK}) setAcceptPartialConnectivity(@onNull Network network, boolean accept, boolean always)4925 public void setAcceptPartialConnectivity(@NonNull Network network, boolean accept, 4926 boolean always) { 4927 try { 4928 mService.setAcceptPartialConnectivity(network, accept, always); 4929 } catch (RemoteException e) { 4930 throw e.rethrowFromSystemServer(); 4931 } 4932 } 4933 4934 /** 4935 * Informs the system to penalize {@code network}'s score when it becomes unvalidated. This is 4936 * only meaningful if the system is configured not to penalize such networks, e.g., if the 4937 * {@code config_networkAvoidBadWifi} configuration variable is set to 0 and the {@code 4938 * NETWORK_AVOID_BAD_WIFI setting is unset}. 4939 * 4940 * @param network The network to accept. 4941 * 4942 * @hide 4943 */ 4944 @SystemApi(client = MODULE_LIBRARIES) 4945 @RequiresPermission(anyOf = { 4946 android.Manifest.permission.NETWORK_SETTINGS, 4947 android.Manifest.permission.NETWORK_SETUP_WIZARD, 4948 android.Manifest.permission.NETWORK_STACK, 4949 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK}) setAvoidUnvalidated(@onNull Network network)4950 public void setAvoidUnvalidated(@NonNull Network network) { 4951 try { 4952 mService.setAvoidUnvalidated(network); 4953 } catch (RemoteException e) { 4954 throw e.rethrowFromSystemServer(); 4955 } 4956 } 4957 4958 /** 4959 * Temporarily allow bad wifi to override {@code config_networkAvoidBadWifi} configuration. 4960 * 4961 * @param timeMs The expired current time. The value should be set within a limited time from 4962 * now. 4963 * 4964 * @hide 4965 */ setTestAllowBadWifiUntil(long timeMs)4966 public void setTestAllowBadWifiUntil(long timeMs) { 4967 try { 4968 mService.setTestAllowBadWifiUntil(timeMs); 4969 } catch (RemoteException e) { 4970 throw e.rethrowFromSystemServer(); 4971 } 4972 } 4973 4974 /** 4975 * Requests that the system open the captive portal app on the specified network. 4976 * 4977 * <p>This is to be used on networks where a captive portal was detected, as per 4978 * {@link NetworkCapabilities#NET_CAPABILITY_CAPTIVE_PORTAL}. 4979 * 4980 * @param network The network to log into. 4981 * 4982 * @hide 4983 */ 4984 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 4985 @RequiresPermission(anyOf = { 4986 android.Manifest.permission.NETWORK_SETTINGS, 4987 android.Manifest.permission.NETWORK_STACK, 4988 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 4989 }) startCaptivePortalApp(@onNull Network network)4990 public void startCaptivePortalApp(@NonNull Network network) { 4991 try { 4992 mService.startCaptivePortalApp(network); 4993 } catch (RemoteException e) { 4994 throw e.rethrowFromSystemServer(); 4995 } 4996 } 4997 4998 /** 4999 * Requests that the system open the captive portal app with the specified extras. 5000 * 5001 * <p>This endpoint is exclusively for use by the NetworkStack and is protected by the 5002 * corresponding permission. 5003 * @param network Network on which the captive portal was detected. 5004 * @param appExtras Extras to include in the app start intent. 5005 * @hide 5006 */ 5007 @SystemApi 5008 @RequiresPermission(NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK) startCaptivePortalApp(@onNull Network network, @NonNull Bundle appExtras)5009 public void startCaptivePortalApp(@NonNull Network network, @NonNull Bundle appExtras) { 5010 try { 5011 mService.startCaptivePortalAppInternal(network, appExtras); 5012 } catch (RemoteException e) { 5013 throw e.rethrowFromSystemServer(); 5014 } 5015 } 5016 5017 /** 5018 * Determine whether the device is configured to avoid bad wifi. 5019 * @hide 5020 */ 5021 @SystemApi 5022 @RequiresPermission(anyOf = { 5023 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK, 5024 android.Manifest.permission.NETWORK_STACK}) shouldAvoidBadWifi()5025 public boolean shouldAvoidBadWifi() { 5026 try { 5027 return mService.shouldAvoidBadWifi(); 5028 } catch (RemoteException e) { 5029 throw e.rethrowFromSystemServer(); 5030 } 5031 } 5032 5033 /** 5034 * It is acceptable to briefly use multipath data to provide seamless connectivity for 5035 * time-sensitive user-facing operations when the system default network is temporarily 5036 * unresponsive. The amount of data should be limited (less than one megabyte for every call to 5037 * this method), and the operation should be infrequent to ensure that data usage is limited. 5038 * 5039 * An example of such an operation might be a time-sensitive foreground activity, such as a 5040 * voice command, that the user is performing while walking out of range of a Wi-Fi network. 5041 */ 5042 public static final int MULTIPATH_PREFERENCE_HANDOVER = 1 << 0; 5043 5044 /** 5045 * It is acceptable to use small amounts of multipath data on an ongoing basis to provide 5046 * a backup channel for traffic that is primarily going over another network. 5047 * 5048 * An example might be maintaining backup connections to peers or servers for the purpose of 5049 * fast fallback if the default network is temporarily unresponsive or disconnects. The traffic 5050 * on backup paths should be negligible compared to the traffic on the main path. 5051 */ 5052 public static final int MULTIPATH_PREFERENCE_RELIABILITY = 1 << 1; 5053 5054 /** 5055 * It is acceptable to use metered data to improve network latency and performance. 5056 */ 5057 public static final int MULTIPATH_PREFERENCE_PERFORMANCE = 1 << 2; 5058 5059 /** 5060 * Return value to use for unmetered networks. On such networks we currently set all the flags 5061 * to true. 5062 * @hide 5063 */ 5064 public static final int MULTIPATH_PREFERENCE_UNMETERED = 5065 MULTIPATH_PREFERENCE_HANDOVER | 5066 MULTIPATH_PREFERENCE_RELIABILITY | 5067 MULTIPATH_PREFERENCE_PERFORMANCE; 5068 5069 /** @hide */ 5070 @Retention(RetentionPolicy.SOURCE) 5071 @IntDef(flag = true, value = { 5072 MULTIPATH_PREFERENCE_HANDOVER, 5073 MULTIPATH_PREFERENCE_RELIABILITY, 5074 MULTIPATH_PREFERENCE_PERFORMANCE, 5075 }) 5076 public @interface MultipathPreference { 5077 } 5078 5079 /** 5080 * Provides a hint to the calling application on whether it is desirable to use the 5081 * multinetwork APIs (e.g., {@link Network#openConnection}, {@link Network#bindSocket}, etc.) 5082 * for multipath data transfer on this network when it is not the system default network. 5083 * Applications desiring to use multipath network protocols should call this method before 5084 * each such operation. 5085 * 5086 * @param network The network on which the application desires to use multipath data. 5087 * If {@code null}, this method will return the a preference that will generally 5088 * apply to metered networks. 5089 * @return a bitwise OR of zero or more of the {@code MULTIPATH_PREFERENCE_*} constants. 5090 */ 5091 @RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE) getMultipathPreference(@ullable Network network)5092 public @MultipathPreference int getMultipathPreference(@Nullable Network network) { 5093 try { 5094 return mService.getMultipathPreference(network); 5095 } catch (RemoteException e) { 5096 throw e.rethrowFromSystemServer(); 5097 } 5098 } 5099 5100 /** 5101 * Resets all connectivity manager settings back to factory defaults. 5102 * @hide 5103 */ 5104 @SystemApi(client = MODULE_LIBRARIES) 5105 @RequiresPermission(anyOf = { 5106 android.Manifest.permission.NETWORK_SETTINGS, 5107 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK}) factoryReset()5108 public void factoryReset() { 5109 try { 5110 mService.factoryReset(); 5111 getTetheringManager().stopAllTethering(); 5112 } catch (RemoteException e) { 5113 throw e.rethrowFromSystemServer(); 5114 } 5115 } 5116 5117 /** 5118 * Binds the current process to {@code network}. All Sockets created in the future 5119 * (and not explicitly bound via a bound SocketFactory from 5120 * {@link Network#getSocketFactory() Network.getSocketFactory()}) will be bound to 5121 * {@code network}. All host name resolutions will be limited to {@code network} as well. 5122 * Note that if {@code network} ever disconnects, all Sockets created in this way will cease to 5123 * work and all host name resolutions will fail. This is by design so an application doesn't 5124 * accidentally use Sockets it thinks are still bound to a particular {@link Network}. 5125 * To clear binding pass {@code null} for {@code network}. Using individually bound 5126 * Sockets created by Network.getSocketFactory().createSocket() and 5127 * performing network-specific host name resolutions via 5128 * {@link Network#getAllByName Network.getAllByName} is preferred to calling 5129 * {@code bindProcessToNetwork}. 5130 * 5131 * @param network The {@link Network} to bind the current process to, or {@code null} to clear 5132 * the current binding. 5133 * @return {@code true} on success, {@code false} if the {@link Network} is no longer valid. 5134 */ bindProcessToNetwork(@ullable Network network)5135 public boolean bindProcessToNetwork(@Nullable Network network) { 5136 // Forcing callers to call through non-static function ensures ConnectivityManager 5137 // instantiated. 5138 return setProcessDefaultNetwork(network); 5139 } 5140 5141 /** 5142 * Binds the current process to {@code network}. All Sockets created in the future 5143 * (and not explicitly bound via a bound SocketFactory from 5144 * {@link Network#getSocketFactory() Network.getSocketFactory()}) will be bound to 5145 * {@code network}. All host name resolutions will be limited to {@code network} as well. 5146 * Note that if {@code network} ever disconnects, all Sockets created in this way will cease to 5147 * work and all host name resolutions will fail. This is by design so an application doesn't 5148 * accidentally use Sockets it thinks are still bound to a particular {@link Network}. 5149 * To clear binding pass {@code null} for {@code network}. Using individually bound 5150 * Sockets created by Network.getSocketFactory().createSocket() and 5151 * performing network-specific host name resolutions via 5152 * {@link Network#getAllByName Network.getAllByName} is preferred to calling 5153 * {@code setProcessDefaultNetwork}. 5154 * 5155 * @param network The {@link Network} to bind the current process to, or {@code null} to clear 5156 * the current binding. 5157 * @return {@code true} on success, {@code false} if the {@link Network} is no longer valid. 5158 * @deprecated This function can throw {@link IllegalStateException}. Use 5159 * {@link #bindProcessToNetwork} instead. {@code bindProcessToNetwork} 5160 * is a direct replacement. 5161 */ 5162 @Deprecated setProcessDefaultNetwork(@ullable Network network)5163 public static boolean setProcessDefaultNetwork(@Nullable Network network) { 5164 int netId = (network == null) ? NETID_UNSET : network.netId; 5165 boolean isSameNetId = (netId == NetworkUtils.getBoundNetworkForProcess()); 5166 5167 if (netId != NETID_UNSET) { 5168 netId = network.getNetIdForResolv(); 5169 } 5170 5171 if (!NetworkUtils.bindProcessToNetwork(netId)) { 5172 return false; 5173 } 5174 5175 if (!isSameNetId) { 5176 // Set HTTP proxy system properties to match network. 5177 // TODO: Deprecate this static method and replace it with a non-static version. 5178 try { 5179 Proxy.setHttpProxyConfiguration(getInstance().getDefaultProxy()); 5180 } catch (SecurityException e) { 5181 // The process doesn't have ACCESS_NETWORK_STATE, so we can't fetch the proxy. 5182 Log.e(TAG, "Can't set proxy properties", e); 5183 } 5184 // Must flush DNS cache as new network may have different DNS resolutions. 5185 InetAddress.clearDnsCache(); 5186 // Must flush socket pool as idle sockets will be bound to previous network and may 5187 // cause subsequent fetches to be performed on old network. 5188 NetworkEventDispatcher.getInstance().dispatchNetworkConfigurationChange(); 5189 } 5190 5191 return true; 5192 } 5193 5194 /** 5195 * Returns the {@link Network} currently bound to this process via 5196 * {@link #bindProcessToNetwork}, or {@code null} if no {@link Network} is explicitly bound. 5197 * 5198 * @return {@code Network} to which this process is bound, or {@code null}. 5199 */ 5200 @Nullable getBoundNetworkForProcess()5201 public Network getBoundNetworkForProcess() { 5202 // Forcing callers to call thru non-static function ensures ConnectivityManager 5203 // instantiated. 5204 return getProcessDefaultNetwork(); 5205 } 5206 5207 /** 5208 * Returns the {@link Network} currently bound to this process via 5209 * {@link #bindProcessToNetwork}, or {@code null} if no {@link Network} is explicitly bound. 5210 * 5211 * @return {@code Network} to which this process is bound, or {@code null}. 5212 * @deprecated Using this function can lead to other functions throwing 5213 * {@link IllegalStateException}. Use {@link #getBoundNetworkForProcess} instead. 5214 * {@code getBoundNetworkForProcess} is a direct replacement. 5215 */ 5216 @Deprecated 5217 @Nullable getProcessDefaultNetwork()5218 public static Network getProcessDefaultNetwork() { 5219 int netId = NetworkUtils.getBoundNetworkForProcess(); 5220 if (netId == NETID_UNSET) return null; 5221 return new Network(netId); 5222 } 5223 unsupportedStartingFrom(int version)5224 private void unsupportedStartingFrom(int version) { 5225 if (Process.myUid() == Process.SYSTEM_UID) { 5226 // The getApplicationInfo() call we make below is not supported in system context. Let 5227 // the call through here, and rely on the fact that ConnectivityService will refuse to 5228 // allow the system to use these APIs anyway. 5229 return; 5230 } 5231 5232 if (mContext.getApplicationInfo().targetSdkVersion >= version) { 5233 throw new UnsupportedOperationException( 5234 "This method is not supported in target SDK version " + version + " and above"); 5235 } 5236 } 5237 5238 // Checks whether the calling app can use the legacy routing API (startUsingNetworkFeature, 5239 // stopUsingNetworkFeature, requestRouteToHost), and if not throw UnsupportedOperationException. 5240 // TODO: convert the existing system users (Tethering, GnssLocationProvider) to the new APIs and 5241 // remove these exemptions. Note that this check is not secure, and apps can still access these 5242 // functions by accessing ConnectivityService directly. However, it should be clear that doing 5243 // so is unsupported and may break in the future. http://b/22728205 checkLegacyRoutingApiAccess()5244 private void checkLegacyRoutingApiAccess() { 5245 unsupportedStartingFrom(VERSION_CODES.M); 5246 } 5247 5248 /** 5249 * Binds host resolutions performed by this process to {@code network}. 5250 * {@link #bindProcessToNetwork} takes precedence over this setting. 5251 * 5252 * @param network The {@link Network} to bind host resolutions from the current process to, or 5253 * {@code null} to clear the current binding. 5254 * @return {@code true} on success, {@code false} if the {@link Network} is no longer valid. 5255 * @hide 5256 * @deprecated This is strictly for legacy usage to support {@link #startUsingNetworkFeature}. 5257 */ 5258 @Deprecated 5259 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) setProcessDefaultNetworkForHostResolution(Network network)5260 public static boolean setProcessDefaultNetworkForHostResolution(Network network) { 5261 return NetworkUtils.bindProcessToNetworkForHostResolution( 5262 (network == null) ? NETID_UNSET : network.getNetIdForResolv()); 5263 } 5264 5265 /** 5266 * Device is not restricting metered network activity while application is running on 5267 * background. 5268 */ 5269 public static final int RESTRICT_BACKGROUND_STATUS_DISABLED = 1; 5270 5271 /** 5272 * Device is restricting metered network activity while application is running on background, 5273 * but application is allowed to bypass it. 5274 * <p> 5275 * In this state, application should take action to mitigate metered network access. 5276 * For example, a music streaming application should switch to a low-bandwidth bitrate. 5277 */ 5278 public static final int RESTRICT_BACKGROUND_STATUS_WHITELISTED = 2; 5279 5280 /** 5281 * Device is restricting metered network activity while application is running on background. 5282 * <p> 5283 * In this state, application should not try to use the network while running on background, 5284 * because it would be denied. 5285 */ 5286 public static final int RESTRICT_BACKGROUND_STATUS_ENABLED = 3; 5287 5288 /** 5289 * A change in the background metered network activity restriction has occurred. 5290 * <p> 5291 * Applications should call {@link #getRestrictBackgroundStatus()} to check if the restriction 5292 * applies to them. 5293 * <p> 5294 * This is only sent to registered receivers, not manifest receivers. 5295 */ 5296 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 5297 public static final String ACTION_RESTRICT_BACKGROUND_CHANGED = 5298 "android.net.conn.RESTRICT_BACKGROUND_CHANGED"; 5299 5300 /** @hide */ 5301 @Retention(RetentionPolicy.SOURCE) 5302 @IntDef(flag = false, value = { 5303 RESTRICT_BACKGROUND_STATUS_DISABLED, 5304 RESTRICT_BACKGROUND_STATUS_WHITELISTED, 5305 RESTRICT_BACKGROUND_STATUS_ENABLED, 5306 }) 5307 public @interface RestrictBackgroundStatus { 5308 } 5309 5310 /** 5311 * Determines if the calling application is subject to metered network restrictions while 5312 * running on background. 5313 * 5314 * @return {@link #RESTRICT_BACKGROUND_STATUS_DISABLED}, 5315 * {@link #RESTRICT_BACKGROUND_STATUS_ENABLED}, 5316 * or {@link #RESTRICT_BACKGROUND_STATUS_WHITELISTED} 5317 */ getRestrictBackgroundStatus()5318 public @RestrictBackgroundStatus int getRestrictBackgroundStatus() { 5319 try { 5320 return mService.getRestrictBackgroundStatusByCaller(); 5321 } catch (RemoteException e) { 5322 throw e.rethrowFromSystemServer(); 5323 } 5324 } 5325 5326 /** 5327 * The network watchlist is a list of domains and IP addresses that are associated with 5328 * potentially harmful apps. This method returns the SHA-256 of the watchlist config file 5329 * currently used by the system for validation purposes. 5330 * 5331 * @return Hash of network watchlist config file. Null if config does not exist. 5332 */ 5333 @Nullable getNetworkWatchlistConfigHash()5334 public byte[] getNetworkWatchlistConfigHash() { 5335 try { 5336 return mService.getNetworkWatchlistConfigHash(); 5337 } catch (RemoteException e) { 5338 Log.e(TAG, "Unable to get watchlist config hash"); 5339 throw e.rethrowFromSystemServer(); 5340 } 5341 } 5342 5343 /** 5344 * Returns the {@code uid} of the owner of a network connection. 5345 * 5346 * @param protocol The protocol of the connection. Only {@code IPPROTO_TCP} and {@code 5347 * IPPROTO_UDP} currently supported. 5348 * @param local The local {@link InetSocketAddress} of a connection. 5349 * @param remote The remote {@link InetSocketAddress} of a connection. 5350 * @return {@code uid} if the connection is found and the app has permission to observe it 5351 * (e.g., if it is associated with the calling VPN app's VpnService tunnel) or {@link 5352 * android.os.Process#INVALID_UID} if the connection is not found. 5353 * @throws {@link SecurityException} if the caller is not the active VpnService for the current 5354 * user. 5355 * @throws {@link IllegalArgumentException} if an unsupported protocol is requested. 5356 */ getConnectionOwnerUid( int protocol, @NonNull InetSocketAddress local, @NonNull InetSocketAddress remote)5357 public int getConnectionOwnerUid( 5358 int protocol, @NonNull InetSocketAddress local, @NonNull InetSocketAddress remote) { 5359 ConnectionInfo connectionInfo = new ConnectionInfo(protocol, local, remote); 5360 try { 5361 return mService.getConnectionOwnerUid(connectionInfo); 5362 } catch (RemoteException e) { 5363 throw e.rethrowFromSystemServer(); 5364 } 5365 } 5366 printStackTrace()5367 private void printStackTrace() { 5368 if (DEBUG) { 5369 final StackTraceElement[] callStack = Thread.currentThread().getStackTrace(); 5370 final StringBuffer sb = new StringBuffer(); 5371 for (int i = 3; i < callStack.length; i++) { 5372 final String stackTrace = callStack[i].toString(); 5373 if (stackTrace == null || stackTrace.contains("android.os")) { 5374 break; 5375 } 5376 sb.append(" [").append(stackTrace).append("]"); 5377 } 5378 Log.d(TAG, "StackLog:" + sb.toString()); 5379 } 5380 } 5381 5382 /** @hide */ startOrGetTestNetworkManager()5383 public TestNetworkManager startOrGetTestNetworkManager() { 5384 final IBinder tnBinder; 5385 try { 5386 tnBinder = mService.startOrGetTestNetworkService(); 5387 } catch (RemoteException e) { 5388 throw e.rethrowFromSystemServer(); 5389 } 5390 5391 return new TestNetworkManager(ITestNetworkManager.Stub.asInterface(tnBinder)); 5392 } 5393 5394 /** @hide */ createDiagnosticsManager()5395 public ConnectivityDiagnosticsManager createDiagnosticsManager() { 5396 return new ConnectivityDiagnosticsManager(mContext, mService); 5397 } 5398 5399 /** 5400 * Simulates a Data Stall for the specified Network. 5401 * 5402 * <p>This method should only be used for tests. 5403 * 5404 * <p>The caller must be the owner of the specified Network. This simulates a data stall to 5405 * have the system behave as if it had happened, but does not actually stall connectivity. 5406 * 5407 * @param detectionMethod The detection method used to identify the Data Stall. 5408 * See ConnectivityDiagnosticsManager.DataStallReport.DETECTION_METHOD_*. 5409 * @param timestampMillis The timestamp at which the stall 'occurred', in milliseconds, as per 5410 * SystemClock.elapsedRealtime. 5411 * @param network The Network for which a Data Stall is being simluated. 5412 * @param extras The PersistableBundle of extras included in the Data Stall notification. 5413 * @throws SecurityException if the caller is not the owner of the given network. 5414 * @hide 5415 */ 5416 @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES) 5417 @RequiresPermission(anyOf = {android.Manifest.permission.MANAGE_TEST_NETWORKS, 5418 android.Manifest.permission.NETWORK_STACK}) simulateDataStall(@etectionMethod int detectionMethod, long timestampMillis, @NonNull Network network, @NonNull PersistableBundle extras)5419 public void simulateDataStall(@DetectionMethod int detectionMethod, long timestampMillis, 5420 @NonNull Network network, @NonNull PersistableBundle extras) { 5421 try { 5422 mService.simulateDataStall(detectionMethod, timestampMillis, network, extras); 5423 } catch (RemoteException e) { 5424 e.rethrowFromSystemServer(); 5425 } 5426 } 5427 5428 @NonNull 5429 private final List<QosCallbackConnection> mQosCallbackConnections = new ArrayList<>(); 5430 5431 /** 5432 * Registers a {@link QosSocketInfo} with an associated {@link QosCallback}. The callback will 5433 * receive available QoS events related to the {@link Network} and local ip + port 5434 * specified within socketInfo. 5435 * <p/> 5436 * The same {@link QosCallback} must be unregistered before being registered a second time, 5437 * otherwise {@link QosCallbackRegistrationException} is thrown. 5438 * <p/> 5439 * This API does not, in itself, require any permission if called with a network that is not 5440 * restricted. However, the underlying implementation currently only supports the IMS network, 5441 * which is always restricted. That means non-preinstalled callers can't possibly find this API 5442 * useful, because they'd never be called back on networks that they would have access to. 5443 * 5444 * @throws SecurityException if {@link QosSocketInfo#getNetwork()} is restricted and the app is 5445 * missing CONNECTIVITY_USE_RESTRICTED_NETWORKS permission. 5446 * @throws QosCallback.QosCallbackRegistrationException if qosCallback is already registered. 5447 * @throws RuntimeException if the app already has too many callbacks registered. 5448 * 5449 * Exceptions after the time of registration is passed through 5450 * {@link QosCallback#onError(QosCallbackException)}. see: {@link QosCallbackException}. 5451 * 5452 * @param socketInfo the socket information used to match QoS events 5453 * @param executor The executor on which the callback will be invoked. The provided 5454 * {@link Executor} must run callback sequentially, otherwise the order of 5455 * callbacks cannot be guaranteed.onQosCallbackRegistered 5456 * @param callback receives qos events that satisfy socketInfo 5457 * 5458 * @hide 5459 */ 5460 @SystemApi registerQosCallback(@onNull final QosSocketInfo socketInfo, @CallbackExecutor @NonNull final Executor executor, @NonNull final QosCallback callback)5461 public void registerQosCallback(@NonNull final QosSocketInfo socketInfo, 5462 @CallbackExecutor @NonNull final Executor executor, 5463 @NonNull final QosCallback callback) { 5464 Objects.requireNonNull(socketInfo, "socketInfo must be non-null"); 5465 Objects.requireNonNull(executor, "executor must be non-null"); 5466 Objects.requireNonNull(callback, "callback must be non-null"); 5467 5468 try { 5469 synchronized (mQosCallbackConnections) { 5470 if (getQosCallbackConnection(callback) == null) { 5471 final QosCallbackConnection connection = 5472 new QosCallbackConnection(this, callback, executor); 5473 mQosCallbackConnections.add(connection); 5474 mService.registerQosSocketCallback(socketInfo, connection); 5475 } else { 5476 Log.e(TAG, "registerQosCallback: Callback already registered"); 5477 throw new QosCallbackRegistrationException(); 5478 } 5479 } 5480 } catch (final RemoteException e) { 5481 Log.e(TAG, "registerQosCallback: Error while registering ", e); 5482 5483 // The same unregister method method is called for consistency even though nothing 5484 // will be sent to the ConnectivityService since the callback was never successfully 5485 // registered. 5486 unregisterQosCallback(callback); 5487 e.rethrowFromSystemServer(); 5488 } catch (final ServiceSpecificException e) { 5489 Log.e(TAG, "registerQosCallback: Error while registering ", e); 5490 unregisterQosCallback(callback); 5491 throw convertServiceException(e); 5492 } 5493 } 5494 5495 /** 5496 * Unregisters the given {@link QosCallback}. The {@link QosCallback} will no longer receive 5497 * events once unregistered and can be registered a second time. 5498 * <p/> 5499 * If the {@link QosCallback} does not have an active registration, it is a no-op. 5500 * 5501 * @param callback the callback being unregistered 5502 * 5503 * @hide 5504 */ 5505 @SystemApi unregisterQosCallback(@onNull final QosCallback callback)5506 public void unregisterQosCallback(@NonNull final QosCallback callback) { 5507 Objects.requireNonNull(callback, "The callback must be non-null"); 5508 try { 5509 synchronized (mQosCallbackConnections) { 5510 final QosCallbackConnection connection = getQosCallbackConnection(callback); 5511 if (connection != null) { 5512 connection.stopReceivingMessages(); 5513 mService.unregisterQosCallback(connection); 5514 mQosCallbackConnections.remove(connection); 5515 } else { 5516 Log.d(TAG, "unregisterQosCallback: Callback not registered"); 5517 } 5518 } 5519 } catch (final RemoteException e) { 5520 Log.e(TAG, "unregisterQosCallback: Error while unregistering ", e); 5521 e.rethrowFromSystemServer(); 5522 } 5523 } 5524 5525 /** 5526 * Gets the connection related to the callback. 5527 * 5528 * @param callback the callback to look up 5529 * @return the related connection 5530 */ 5531 @Nullable getQosCallbackConnection(final QosCallback callback)5532 private QosCallbackConnection getQosCallbackConnection(final QosCallback callback) { 5533 for (final QosCallbackConnection connection : mQosCallbackConnections) { 5534 // Checking by reference here is intentional 5535 if (connection.getCallback() == callback) { 5536 return connection; 5537 } 5538 } 5539 return null; 5540 } 5541 5542 /** 5543 * Request a network to satisfy a set of {@link NetworkCapabilities}, but 5544 * does not cause any networks to retain the NET_CAPABILITY_FOREGROUND capability. This can 5545 * be used to request that the system provide a network without causing the network to be 5546 * in the foreground. 5547 * 5548 * <p>This method will attempt to find the best network that matches the passed 5549 * {@link NetworkRequest}, and to bring up one that does if none currently satisfies the 5550 * criteria. The platform will evaluate which network is the best at its own discretion. 5551 * Throughput, latency, cost per byte, policy, user preference and other considerations 5552 * may be factored in the decision of what is considered the best network. 5553 * 5554 * <p>As long as this request is outstanding, the platform will try to maintain the best network 5555 * matching this request, while always attempting to match the request to a better network if 5556 * possible. If a better match is found, the platform will switch this request to the now-best 5557 * network and inform the app of the newly best network by invoking 5558 * {@link NetworkCallback#onAvailable(Network)} on the provided callback. Note that the platform 5559 * will not try to maintain any other network than the best one currently matching the request: 5560 * a network not matching any network request may be disconnected at any time. 5561 * 5562 * <p>For example, an application could use this method to obtain a connected cellular network 5563 * even if the device currently has a data connection over Ethernet. This may cause the cellular 5564 * radio to consume additional power. Or, an application could inform the system that it wants 5565 * a network supporting sending MMSes and have the system let it know about the currently best 5566 * MMS-supporting network through the provided {@link NetworkCallback}. 5567 * 5568 * <p>The status of the request can be followed by listening to the various callbacks described 5569 * in {@link NetworkCallback}. The {@link Network} object passed to the callback methods can be 5570 * used to direct traffic to the network (although accessing some networks may be subject to 5571 * holding specific permissions). Callers will learn about the specific characteristics of the 5572 * network through 5573 * {@link NetworkCallback#onCapabilitiesChanged(Network, NetworkCapabilities)} and 5574 * {@link NetworkCallback#onLinkPropertiesChanged(Network, LinkProperties)}. The methods of the 5575 * provided {@link NetworkCallback} will only be invoked due to changes in the best network 5576 * matching the request at any given time; therefore when a better network matching the request 5577 * becomes available, the {@link NetworkCallback#onAvailable(Network)} method is called 5578 * with the new network after which no further updates are given about the previously-best 5579 * network, unless it becomes the best again at some later time. All callbacks are invoked 5580 * in order on the same thread, which by default is a thread created by the framework running 5581 * in the app. 5582 * 5583 * <p>This{@link NetworkRequest} will live until released via 5584 * {@link #unregisterNetworkCallback(NetworkCallback)} or the calling application exits, at 5585 * which point the system may let go of the network at any time. 5586 * 5587 * <p>It is presently unsupported to request a network with mutable 5588 * {@link NetworkCapabilities} such as 5589 * {@link NetworkCapabilities#NET_CAPABILITY_VALIDATED} or 5590 * {@link NetworkCapabilities#NET_CAPABILITY_CAPTIVE_PORTAL} 5591 * as these {@code NetworkCapabilities} represent states that a particular 5592 * network may never attain, and whether a network will attain these states 5593 * is unknown prior to bringing up the network so the framework does not 5594 * know how to go about satisfying a request with these capabilities. 5595 * 5596 * <p>To avoid performance issues due to apps leaking callbacks, the system will limit the 5597 * number of outstanding requests to 100 per app (identified by their UID), shared with 5598 * all variants of this method, of {@link #registerNetworkCallback} as well as 5599 * {@link ConnectivityDiagnosticsManager#registerConnectivityDiagnosticsCallback}. 5600 * Requesting a network with this method will count toward this limit. If this limit is 5601 * exceeded, an exception will be thrown. To avoid hitting this issue and to conserve resources, 5602 * make sure to unregister the callbacks with 5603 * {@link #unregisterNetworkCallback(NetworkCallback)}. 5604 * 5605 * @param request {@link NetworkRequest} describing this request. 5606 * @param networkCallback The {@link NetworkCallback} to be utilized for this request. Note 5607 * the callback must not be shared - it uniquely specifies this request. 5608 * @param handler {@link Handler} to specify the thread upon which the callback will be invoked. 5609 * If null, the callback is invoked on the default internal Handler. 5610 * @throws IllegalArgumentException if {@code request} contains invalid network capabilities. 5611 * @throws SecurityException if missing the appropriate permissions. 5612 * @throws RuntimeException if the app already has too many callbacks registered. 5613 * 5614 * @hide 5615 */ 5616 @SystemApi(client = MODULE_LIBRARIES) 5617 @SuppressLint("ExecutorRegistration") 5618 @RequiresPermission(anyOf = { 5619 android.Manifest.permission.NETWORK_SETTINGS, 5620 android.Manifest.permission.NETWORK_STACK, 5621 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5622 }) requestBackgroundNetwork(@onNull NetworkRequest request, @NonNull NetworkCallback networkCallback, @SuppressLint("ListenerLast") @NonNull Handler handler)5623 public void requestBackgroundNetwork(@NonNull NetworkRequest request, 5624 @NonNull NetworkCallback networkCallback, 5625 @SuppressLint("ListenerLast") @NonNull Handler handler) { 5626 final NetworkCapabilities nc = request.networkCapabilities; 5627 sendRequestForNetwork(nc, networkCallback, 0, BACKGROUND_REQUEST, 5628 TYPE_NONE, new CallbackHandler(handler)); 5629 } 5630 5631 /** 5632 * Used by automotive devices to set the network preferences used to direct traffic at an 5633 * application level as per the given OemNetworkPreferences. An example use-case would be an 5634 * automotive OEM wanting to provide connectivity for applications critical to the usage of a 5635 * vehicle via a particular network. 5636 * 5637 * Calling this will overwrite the existing preference. 5638 * 5639 * @param preference {@link OemNetworkPreferences} The application network preference to be set. 5640 * @param executor the executor on which listener will be invoked. 5641 * @param listener {@link OnSetOemNetworkPreferenceListener} optional listener used to 5642 * communicate completion of setOemNetworkPreference(). This will only be 5643 * called once upon successful completion of setOemNetworkPreference(). 5644 * @throws IllegalArgumentException if {@code preference} contains invalid preference values. 5645 * @throws SecurityException if missing the appropriate permissions. 5646 * @throws UnsupportedOperationException if called on a non-automotive device. 5647 * @hide 5648 */ 5649 @SystemApi 5650 @RequiresPermission(android.Manifest.permission.CONTROL_OEM_PAID_NETWORK_PREFERENCE) setOemNetworkPreference(@onNull final OemNetworkPreferences preference, @Nullable @CallbackExecutor final Executor executor, @Nullable final Runnable listener)5651 public void setOemNetworkPreference(@NonNull final OemNetworkPreferences preference, 5652 @Nullable @CallbackExecutor final Executor executor, 5653 @Nullable final Runnable listener) { 5654 Objects.requireNonNull(preference, "OemNetworkPreferences must be non-null"); 5655 if (null != listener) { 5656 Objects.requireNonNull(executor, "Executor must be non-null"); 5657 } 5658 final IOnCompleteListener listenerInternal = listener == null ? null : 5659 new IOnCompleteListener.Stub() { 5660 @Override 5661 public void onComplete() { 5662 executor.execute(listener::run); 5663 } 5664 }; 5665 5666 try { 5667 mService.setOemNetworkPreference(preference, listenerInternal); 5668 } catch (RemoteException e) { 5669 Log.e(TAG, "setOemNetworkPreference() failed for preference: " + preference.toString()); 5670 throw e.rethrowFromSystemServer(); 5671 } 5672 } 5673 5674 /** 5675 * Request that a user profile is put by default on a network matching a given preference. 5676 * 5677 * See the documentation for the individual preferences for a description of the supported 5678 * behaviors. 5679 * 5680 * @param profile the profile concerned. 5681 * @param preference the preference for this profile. 5682 * @param executor an executor to execute the listener on. Optional if listener is null. 5683 * @param listener an optional listener to listen for completion of the operation. 5684 * @throws IllegalArgumentException if {@code profile} is not a valid user profile. 5685 * @throws SecurityException if missing the appropriate permissions. 5686 * @deprecated Use {@link #setProfileNetworkPreferences(UserHandle, List, Executor, Runnable)} 5687 * instead as it provides a more flexible API with more options. 5688 * @hide 5689 */ 5690 // This function is for establishing per-profile default networking and can only be called by 5691 // the device policy manager, running as the system server. It would make no sense to call it 5692 // on a context for a user because it does not establish a setting on behalf of a user, rather 5693 // it establishes a setting for a user on behalf of the DPM. 5694 @SuppressLint({"UserHandle"}) 5695 @SystemApi(client = MODULE_LIBRARIES) 5696 @RequiresPermission(android.Manifest.permission.NETWORK_STACK) 5697 @Deprecated setProfileNetworkPreference(@onNull final UserHandle profile, @ProfileNetworkPreferencePolicy final int preference, @Nullable @CallbackExecutor final Executor executor, @Nullable final Runnable listener)5698 public void setProfileNetworkPreference(@NonNull final UserHandle profile, 5699 @ProfileNetworkPreferencePolicy final int preference, 5700 @Nullable @CallbackExecutor final Executor executor, 5701 @Nullable final Runnable listener) { 5702 5703 ProfileNetworkPreference.Builder preferenceBuilder = 5704 new ProfileNetworkPreference.Builder(); 5705 preferenceBuilder.setPreference(preference); 5706 if (preference != PROFILE_NETWORK_PREFERENCE_DEFAULT) { 5707 preferenceBuilder.setPreferenceEnterpriseId(NET_ENTERPRISE_ID_1); 5708 } 5709 setProfileNetworkPreferences(profile, 5710 List.of(preferenceBuilder.build()), executor, listener); 5711 } 5712 5713 /** 5714 * Set a list of default network selection policies for a user profile. 5715 * 5716 * Calling this API with a user handle defines the entire policy for that user handle. 5717 * It will overwrite any setting previously set for the same user profile, 5718 * and not affect previously set settings for other handles. 5719 * 5720 * Call this API with an empty list to remove settings for this user profile. 5721 * 5722 * See {@link ProfileNetworkPreference} for more details on each preference 5723 * parameter. 5724 * 5725 * @param profile the user profile for which the preference is being set. 5726 * @param profileNetworkPreferences the list of profile network preferences for the 5727 * provided profile. 5728 * @param executor an executor to execute the listener on. Optional if listener is null. 5729 * @param listener an optional listener to listen for completion of the operation. 5730 * @throws IllegalArgumentException if {@code profile} is not a valid user profile. 5731 * @throws SecurityException if missing the appropriate permissions. 5732 * @hide 5733 */ 5734 @SystemApi(client = MODULE_LIBRARIES) 5735 @RequiresPermission(android.Manifest.permission.NETWORK_STACK) setProfileNetworkPreferences( @onNull final UserHandle profile, @NonNull List<ProfileNetworkPreference> profileNetworkPreferences, @Nullable @CallbackExecutor final Executor executor, @Nullable final Runnable listener)5736 public void setProfileNetworkPreferences( 5737 @NonNull final UserHandle profile, 5738 @NonNull List<ProfileNetworkPreference> profileNetworkPreferences, 5739 @Nullable @CallbackExecutor final Executor executor, 5740 @Nullable final Runnable listener) { 5741 if (null != listener) { 5742 Objects.requireNonNull(executor, "Pass a non-null executor, or a null listener"); 5743 } 5744 final IOnCompleteListener proxy; 5745 if (null == listener) { 5746 proxy = null; 5747 } else { 5748 proxy = new IOnCompleteListener.Stub() { 5749 @Override 5750 public void onComplete() { 5751 executor.execute(listener::run); 5752 } 5753 }; 5754 } 5755 try { 5756 mService.setProfileNetworkPreferences(profile, profileNetworkPreferences, proxy); 5757 } catch (RemoteException e) { 5758 throw e.rethrowFromSystemServer(); 5759 } 5760 } 5761 5762 // The first network ID of IPSec tunnel interface. 5763 private static final int TUN_INTF_NETID_START = 0xFC00; // 0xFC00 = 64512 5764 // The network ID range of IPSec tunnel interface. 5765 private static final int TUN_INTF_NETID_RANGE = 0x0400; // 0x0400 = 1024 5766 5767 /** 5768 * Get the network ID range reserved for IPSec tunnel interfaces. 5769 * 5770 * @return A Range which indicates the network ID range of IPSec tunnel interface. 5771 * @hide 5772 */ 5773 @SystemApi(client = MODULE_LIBRARIES) 5774 @NonNull getIpSecNetIdRange()5775 public static Range<Integer> getIpSecNetIdRange() { 5776 return new Range(TUN_INTF_NETID_START, TUN_INTF_NETID_START + TUN_INTF_NETID_RANGE - 1); 5777 } 5778 5779 /** 5780 * Adds the specified UID to the list of UIds that are allowed to use data on metered networks 5781 * even when background data is restricted. The deny list takes precedence over the allow list. 5782 * 5783 * @param uid uid of target app 5784 * @throws IllegalStateException if updating allow list failed. 5785 * @hide 5786 */ 5787 @SystemApi(client = MODULE_LIBRARIES) 5788 @RequiresPermission(anyOf = { 5789 android.Manifest.permission.NETWORK_SETTINGS, 5790 android.Manifest.permission.NETWORK_STACK, 5791 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5792 }) addUidToMeteredNetworkAllowList(final int uid)5793 public void addUidToMeteredNetworkAllowList(final int uid) { 5794 try { 5795 mService.updateMeteredNetworkAllowList(uid, true /* add */); 5796 } catch (RemoteException e) { 5797 throw e.rethrowFromSystemServer(); 5798 } 5799 } 5800 5801 /** 5802 * Removes the specified UID from the list of UIDs that are allowed to use background data on 5803 * metered networks when background data is restricted. The deny list takes precedence over 5804 * the allow list. 5805 * 5806 * @param uid uid of target app 5807 * @throws IllegalStateException if updating allow list failed. 5808 * @hide 5809 */ 5810 @SystemApi(client = MODULE_LIBRARIES) 5811 @RequiresPermission(anyOf = { 5812 android.Manifest.permission.NETWORK_SETTINGS, 5813 android.Manifest.permission.NETWORK_STACK, 5814 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5815 }) removeUidFromMeteredNetworkAllowList(final int uid)5816 public void removeUidFromMeteredNetworkAllowList(final int uid) { 5817 try { 5818 mService.updateMeteredNetworkAllowList(uid, false /* remove */); 5819 } catch (RemoteException e) { 5820 throw e.rethrowFromSystemServer(); 5821 } 5822 } 5823 5824 /** 5825 * Adds the specified UID to the list of UIDs that are not allowed to use background data on 5826 * metered networks. Takes precedence over {@link #addUidToMeteredNetworkAllowList}. 5827 * 5828 * @param uid uid of target app 5829 * @throws IllegalStateException if updating deny list failed. 5830 * @hide 5831 */ 5832 @SystemApi(client = MODULE_LIBRARIES) 5833 @RequiresPermission(anyOf = { 5834 android.Manifest.permission.NETWORK_SETTINGS, 5835 android.Manifest.permission.NETWORK_STACK, 5836 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5837 }) addUidToMeteredNetworkDenyList(final int uid)5838 public void addUidToMeteredNetworkDenyList(final int uid) { 5839 try { 5840 mService.updateMeteredNetworkDenyList(uid, true /* add */); 5841 } catch (RemoteException e) { 5842 throw e.rethrowFromSystemServer(); 5843 } 5844 } 5845 5846 /** 5847 * Removes the specified UID from the list of UIds that can use use background data on metered 5848 * networks if background data is not restricted. The deny list takes precedence over the 5849 * allow list. 5850 * 5851 * @param uid uid of target app 5852 * @throws IllegalStateException if updating deny list failed. 5853 * @hide 5854 */ 5855 @SystemApi(client = MODULE_LIBRARIES) 5856 @RequiresPermission(anyOf = { 5857 android.Manifest.permission.NETWORK_SETTINGS, 5858 android.Manifest.permission.NETWORK_STACK, 5859 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5860 }) removeUidFromMeteredNetworkDenyList(final int uid)5861 public void removeUidFromMeteredNetworkDenyList(final int uid) { 5862 try { 5863 mService.updateMeteredNetworkDenyList(uid, false /* remove */); 5864 } catch (RemoteException e) { 5865 throw e.rethrowFromSystemServer(); 5866 } 5867 } 5868 5869 /** 5870 * Sets a firewall rule for the specified UID on the specified chain. 5871 * 5872 * @param chain target chain. 5873 * @param uid uid to allow/deny. 5874 * @param rule firewall rule to allow/drop packets. 5875 * @throws IllegalStateException if updating firewall rule failed. 5876 * @throws IllegalArgumentException if {@code rule} is not a valid rule. 5877 * @hide 5878 */ 5879 @SystemApi(client = MODULE_LIBRARIES) 5880 @RequiresPermission(anyOf = { 5881 android.Manifest.permission.NETWORK_SETTINGS, 5882 android.Manifest.permission.NETWORK_STACK, 5883 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5884 }) setUidFirewallRule(@irewallChain final int chain, final int uid, @FirewallRule final int rule)5885 public void setUidFirewallRule(@FirewallChain final int chain, final int uid, 5886 @FirewallRule final int rule) { 5887 try { 5888 mService.setUidFirewallRule(chain, uid, rule); 5889 } catch (RemoteException e) { 5890 throw e.rethrowFromSystemServer(); 5891 } 5892 } 5893 5894 /** 5895 * Enables or disables the specified firewall chain. 5896 * 5897 * @param chain target chain. 5898 * @param enable whether the chain should be enabled. 5899 * @throws IllegalStateException if enabling or disabling the firewall chain failed. 5900 * @hide 5901 */ 5902 @SystemApi(client = MODULE_LIBRARIES) 5903 @RequiresPermission(anyOf = { 5904 android.Manifest.permission.NETWORK_SETTINGS, 5905 android.Manifest.permission.NETWORK_STACK, 5906 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5907 }) setFirewallChainEnabled(@irewallChain final int chain, final boolean enable)5908 public void setFirewallChainEnabled(@FirewallChain final int chain, final boolean enable) { 5909 try { 5910 mService.setFirewallChainEnabled(chain, enable); 5911 } catch (RemoteException e) { 5912 throw e.rethrowFromSystemServer(); 5913 } 5914 } 5915 5916 /** 5917 * Replaces the contents of the specified UID-based firewall chain. 5918 * 5919 * @param chain target chain to replace. 5920 * @param uids The list of UIDs to be placed into chain. 5921 * @throws IllegalStateException if replacing the firewall chain failed. 5922 * @throws IllegalArgumentException if {@code chain} is not a valid chain. 5923 * @hide 5924 */ 5925 @SystemApi(client = MODULE_LIBRARIES) 5926 @RequiresPermission(anyOf = { 5927 android.Manifest.permission.NETWORK_SETTINGS, 5928 android.Manifest.permission.NETWORK_STACK, 5929 NetworkStack.PERMISSION_MAINLINE_NETWORK_STACK 5930 }) replaceFirewallChain(@irewallChain final int chain, @NonNull final int[] uids)5931 public void replaceFirewallChain(@FirewallChain final int chain, @NonNull final int[] uids) { 5932 Objects.requireNonNull(uids); 5933 try { 5934 mService.replaceFirewallChain(chain, uids); 5935 } catch (RemoteException e) { 5936 throw e.rethrowFromSystemServer(); 5937 } 5938 } 5939 } 5940