diff --git a/core/java/android/net/NetworkCapabilities.java b/core/java/android/net/NetworkCapabilities.java index 8005e5ca7e..35274f1e7e 100644 --- a/core/java/android/net/NetworkCapabilities.java +++ b/core/java/android/net/NetworkCapabilities.java @@ -30,13 +30,31 @@ import java.util.Map.Entry; import java.util.Set; /** - * A class representing the capabilities of a network - * @hide + * This class represents the capabilities of a network. This is used both to specify + * needs to {@link ConnectivityManager} and when inspecting a network. + * + * Note that this replaces the old {@link ConnectivityManager#TYPE_MOBILE} method + * of network selection. Rather than indicate a need for Wi-Fi because an application + * needs high bandwidth and risk obselence when a new, fast network appears (like LTE), + * the application should specify it needs high bandwidth. Similarly if an application + * needs an unmetered network for a bulk transfer it can specify that rather than assuming + * all cellular based connections are metered and all Wi-Fi based connections are not. */ public final class NetworkCapabilities implements Parcelable { private static final String TAG = "NetworkCapabilities"; private static final boolean DBG = false; + public NetworkCapabilities() { + } + + public NetworkCapabilities(NetworkCapabilities nc) { + if (nc != null) { + mNetworkCapabilities = nc.mNetworkCapabilities; + mTransportTypes = nc.mTransportTypes; + mLinkUpBandwidthKbps = nc.mLinkUpBandwidthKbps; + mLinkDownBandwidthKbps = nc.mLinkDownBandwidthKbps; + } + } /** * Represents the network's capabilities. If any are specified they will be satisfied @@ -45,28 +63,99 @@ public final class NetworkCapabilities implements Parcelable { private long mNetworkCapabilities = (1 << NET_CAPABILITY_NOT_RESTRICTED); /** - * Values for NetworkCapabilities. Roughly matches/extends deprecated - * ConnectivityManager TYPE_* + * Indicates this is a network that has the ability to reach the + * carrier's MMSC for sending and receiving MMS messages. */ public static final int NET_CAPABILITY_MMS = 0; + + /** + * Indicates this is a network that has the ability to reach the carrier's + * SUPL server, used to retrieve GPS information. + */ public static final int NET_CAPABILITY_SUPL = 1; + + /** + * Indicates this is a network that has the ability to reach the carrier's + * DUN or tethering gateway. + */ public static final int NET_CAPABILITY_DUN = 2; + + /** + * Indicates this is a network that has the ability to reach the carrier's + * FOTA portal, used for over the air updates. + */ public static final int NET_CAPABILITY_FOTA = 3; + + /** + * Indicates this is a network that has the ability to reach the carrier's + * IMS servers, used for network registration and signaling. + */ public static final int NET_CAPABILITY_IMS = 4; + + /** + * Indicates this is a network that has the ability to reach the carrier's + * CBS servers, used for carrier specific services. + */ public static final int NET_CAPABILITY_CBS = 5; + + /** + * Indicates this is a network that has the ability to reach a Wi-Fi direct + * peer. + */ public static final int NET_CAPABILITY_WIFI_P2P = 6; + + /** + * Indicates this is a network that has the ability to reach a carrier's + * Initial Attach servers. + */ public static final int NET_CAPABILITY_IA = 7; + + /** + * Indicates this is a network that has the ability to reach a carrier's + * RCS servers, used for Rich Communication Services. + */ public static final int NET_CAPABILITY_RCS = 8; + + /** + * Indicates this is a network that has the ability to reach a carrier's + * XCAP servers, used for configuration and control. + */ public static final int NET_CAPABILITY_XCAP = 9; + + /** + * Indicates this is a network that has the ability to reach a carrier's + * Emergency IMS servers, used for network signaling during emergency calls. + */ public static final int NET_CAPABILITY_EIMS = 10; + + /** + * Indicates that this network is unmetered. + */ public static final int NET_CAPABILITY_NOT_METERED = 11; + + /** + * Indicates that this network should be able to reach the internet. + */ public static final int NET_CAPABILITY_INTERNET = 12; - /** Set by default */ + + /** + * Indicates that this network is available for general use. If this is not set + * applications should not attempt to communicate on this network. Note that this + * is simply informative and not enforcement - enforcement is handled via other means. + * Set by default. + */ public static final int NET_CAPABILITY_NOT_RESTRICTED = 13; private static final int MIN_NET_CAPABILITY = NET_CAPABILITY_MMS; private static final int MAX_NET_CAPABILITY = NET_CAPABILITY_NOT_RESTRICTED; + /** + * Adds the given capability to this {@code NetworkCapability} instance. + * Multiple capabilities may be applied sequentially. Note that when searching + * for a network to satisfy a request, all capabilities requested must be satisfied. + * + * @param networkCapability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be added. + */ public void addNetworkCapability(int networkCapability) { if (networkCapability < MIN_NET_CAPABILITY || networkCapability > MAX_NET_CAPABILITY) { @@ -74,6 +163,12 @@ public final class NetworkCapabilities implements Parcelable { } mNetworkCapabilities |= 1 << networkCapability; } + + /** + * Removes (if found) the given capability from this {@code NetworkCapability} instance. + * + * @param networkCapability the {@code NetworkCapabilities.NET_CAPABILTIY_*} to be removed. + */ public void removeNetworkCapability(int networkCapability) { if (networkCapability < MIN_NET_CAPABILITY || networkCapability > MAX_NET_CAPABILITY) { @@ -81,9 +176,23 @@ public final class NetworkCapabilities implements Parcelable { } mNetworkCapabilities &= ~(1 << networkCapability); } + + /** + * Gets all the capabilities set on this {@code NetworkCapability} instance. + * + * @return a {@link Collection} of {@code NetworkCapabilities.NET_CAPABILITY_*} values + * for this instance. + */ public Collection getNetworkCapabilities() { return enumerateBits(mNetworkCapabilities); } + + /** + * Tests for the presence of a capabilitity on this instance. + * + * @param networkCapability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be tested for. + * @return {@code true} if set on this instance. + */ public boolean hasCapability(int networkCapability) { if (networkCapability < MIN_NET_CAPABILITY || networkCapability > MAX_NET_CAPABILITY) { @@ -124,31 +233,74 @@ public final class NetworkCapabilities implements Parcelable { private long mTransportTypes; /** - * Values for TransportType + * Indicates this network uses a Cellular transport. */ public static final int TRANSPORT_CELLULAR = 0; + + /** + * Indicates this network uses a Wi-Fi transport. + */ public static final int TRANSPORT_WIFI = 1; + + /** + * Indicates this network uses a Bluetooth transport. + */ public static final int TRANSPORT_BLUETOOTH = 2; + + /** + * Indicates this network uses an Ethernet transport. + */ public static final int TRANSPORT_ETHERNET = 3; private static final int MIN_TRANSPORT = TRANSPORT_CELLULAR; private static final int MAX_TRANSPORT = TRANSPORT_ETHERNET; + /** + * Adds the given transport type to this {@code NetworkCapability} instance. + * Multiple transports may be applied sequentially. Note that when searching + * for a network to satisfy a request, any listed in the request will satisfy the request. + * For example {@code TRANSPORT_WIFI} and {@code TRANSPORT_ETHERNET} added to a + * {@code NetworkCapabilities} would cause either a Wi-Fi network or an Ethernet network + * to be selected. This is logically different than + * {@code NetworkCapabilities.NET_CAPABILITY_*} listed above. + * + * @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be added. + */ public void addTransportType(int transportType) { if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) { throw new IllegalArgumentException("TransportType out of range"); } mTransportTypes |= 1 << transportType; } + + /** + * Removes (if found) the given transport from this {@code NetworkCapability} instance. + * + * @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be removed. + */ public void removeTransportType(int transportType) { if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) { throw new IllegalArgumentException("TransportType out of range"); } mTransportTypes &= ~(1 << transportType); } + + /** + * Gets all the transports set on this {@code NetworkCapability} instance. + * + * @return a {@link Collection} of {@code NetworkCapabilities.TRANSPORT_*} values + * for this instance. + */ public Collection getTransportTypes() { return enumerateBits(mTransportTypes); } + + /** + * Tests for the presence of a transport on this instance. + * + * @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be tested for. + * @return {@code true} if set on this instance. + */ public boolean hasTransport(int transportType) { if (transportType < MIN_TRANSPORT || transportType > MAX_TRANSPORT) { return false; @@ -175,15 +327,58 @@ public final class NetworkCapabilities implements Parcelable { private int mLinkUpBandwidthKbps; private int mLinkDownBandwidthKbps; + /** + * Sets the upstream bandwidth for this network in Kbps. This always only refers to + * the estimated first hop transport bandwidth. + *

+ * Note that when used to request a network, this specifies the minimum acceptable. + * When received as the state of an existing network this specifies the typical + * first hop bandwidth expected. This is never measured, but rather is inferred + * from technology type and other link parameters. It could be used to differentiate + * between very slow 1xRTT cellular links and other faster networks or even between + * 802.11b vs 802.11AC wifi technologies. It should not be used to differentiate between + * fast backhauls and slow backhauls. + * + * @param upKbps the estimated first hop upstream (device to network) bandwidth. + */ public void setLinkUpstreamBandwidthKbps(int upKbps) { mLinkUpBandwidthKbps = upKbps; } + + /** + * Retrieves the upstream bandwidth for this network in Kbps. This always only refers to + * the estimated first hop transport bandwidth. + * + * @return The estimated first hop upstream (device to network) bandwidth. + */ public int getLinkUpstreamBandwidthKbps() { return mLinkUpBandwidthKbps; } + + /** + * Sets the downstream bandwidth for this network in Kbps. This always only refers to + * the estimated first hop transport bandwidth. + *

+ * Note that when used to request a network, this specifies the minimum acceptable. + * When received as the state of an existing network this specifies the typical + * first hop bandwidth expected. This is never measured, but rather is inferred + * from technology type and other link parameters. It could be used to differentiate + * between very slow 1xRTT cellular links and other faster networks or even between + * 802.11b vs 802.11AC wifi technologies. It should not be used to differentiate between + * fast backhauls and slow backhauls. + * + * @param downKbps the estimated first hop downstream (network to device) bandwidth. + */ public void setLinkDownstreamBandwidthKbps(int downKbps) { mLinkDownBandwidthKbps = downKbps; } + + /** + * Retrieves the downstream bandwidth for this network in Kbps. This always only refers to + * the estimated first hop transport bandwidth. + * + * @return The estimated first hop downstream (network to device) bandwidth. + */ public int getLinkDownstreamBandwidthKbps() { return mLinkDownBandwidthKbps; } @@ -243,19 +438,6 @@ public final class NetworkCapabilities implements Parcelable { (mLinkDownBandwidthKbps * 13)); } - public NetworkCapabilities() { - } - - public NetworkCapabilities(NetworkCapabilities nc) { - if (nc != null) { - mNetworkCapabilities = nc.mNetworkCapabilities; - mTransportTypes = nc.mTransportTypes; - mLinkUpBandwidthKbps = nc.mLinkUpBandwidthKbps; - mLinkDownBandwidthKbps = nc.mLinkDownBandwidthKbps; - } - } - - // Parcelable public int describeContents() { return 0; }