Merge "Improve NetworkCapabilities docs." am: 14a51058b1 am: b385ba095b (9cd92adb) · Commits · e / os / android_frameworks_base

core/java/android/net/NetworkCapabilities.java

+63 −24

Original line number	Diff line number	Diff line
		@@ -16,6 +16,7 @@

		package android.net;

		import android.annotation.IntDef;
		import android.os.Parcel;
		import android.os.Parcelable;

		@@ -23,6 +24,8 @@ import com.android.internal.annotations.VisibleForTesting;
		import com.android.internal.util.BitUtils;
		import com.android.internal.util.Preconditions;

		import java.lang.annotation.Retention;
		import java.lang.annotation.RetentionPolicy;
		import java.util.Objects;
		import java.util.StringJoiner;

		@@ -77,6 +80,31 @@ public final class NetworkCapabilities implements Parcelable {
		*/
		private long mNetworkCapabilities;

		/** @hide */
		@Retention(RetentionPolicy.SOURCE)
		@IntDef(prefix = { "NET_CAPABILITY_" }, value = {
		NET_CAPABILITY_MMS,
		NET_CAPABILITY_SUPL,
		NET_CAPABILITY_DUN,
		NET_CAPABILITY_FOTA,
		NET_CAPABILITY_IMS,
		NET_CAPABILITY_CBS,
		NET_CAPABILITY_WIFI_P2P,
		NET_CAPABILITY_IA,
		NET_CAPABILITY_RCS,
		NET_CAPABILITY_XCAP,
		NET_CAPABILITY_EIMS,
		NET_CAPABILITY_NOT_METERED,
		NET_CAPABILITY_INTERNET,
		NET_CAPABILITY_NOT_RESTRICTED,
		NET_CAPABILITY_TRUSTED,
		NET_CAPABILITY_NOT_VPN,
		NET_CAPABILITY_VALIDATED,
		NET_CAPABILITY_CAPTIVE_PORTAL,
		NET_CAPABILITY_FOREGROUND,
		})
		public @interface NetCapability { }

		/**
		* Indicates this is a network that has the ability to reach the
		* carrier's MMSC for sending and receiving MMS messages.
		@@ -260,11 +288,11 @@ public final class NetworkCapabilities implements Parcelable {
		* Multiple capabilities may be applied sequentially. Note that when searching
		* for a network to satisfy a request, all capabilities requested must be satisfied.
		*
		* @param capability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be added.
		* @param capability the capability to be added.
		* @return This NetworkCapabilities instance, to facilitate chaining.
		* @hide
		*/
		public NetworkCapabilities addCapability(int capability) {
		public NetworkCapabilities addCapability(@NetCapability int capability) {
		if (capability < MIN_NET_CAPABILITY \|\| capability > MAX_NET_CAPABILITY) {
		throw new IllegalArgumentException("NetworkCapability out of range");
		}
		@@ -275,11 +303,11 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* Removes (if found) the given capability from this {@code NetworkCapability} instance.
		*
		* @param capability the {@code NetworkCapabilities.NET_CAPABILTIY_*} to be removed.
		* @param capability the capability to be removed.
		* @return This NetworkCapabilities instance, to facilitate chaining.
		* @hide
		*/
		public NetworkCapabilities removeCapability(int capability) {
		public NetworkCapabilities removeCapability(@NetCapability int capability) {
		if (capability < MIN_NET_CAPABILITY \|\| capability > MAX_NET_CAPABILITY) {
		throw new IllegalArgumentException("NetworkCapability out of range");
		}
		@@ -290,21 +318,20 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* Gets all the capabilities set on this {@code NetworkCapability} instance.
		*
		* @return an array of {@code NetworkCapabilities.NET_CAPABILITY_*} values
		* for this instance.
		* @return an array of capability values for this instance.
		* @hide
		*/
		public int[] getCapabilities() {
		public @NetCapability int[] getCapabilities() {
		return BitUtils.unpackBits(mNetworkCapabilities);
		}

		/**
		* Tests for the presence of a capabilitity on this instance.
		*
		* @param capability the {@code NetworkCapabilities.NET_CAPABILITY_*} to be tested for.
		* @param capability the capabilities to be tested for.
		* @return {@code true} if set on this instance.
		*/
		public boolean hasCapability(int capability) {
		public boolean hasCapability(@NetCapability int capability) {
		if (capability < MIN_NET_CAPABILITY \|\| capability > MAX_NET_CAPABILITY) {
		return false;
		}
		@@ -385,6 +412,19 @@ public final class NetworkCapabilities implements Parcelable {
		*/
		private long mTransportTypes;

		/** @hide */
		@Retention(RetentionPolicy.SOURCE)
		@IntDef(prefix = { "TRANSPORT_" }, value = {
		TRANSPORT_CELLULAR,
		TRANSPORT_WIFI,
		TRANSPORT_BLUETOOTH,
		TRANSPORT_ETHERNET,
		TRANSPORT_VPN,
		TRANSPORT_WIFI_AWARE,
		TRANSPORT_LOWPAN,
		})
		public @interface Transport { }

		/**
		* Indicates this network uses a Cellular transport.
		*/
		@@ -426,7 +466,7 @@ public final class NetworkCapabilities implements Parcelable {
		public static final int MAX_TRANSPORT = TRANSPORT_LOWPAN;

		/** @hide */
		public static boolean isValidTransport(int transportType) {
		public static boolean isValidTransport(@Transport int transportType) {
		return (MIN_TRANSPORT <= transportType) && (transportType <= MAX_TRANSPORT);
		}

		@@ -449,11 +489,11 @@ public final class NetworkCapabilities implements Parcelable {
		* to be selected. This is logically different than
		* {@code NetworkCapabilities.NET_CAPABILITY_*} listed above.
		*
		* @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be added.
		* @param transportType the transport type to be added.
		* @return This NetworkCapabilities instance, to facilitate chaining.
		* @hide
		*/
		public NetworkCapabilities addTransportType(int transportType) {
		public NetworkCapabilities addTransportType(@Transport int transportType) {
		checkValidTransportType(transportType);
		mTransportTypes \|= 1 << transportType;
		setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
		@@ -463,11 +503,11 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* Removes (if found) the given transport from this {@code NetworkCapability} instance.
		*
		* @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be removed.
		* @param transportType the transport type to be removed.
		* @return This NetworkCapabilities instance, to facilitate chaining.
		* @hide
		*/
		public NetworkCapabilities removeTransportType(int transportType) {
		public NetworkCapabilities removeTransportType(@Transport int transportType) {
		checkValidTransportType(transportType);
		mTransportTypes &= ~(1 << transportType);
		setNetworkSpecifier(mNetworkSpecifier); // used for exception checking
		@@ -477,21 +517,20 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* Gets all the transports set on this {@code NetworkCapability} instance.
		*
		* @return an array of {@code NetworkCapabilities.TRANSPORT_*} values
		* for this instance.
		* @return an array of transport type values for this instance.
		* @hide
		*/
		public int[] getTransportTypes() {
		public @Transport int[] getTransportTypes() {
		return BitUtils.unpackBits(mTransportTypes);
		}

		/**
		* Tests for the presence of a transport on this instance.
		*
		* @param transportType the {@code NetworkCapabilities.TRANSPORT_*} to be tested for.
		* @param transportType the transport type to be tested for.
		* @return {@code true} if set on this instance.
		*/
		public boolean hasTransport(int transportType) {
		public boolean hasTransport(@Transport int transportType) {
		return isValidTransport(transportType) && ((mTransportTypes & (1 << transportType)) != 0);
		}

		@@ -896,7 +935,7 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* @hide
		*/
		public static String capabilityNamesOf(int[] capabilities) {
		public static String capabilityNamesOf(@NetCapability int[] capabilities) {
		StringJoiner joiner = new StringJoiner("\|");
		if (capabilities != null) {
		for (int c : capabilities) {
		@@ -909,7 +948,7 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* @hide
		*/
		public static String capabilityNameOf(int capability) {
		public static String capabilityNameOf(@NetCapability int capability) {
		switch (capability) {
		case NET_CAPABILITY_MMS: return "MMS";
		case NET_CAPABILITY_SUPL: return "SUPL";
		@@ -937,7 +976,7 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* @hide
		*/
		public static String transportNamesOf(int[] types) {
		public static String transportNamesOf(@Transport int[] types) {
		StringJoiner joiner = new StringJoiner("\|");
		if (types != null) {
		for (int t : types) {
		@@ -950,14 +989,14 @@ public final class NetworkCapabilities implements Parcelable {
		/**
		* @hide
		*/
		public static String transportNameOf(int transport) {
		public static String transportNameOf(@Transport int transport) {
		if (!isValidTransport(transport)) {
		return "UNKNOWN";
		}
		return TRANSPORT_NAMES[transport];
		}

		private static void checkValidTransportType(int transport) {
		private static void checkValidTransportType(@Transport int transport) {
		Preconditions.checkArgument(
		isValidTransport(transport), "Invalid TransportType " + transport);
		}

core/java/android/net/NetworkRequest.java

+10 −12

Original line number	Diff line number	Diff line
		@@ -155,14 +155,13 @@ public class NetworkRequest implements Parcelable {
		* Add the given capability requirement to this builder. These represent
		* the requested network's required capabilities. Note that when searching
		* for a network to satisfy a request, all capabilities requested must be
		* satisfied. See {@link NetworkCapabilities} for {@code NET_CAPABILITY_*}
		* definitions.
		* satisfied.
		*
		* @param capability The {@code NetworkCapabilities.NET_CAPABILITY_*} to add.
		* @param capability The capability to add.
		* @return The builder to facilitate chaining
		* {@code builder.addCapability(...).addCapability();}.
		*/
		public Builder addCapability(int capability) {
		public Builder addCapability(@NetworkCapabilities.NetCapability int capability) {
		mNetworkCapabilities.addCapability(capability);
		return this;
		}
		@@ -170,10 +169,10 @@ public class NetworkRequest implements Parcelable {
		/**
		* Removes (if found) the given capability from this builder instance.
		*
		* @param capability The {@code NetworkCapabilities.NET_CAPABILITY_*} to remove.
		* @param capability The capability to remove.
		* @return The builder to facilitate chaining.
		*/
		public Builder removeCapability(int capability) {
		public Builder removeCapability(@NetworkCapabilities.NetCapability int capability) {
		mNetworkCapabilities.removeCapability(capability);
		return this;
		}
		@@ -208,13 +207,12 @@ public class NetworkRequest implements Parcelable {
		* Adds the given transport requirement to this builder. These represent
		* the set of allowed transports for the request. Only networks using one
		* of these transports will satisfy the request. If no particular transports
		* are required, none should be specified here. See {@link NetworkCapabilities}
		* for {@code TRANSPORT_*} definitions.
		* are required, none should be specified here.
		*
		* @param transportType The {@code NetworkCapabilities.TRANSPORT_*} to add.
		* @param transportType The transport type to add.
		* @return The builder to facilitate chaining.
		*/
		public Builder addTransportType(int transportType) {
		public Builder addTransportType(@NetworkCapabilities.Transport int transportType) {
		mNetworkCapabilities.addTransportType(transportType);
		return this;
		}
		@@ -222,10 +220,10 @@ public class NetworkRequest implements Parcelable {
		/**
		* Removes (if found) the given transport from this builder instance.
		*
		* @param transportType The {@code NetworkCapabilities.TRANSPORT_*} to remove.
		* @param transportType The transport type to remove.
		* @return The builder to facilitate chaining.
		*/
		public Builder removeTransportType(int transportType) {
		public Builder removeTransportType(@NetworkCapabilities.Transport int transportType) {
		mNetworkCapabilities.removeTransportType(transportType);
		return this;
		}