Deprecate most of NetworkInfo.
getType, getTypeName, isConnectedOrConnecting, isConnected,
isAvaisable, isFailover, isRoaming, getState, getDetailedState,
getReason, and the TYPE_* constants in ConnectivityManager
along with methods that use them are now stacked on a boat
bound for the other side of the Styx.
Test: no code changes
Bug: 62844794
Change-Id: Idd70763de5b1af5580b4734cd443ac4b570069cc
diff --git a/api/current.txt b/api/current.txt
index 2250379..c1ed212 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -25736,17 +25736,17 @@
field public static final int RESTRICT_BACKGROUND_STATUS_DISABLED = 1; // 0x1
field public static final int RESTRICT_BACKGROUND_STATUS_ENABLED = 3; // 0x3
field public static final int RESTRICT_BACKGROUND_STATUS_WHITELISTED = 2; // 0x2
- field public static final int TYPE_BLUETOOTH = 7; // 0x7
- field public static final int TYPE_DUMMY = 8; // 0x8
- field public static final int TYPE_ETHERNET = 9; // 0x9
- field public static final int TYPE_MOBILE = 0; // 0x0
- field public static final int TYPE_MOBILE_DUN = 4; // 0x4
+ field public static final deprecated int TYPE_BLUETOOTH = 7; // 0x7
+ field public static final deprecated int TYPE_DUMMY = 8; // 0x8
+ field public static final deprecated int TYPE_ETHERNET = 9; // 0x9
+ field public static final deprecated int TYPE_MOBILE = 0; // 0x0
+ field public static final deprecated int TYPE_MOBILE_DUN = 4; // 0x4
field public static final deprecated int TYPE_MOBILE_HIPRI = 5; // 0x5
field public static final deprecated int TYPE_MOBILE_MMS = 2; // 0x2
field public static final deprecated int TYPE_MOBILE_SUPL = 3; // 0x3
- field public static final int TYPE_VPN = 17; // 0x11
- field public static final int TYPE_WIFI = 1; // 0x1
- field public static final int TYPE_WIMAX = 6; // 0x6
+ field public static final deprecated int TYPE_VPN = 17; // 0x11
+ field public static final deprecated int TYPE_WIFI = 1; // 0x1
+ field public static final deprecated int TYPE_WIMAX = 6; // 0x6
}
public static class ConnectivityManager.NetworkCallback {
@@ -26023,16 +26023,16 @@
method public int describeContents();
method public android.net.NetworkInfo.DetailedState getDetailedState();
method public java.lang.String getExtraInfo();
- method public java.lang.String getReason();
- method public android.net.NetworkInfo.State getState();
+ method public deprecated java.lang.String getReason();
+ method public deprecated android.net.NetworkInfo.State getState();
method public int getSubtype();
method public java.lang.String getSubtypeName();
- method public int getType();
- method public java.lang.String getTypeName();
- method public boolean isAvailable();
+ method public deprecated int getType();
+ method public deprecated java.lang.String getTypeName();
+ method public deprecated boolean isAvailable();
method public boolean isConnected();
- method public boolean isConnectedOrConnecting();
- method public boolean isFailover();
+ method public deprecated boolean isConnectedOrConnecting();
+ method public deprecated boolean isFailover();
method public deprecated boolean isRoaming();
method public void writeToParcel(android.os.Parcel, int);
field public static final android.os.Parcelable.Creator<android.net.NetworkInfo> CREATOR;
diff --git a/core/java/android/net/ConnectivityManager.java b/core/java/android/net/ConnectivityManager.java
index 3a8a254..f136e27 100644
--- a/core/java/android/net/ConnectivityManager.java
+++ b/core/java/android/net/ConnectivityManager.java
@@ -453,133 +453,177 @@
public static final int TYPE_NONE = -1;
/**
- * The Mobile data connection. When active, all data traffic
- * will use this network type's interface by default
- * (it has a default route)
+ * A Mobile data connection. Devices may support more than one.
+ *
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an
+ * appropriate network. {@see NetworkCapabilities} for supported transports.
*/
+ @Deprecated
public static final int TYPE_MOBILE = 0;
+
/**
- * The WIFI data connection. When active, all data traffic
- * will use this network type's interface by default
- * (it has a default route).
+ * A WIFI data connection. Devices may support more than one.
+ *
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an
+ * appropriate network. {@see NetworkCapabilities} for supported transports.
*/
+ @Deprecated
public static final int TYPE_WIFI = 1;
+
/**
* An MMS-specific Mobile data connection. This network type may use the
* same network interface as {@link #TYPE_MOBILE} or it may use a different
* one. This is used by applications needing to talk to the carrier's
* Multimedia Messaging Service servers.
*
- * @deprecated Applications should instead use
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasCapability} or
* {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request a network that
* provides the {@link NetworkCapabilities#NET_CAPABILITY_MMS} capability.
*/
@Deprecated
public static final int TYPE_MOBILE_MMS = 2;
+
/**
* A SUPL-specific Mobile data connection. This network type may use the
* same network interface as {@link #TYPE_MOBILE} or it may use a different
* one. This is used by applications needing to talk to the carrier's
* Secure User Plane Location servers for help locating the device.
*
- * @deprecated Applications should instead use
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasCapability} or
* {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request a network that
* provides the {@link NetworkCapabilities#NET_CAPABILITY_SUPL} capability.
*/
@Deprecated
public static final int TYPE_MOBILE_SUPL = 3;
+
/**
* A DUN-specific Mobile data connection. This network type may use the
* same network interface as {@link #TYPE_MOBILE} or it may use a different
* one. This is sometimes by the system when setting up an upstream connection
* for tethering so that the carrier is aware of DUN traffic.
+ *
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasCapability} or
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request a network that
+ * provides the {@link NetworkCapabilities#NET_CAPABILITY_DUN} capability.
*/
+ @Deprecated
public static final int TYPE_MOBILE_DUN = 4;
+
/**
* A High Priority Mobile data connection. This network type uses the
* same network interface as {@link #TYPE_MOBILE} but the routing setup
* is different.
*
- * @deprecated Applications should instead use
- * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request a network that
- * uses the {@link NetworkCapabilities#TRANSPORT_CELLULAR} transport.
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an
+ * appropriate network. {@see NetworkCapabilities} for supported transports.
*/
@Deprecated
public static final int TYPE_MOBILE_HIPRI = 5;
+
/**
- * The WiMAX data connection. When active, all data traffic
- * will use this network type's interface by default
- * (it has a default route).
+ * A WiMAX data connection.
+ *
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an
+ * appropriate network. {@see NetworkCapabilities} for supported transports.
*/
+ @Deprecated
public static final int TYPE_WIMAX = 6;
/**
- * The Bluetooth data connection. When active, all data traffic
- * will use this network type's interface by default
- * (it has a default route).
+ * A Bluetooth data connection.
+ *
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an
+ * appropriate network. {@see NetworkCapabilities} for supported transports.
*/
+ @Deprecated
public static final int TYPE_BLUETOOTH = 7;
/**
* Dummy data connection. This should not be used on shipping devices.
+ * @deprecated This is not used any more.
*/
+ @Deprecated
public static final int TYPE_DUMMY = 8;
/**
- * The Ethernet data connection. When active, all data traffic
- * will use this network type's interface by default
- * (it has a default route).
+ * An Ethernet data connection.
+ *
+ * @deprecated Applications should instead use {@link NetworkCapabilities#hasTransport} or
+ * {@link #requestNetwork(NetworkRequest, NetworkCallback)} to request an
+ * appropriate network. {@see NetworkCapabilities} for supported transports.
*/
+ @Deprecated
public static final int TYPE_ETHERNET = 9;
/**
* Over the air Administration.
+ * @deprecated Use {@link NetworkCapabilities} instead.
* {@hide}
*/
+ @Deprecated
public static final int TYPE_MOBILE_FOTA = 10;
/**
* IP Multimedia Subsystem.
+ * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_IMS} instead.
* {@hide}
*/
+ @Deprecated
public static final int TYPE_MOBILE_IMS = 11;
/**
* Carrier Branded Services.
+ * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_CBS} instead.
* {@hide}
*/
+ @Deprecated
public static final int TYPE_MOBILE_CBS = 12;
/**
* A Wi-Fi p2p connection. Only requesting processes will have access to
* the peers connected.
+ * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_WIFI_P2P} instead.
* {@hide}
*/
+ @Deprecated
public static final int TYPE_WIFI_P2P = 13;
/**
* The network to use for initially attaching to the network
+ * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_IA} instead.
* {@hide}
*/
+ @Deprecated
public static final int TYPE_MOBILE_IA = 14;
/**
* Emergency PDN connection for emergency services. This
* may include IMS and MMS in emergency situations.
+ * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_EIMS} instead.
* {@hide}
*/
+ @Deprecated
public static final int TYPE_MOBILE_EMERGENCY = 15;
/**
* The network that uses proxy to achieve connectivity.
+ * @deprecated Use {@link NetworkCapabilities} instead.
* {@hide}
*/
+ @Deprecated
public static final int TYPE_PROXY = 16;
/**
* A virtual network using one or more native bearers.
* It may or may not be providing security services.
+ * @deprecated Applications should use {@link NetworkCapabilities#TRANSPORT_VPN} instead.
*/
+ @Deprecated
public static final int TYPE_VPN = 17;
/** {@hide} */
@@ -686,8 +730,10 @@
* @param type the type needing naming
* @return a String for the given type, or a string version of the type ("87")
* if no name is known.
+ * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead.
* {@hide}
*/
+ @Deprecated
public static String getNetworkTypeName(int type) {
switch (type) {
case TYPE_NONE:
@@ -738,8 +784,10 @@
* This should be replaced in the future by a network property.
* @param networkType the type to check
* @return a boolean - {@code true} if uses cellular network, else {@code false}
+ * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead.
* {@hide}
*/
+ @Deprecated
public static boolean isNetworkTypeMobile(int networkType) {
switch (networkType) {
case TYPE_MOBILE:
@@ -761,8 +809,10 @@
/**
* Checks if the given network type is backed by a Wi-Fi radio.
*
+ * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead.
* @hide
*/
+ @Deprecated
public static boolean isNetworkTypeWifi(int networkType) {
switch (networkType) {
case TYPE_WIFI:
@@ -1529,6 +1579,8 @@
* IllegalArgumentException if no mapping from the legacy type to
* NetworkCapabilities is known.
*
+ * @deprecated Types are deprecated. Use {@link NetworkCallback} or {@link NetworkRequest}
+ * to find the network instead.
* @hide
*/
public static NetworkCapabilities networkCapabilitiesForType(int type) {
@@ -2380,6 +2432,7 @@
*
* @param networkType The type of network you want to report on
* @param percentage The quality of the connection 0 is bad, 100 is good
+ * @deprecated Types are deprecated. Use {@link #reportNetworkConnectivity} instead.
* {@hide}
*/
public void reportInetCondition(int networkType, int percentage) {
@@ -2511,9 +2564,10 @@
*
* @param networkType The network type we'd like to check
* @return {@code true} if supported, else {@code false}
- *
+ * @deprecated Types are deprecated. Use {@link NetworkCapabilities} instead.
* @hide
*/
+ @Deprecated
@RequiresPermission(android.Manifest.permission.ACCESS_NETWORK_STATE)
public boolean isNetworkSupported(int networkType) {
try {
diff --git a/core/java/android/net/NetworkInfo.java b/core/java/android/net/NetworkInfo.java
index e6ad89a..999771a 100644
--- a/core/java/android/net/NetworkInfo.java
+++ b/core/java/android/net/NetworkInfo.java
@@ -38,14 +38,18 @@
* <table>
* <tr><td><b>Detailed state</b></td><td><b>Coarse-grained state</b></td></tr>
* <tr><td><code>IDLE</code></td><td><code>DISCONNECTED</code></td></tr>
- * <tr><td><code>SCANNING</code></td><td><code>CONNECTING</code></td></tr>
+ * <tr><td><code>SCANNING</code></td><td><code>DISCONNECTED</code></td></tr>
* <tr><td><code>CONNECTING</code></td><td><code>CONNECTING</code></td></tr>
* <tr><td><code>AUTHENTICATING</code></td><td><code>CONNECTING</code></td></tr>
+ * <tr><td><code>OBTAINING_IPADDR</code></td><td><code>CONNECTING</code></td></tr>
+ * <tr><td><code>VERIFYING_POOR_LINK</code></td><td><code>CONNECTING</code></td></tr>
+ * <tr><td><code>CAPTIVE_PORTAL_CHECK</code></td><td><code>CONNECTING</code></td></tr>
* <tr><td><code>CONNECTED</code></td><td><code>CONNECTED</code></td></tr>
+ * <tr><td><code>SUSPENDED</code></td><td><code>SUSPENDED</code></td></tr>
* <tr><td><code>DISCONNECTING</code></td><td><code>DISCONNECTING</code></td></tr>
* <tr><td><code>DISCONNECTED</code></td><td><code>DISCONNECTED</code></td></tr>
- * <tr><td><code>UNAVAILABLE</code></td><td><code>DISCONNECTED</code></td></tr>
* <tr><td><code>FAILED</code></td><td><code>DISCONNECTED</code></td></tr>
+ * <tr><td><code>BLOCKED</code></td><td><code>DISCONNECTED</code></td></tr>
* </table>
*/
public enum State {
@@ -163,8 +167,17 @@
* @return one of {@link ConnectivityManager#TYPE_MOBILE}, {@link
* ConnectivityManager#TYPE_WIFI}, {@link ConnectivityManager#TYPE_WIMAX}, {@link
* ConnectivityManager#TYPE_ETHERNET}, {@link ConnectivityManager#TYPE_BLUETOOTH}, or other
- * types defined by {@link ConnectivityManager}
+ * types defined by {@link ConnectivityManager}.
+ * @deprecated Callers should switch to checking {@link NetworkCapabilities#hasTransport}
+ * instead with one of the NetworkCapabilities#TRANSPORT_* constants :
+ * {@link #getType} and {@link #getTypeName} cannot account for networks using
+ * multiple transports. Note that generally apps should not care about transport;
+ * {@link NetworkCapabilities#NET_CAPABILITY_NOT_METERED} and
+ * {@link NetworkCapabilities#getLinkDownstreamBandwidthKbps} are calls that
+ * apps concerned with meteredness or bandwidth should be looking at, as they
+ * offer this information with much better accuracy.
*/
+ @Deprecated
public int getType() {
synchronized (this) {
return mNetworkType;
@@ -172,8 +185,10 @@
}
/**
+ * @deprecated Use {@link NetworkCapabilities} instead
* @hide
*/
+ @Deprecated
public void setType(int type) {
synchronized (this) {
mNetworkType = type;
@@ -205,7 +220,16 @@
* Return a human-readable name describe the type of the network,
* for example "WIFI" or "MOBILE".
* @return the name of the network type
+ * @deprecated Callers should switch to checking {@link NetworkCapabilities#hasTransport}
+ * instead with one of the NetworkCapabilities#TRANSPORT_* constants :
+ * {@link #getType} and {@link #getTypeName} cannot account for networks using
+ * multiple transports. Note that generally apps should not care about transport;
+ * {@link NetworkCapabilities#NET_CAPABILITY_NOT_METERED} and
+ * {@link NetworkCapabilities#getLinkDownstreamBandwidthKbps} are calls that
+ * apps concerned with meteredness or bandwidth should be looking at, as they
+ * offer this information with much better accuracy.
*/
+ @Deprecated
public String getTypeName() {
synchronized (this) {
return mTypeName;
@@ -230,7 +254,15 @@
* that the network is fully usable.
* @return {@code true} if network connectivity exists or is in the process
* of being established, {@code false} otherwise.
+ * @deprecated Apps should instead use the
+ * {@link android.net.ConnectivityManager.NetworkCallback} API to
+ * learn about connectivity changes.
+ * {@link ConnectivityManager#registerDefaultNetworkCallback} and
+ * {@link ConnectivityManager#registerNetworkCallback}. These will
+ * give a more accurate picture of the connectivity state of
+ * the device and let apps react more easily and quickly to changes.
*/
+ @Deprecated
public boolean isConnectedOrConnecting() {
synchronized (this) {
return mState == State.CONNECTED || mState == State.CONNECTING;
@@ -259,8 +291,18 @@
* data roaming has been disabled.</li>
* <li>The device's radio is turned off, e.g., because airplane mode is enabled.</li>
* </ul>
+ * Since Android L, this always returns {@code true}, because the system only
+ * returns info for available networks.
* @return {@code true} if the network is available, {@code false} otherwise
+ * @deprecated Apps should instead use the
+ * {@link android.net.ConnectivityManager.NetworkCallback} API to
+ * learn about connectivity changes.
+ * {@link ConnectivityManager#registerDefaultNetworkCallback} and
+ * {@link ConnectivityManager#registerNetworkCallback}. These will
+ * give a more accurate picture of the connectivity state of
+ * the device and let apps react more easily and quickly to changes.
*/
+ @Deprecated
public boolean isAvailable() {
synchronized (this) {
return mIsAvailable;
@@ -270,9 +312,11 @@
/**
* Sets if the network is available, ie, if the connectivity is possible.
* @param isAvailable the new availability value.
+ * @deprecated Use {@link NetworkCapabilities} instead
*
* @hide
*/
+ @Deprecated
public void setIsAvailable(boolean isAvailable) {
synchronized (this) {
mIsAvailable = isAvailable;
@@ -285,7 +329,10 @@
* network following a disconnect from another network.
* @return {@code true} if this is a failover attempt, {@code false}
* otherwise.
+ * @deprecated This field is not populated in recent Android releases,
+ * and does not make a lot of sense in a multi-network world.
*/
+ @Deprecated
public boolean isFailover() {
synchronized (this) {
return mIsFailover;
@@ -296,8 +343,10 @@
* Set the failover boolean.
* @param isFailover {@code true} to mark the current connection attempt
* as a failover.
+ * @deprecated This hasn't been set in any recent Android release.
* @hide
*/
+ @Deprecated
public void setFailover(boolean isFailover) {
synchronized (this) {
mIsFailover = isFailover;
@@ -322,7 +371,10 @@
}
}
- /** {@hide} */
+ /**
+ * @deprecated Use {@link NetworkCapabilities#NET_CAPABILITY_NOT_ROAMING} instead.
+ * {@hide}
+ */
@VisibleForTesting
@Deprecated
public void setRoaming(boolean isRoaming) {
@@ -334,7 +386,15 @@
/**
* Reports the current coarse-grained state of the network.
* @return the coarse-grained state
+ * @deprecated Apps should instead use the
+ * {@link android.net.ConnectivityManager.NetworkCallback} API to
+ * learn about connectivity changes.
+ * {@link ConnectivityManager#registerDefaultNetworkCallback} and
+ * {@link ConnectivityManager#registerNetworkCallback}. These will
+ * give a more accurate picture of the connectivity state of
+ * the device and let apps react more easily and quickly to changes.
*/
+ @Deprecated
public State getState() {
synchronized (this) {
return mState;
@@ -358,8 +418,10 @@
* if one was supplied. May be {@code null}.
* @param extraInfo an optional {@code String} providing addditional network state
* information passed up from the lower networking layers.
+ * @deprecated Use {@link NetworkCapabilities} instead.
* @hide
*/
+ @Deprecated
public void setDetailedState(DetailedState detailedState, String reason, String extraInfo) {
synchronized (this) {
this.mDetailedState = detailedState;
@@ -385,6 +447,8 @@
* Report the reason an attempt to establish connectivity failed,
* if one is available.
* @return the reason for failure, or null if not available
+ * @deprecated This method does not have a consistent contract that could make it useful
+ * to callers.
*/
public String getReason() {
synchronized (this) {