Update the docs for NetworkCapabilities (01d004ef) · Commits · e / os / android_frameworks_base

api/current.txt

+38 −0

Original line number	Diff line number	Diff line
		@@ -15953,6 +15953,44 @@ package android.net {
		field public static final java.lang.String MAILTO_SCHEME = "mailto:";
		}

		public final class NetworkCapabilities implements android.os.Parcelable {
		ctor public NetworkCapabilities();
		ctor public NetworkCapabilities(android.net.NetworkCapabilities);
		method public void addNetworkCapability(int);
		method public void addTransportType(int);
		method public int describeContents();
		method public int getLinkDownstreamBandwidthKbps();
		method public int getLinkUpstreamBandwidthKbps();
		method public java.util.Collection<java.lang.Integer> getNetworkCapabilities();
		method public java.util.Collection<java.lang.Integer> getTransportTypes();
		method public boolean hasCapability(int);
		method public boolean hasTransport(int);
		method public void removeNetworkCapability(int);
		method public void removeTransportType(int);
		method public void setLinkDownstreamBandwidthKbps(int);
		method public void setLinkUpstreamBandwidthKbps(int);
		method public void writeToParcel(android.os.Parcel, int);
		field public static final android.os.Parcelable.Creator CREATOR;
		field public static final int NET_CAPABILITY_CBS = 5; // 0x5
		field public static final int NET_CAPABILITY_DUN = 2; // 0x2
		field public static final int NET_CAPABILITY_EIMS = 10; // 0xa
		field public static final int NET_CAPABILITY_FOTA = 3; // 0x3
		field public static final int NET_CAPABILITY_IA = 7; // 0x7
		field public static final int NET_CAPABILITY_IMS = 4; // 0x4
		field public static final int NET_CAPABILITY_INTERNET = 12; // 0xc
		field public static final int NET_CAPABILITY_MMS = 0; // 0x0
		field public static final int NET_CAPABILITY_NOT_METERED = 11; // 0xb
		field public static final int NET_CAPABILITY_NOT_RESTRICTED = 13; // 0xd
		field public static final int NET_CAPABILITY_RCS = 8; // 0x8
		field public static final int NET_CAPABILITY_SUPL = 1; // 0x1
		field public static final int NET_CAPABILITY_WIFI_P2P = 6; // 0x6
		field public static final int NET_CAPABILITY_XCAP = 9; // 0x9
		field public static final int TRANSPORT_BLUETOOTH = 2; // 0x2
		field public static final int TRANSPORT_CELLULAR = 0; // 0x0
		field public static final int TRANSPORT_ETHERNET = 3; // 0x3
		field public static final int TRANSPORT_WIFI = 1; // 0x1
		}

		public class NetworkInfo implements android.os.Parcelable {
		method public int describeContents();
		method public android.net.NetworkInfo.DetailedState getDetailedState();

core/java/android/net/NetworkCapabilities.java

+201 −19

Original line number	Diff line number	Diff line
		@@ -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<Integer> 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<Integer> 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.
		* <p>
		* 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.
		* <p>
		* 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;
		}