diff --git a/core/api/current.txt b/core/api/current.txt index 230689dda0c92..917d89cd8e7d0 100644 --- a/core/api/current.txt +++ b/core/api/current.txt @@ -27276,6 +27276,23 @@ package android.net.sip { package android.net.vcn { + public final class VcnCellUnderlyingNetworkTemplate extends android.net.vcn.VcnUnderlyingNetworkTemplate { + method @NonNull public java.util.Set getOperatorPlmnIds(); + method public int getOpportunistic(); + method public int getRoaming(); + method @NonNull public java.util.Set getSimSpecificCarrierIds(); + } + + public static final class VcnCellUnderlyingNetworkTemplate.Builder { + ctor public VcnCellUnderlyingNetworkTemplate.Builder(); + method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate build(); + method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setMetered(int); + method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setOperatorPlmnIds(@NonNull java.util.Set); + method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setOpportunistic(int); + method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setRoaming(int); + method @NonNull public android.net.vcn.VcnCellUnderlyingNetworkTemplate.Builder setSimSpecificCarrierIds(@NonNull java.util.Set); + } + public final class VcnConfig implements android.os.Parcelable { method public int describeContents(); method @NonNull public java.util.Set getGatewayConnectionConfigs(); @@ -27294,6 +27311,7 @@ package android.net.vcn { method @NonNull public String getGatewayConnectionName(); method @IntRange(from=0x500) public int getMaxMtu(); method @NonNull public long[] getRetryIntervalsMillis(); + method @NonNull public java.util.List getVcnUnderlyingNetworkPriorities(); } public static final class VcnGatewayConnectionConfig.Builder { @@ -27303,6 +27321,7 @@ package android.net.vcn { method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder removeExposedCapability(int); method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setMaxMtu(@IntRange(from=0x500) int); method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setRetryIntervalsMillis(@NonNull long[]); + method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setVcnUnderlyingNetworkPriorities(@NonNull java.util.List); } public class VcnManager { @@ -27326,6 +27345,24 @@ package android.net.vcn { method public abstract void onStatusChanged(int); } + public abstract class VcnUnderlyingNetworkTemplate { + method public int getMetered(); + field public static final int MATCH_ANY = 0; // 0x0 + field public static final int MATCH_FORBIDDEN = 2; // 0x2 + field public static final int MATCH_REQUIRED = 1; // 0x1 + } + + public final class VcnWifiUnderlyingNetworkTemplate extends android.net.vcn.VcnUnderlyingNetworkTemplate { + method @NonNull public java.util.Set getSsids(); + } + + public static final class VcnWifiUnderlyingNetworkTemplate.Builder { + ctor public VcnWifiUnderlyingNetworkTemplate.Builder(); + method @NonNull public android.net.vcn.VcnWifiUnderlyingNetworkTemplate build(); + method @NonNull public android.net.vcn.VcnWifiUnderlyingNetworkTemplate.Builder setMetered(int); + method @NonNull public android.net.vcn.VcnWifiUnderlyingNetworkTemplate.Builder setSsids(@NonNull java.util.Set); + } + } package android.nfc { diff --git a/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java b/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java index 2dcb6872d63bb..125b5730b2ed9 100644 --- a/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java +++ b/core/java/android/net/vcn/VcnCellUnderlyingNetworkTemplate.java @@ -49,8 +49,6 @@ import java.util.Set; * networks. * *

See {@link VcnUnderlyingNetworkTemplate} - * - * @hide */ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetworkTemplate { private static final String ALLOWED_NETWORK_PLMN_IDS_KEY = "mAllowedNetworkPlmnIds"; @@ -279,8 +277,13 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork /** * Set the matching criteria for metered networks. * + *

A template where setMetered(MATCH_REQUIRED) will only match metered networks (one + * without NET_CAPABILITY_NOT_METERED). A template where setMetered(MATCH_FORBIDDEN) will + * only match a network that is not metered (one with NET_CAPABILITY_NOT_METERED). + * * @param matchCriteria the matching criteria for metered networks. Defaults to {@link - * #MATCH_ANY}. See {@link NetworkCapabilities#NET_CAPABILITY_NOT_METERED} + * #MATCH_ANY}. + * @see NetworkCapabilities#NET_CAPABILITY_NOT_METERED */ // The matching getter is defined in the super class. Please see {@link // VcnUnderlyingNetworkTemplate#getMetered()} @@ -300,10 +303,11 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork * priority from a partner's networks. * * @param operatorPlmnIds the matching operator PLMN IDs in String. Network with one of the - * matching PLMN IDs can match this template. Defaults to an empty set, allowing ANY - * PLMN ID. A valid PLMN is a concatenation of MNC and MCC, and thus consists of 5 or 6 - * decimal digits. See {@link SubscriptionInfo#getMccString()} and {@link - * SubscriptionInfo#getMncString()}. + * matching PLMN IDs can match this template. If the set is empty, any PLMN ID will + * match. The default is an empty set. A valid PLMN is a concatenation of MNC and MCC, + * and thus consists of 5 or 6 decimal digits. + * @see SubscriptionInfo#getMccString() + * @see SubscriptionInfo#getMncString() */ @NonNull public Builder setOperatorPlmnIds(@NonNull Set operatorPlmnIds) { @@ -318,8 +322,9 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork * Set sim specific carrier IDs with which a network can match this template. * * @param simSpecificCarrierIds the matching sim specific carrier IDs. Network with one of - * the sim specific carrier IDs can match this template. Defaults to an empty set, - * allowing ANY carrier ID. See {@link TelephonyManager#getSimSpecificCarrierId()}. + * the sim specific carrier IDs can match this template. If the set is empty, any + * carrier ID will match. The default is an empty set. + * @see TelephonyManager#getSimSpecificCarrierId() */ @NonNull public Builder setSimSpecificCarrierIds(@NonNull Set simSpecificCarrierIds) { @@ -333,8 +338,13 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork /** * Set the matching criteria for roaming networks. * + *

A template where setRoaming(MATCH_REQUIRED) will only match roaming networks (one + * without NET_CAPABILITY_NOT_ROAMING). A template where setRoaming(MATCH_FORBIDDEN) will + * only match a network that is not roaming (one with NET_CAPABILITY_NOT_ROAMING). + * * @param matchCriteria the matching criteria for roaming networks. Defaults to {@link - * #MATCH_ANY}. See {@link NetworkCapabilities#NET_CAPABILITY_NOT_ROAMING}. + * #MATCH_ANY}. + * @see NetworkCapabilities#NET_CAPABILITY_NOT_ROAMING */ @NonNull public Builder setRoaming(@MatchCriteria int matchCriteria) { @@ -348,8 +358,8 @@ public final class VcnCellUnderlyingNetworkTemplate extends VcnUnderlyingNetwork * Set the matching criteria for opportunistic cellular subscriptions. * * @param matchCriteria the matching criteria for opportunistic cellular subscriptions. - * Defaults to {@link #MATCH_ANY}. See {@link - * SubscriptionManager#setOpportunistic(boolean, int)} + * Defaults to {@link #MATCH_ANY}. + * @see SubscriptionManager#setOpportunistic(boolean, int) */ @NonNull public Builder setOpportunistic(@MatchCriteria int matchCriteria) { diff --git a/core/java/android/net/vcn/VcnGatewayConnectionConfig.java b/core/java/android/net/vcn/VcnGatewayConnectionConfig.java index f17f30a0d1d8c..92956e859fc70 100644 --- a/core/java/android/net/vcn/VcnGatewayConnectionConfig.java +++ b/core/java/android/net/vcn/VcnGatewayConnectionConfig.java @@ -375,11 +375,10 @@ public final class VcnGatewayConnectionConfig { /** * Retrieve the VcnUnderlyingNetworkTemplate list, or a default list if it is not configured. * - * @see Builder#setVcnUnderlyingNetworkTemplates(List) - * @hide + * @see Builder#setVcnUnderlyingNetworkPriorities(List) */ @NonNull - public List getVcnUnderlyingNetworkTemplates() { + public List getVcnUnderlyingNetworkPriorities() { return new ArrayList<>(mUnderlyingNetworkTemplates); } @@ -543,29 +542,28 @@ public final class VcnGatewayConnectionConfig { } /** - * Set the list of templates to match underlying networks against, in priority order. + * Set the list of templates to match underlying networks against, in high-to-low priority + * order. * - *

To select the VCN underlying network, the VCN gateway will go through all the network - * candidates and return a network matching the highest priority rule. + *

To select the VCN underlying network, the VCN connection will go through all the + * network candidates and return a network matching the highest priority rule. * *

If multiple networks match the same rule, the VCN will prefer an already-selected * network as opposed to a new/unselected network. However, if both are new/unselected * networks, a network will be chosen arbitrarily amongst the networks matching the highest * priority rule. * - *

A rule that matches all carrier-owned networks is implicitly added at the end of the - * priority list, ensuring that if all networks fail to match the rules provided, an - * underlying network will still be selected (at random if necessary). + *

If all networks fail to match the rules provided, an underlying network will still be + * selected (at random if necessary). * * @param underlyingNetworkTemplates a list of unique VcnUnderlyingNetworkTemplates that are * ordered from most to least preferred, or an empty list to use the default * prioritization. The default network prioritization order is Opportunistic cellular, * Carrier WiFi and then Macro cellular. * @return this {@link Builder} instance, for chaining - * @hide */ @NonNull - public Builder setVcnUnderlyingNetworkTemplates( + public Builder setVcnUnderlyingNetworkPriorities( @NonNull List underlyingNetworkTemplates) { validateNetworkTemplateList(underlyingNetworkTemplates); diff --git a/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java b/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java index 33b02e8f10e6e..60fc936072fb4 100644 --- a/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java +++ b/core/java/android/net/vcn/VcnUnderlyingNetworkTemplate.java @@ -22,7 +22,6 @@ import static com.android.internal.annotations.VisibleForTesting.Visibility; import android.annotation.IntDef; import android.annotation.NonNull; import android.annotation.Nullable; -import android.net.NetworkCapabilities; import android.os.PersistableBundle; import android.util.SparseArray; @@ -41,9 +40,7 @@ import java.util.Objects; *

Apps provisioning a VCN can configure the underlying network priority for each Gateway * Connection by setting a list (in priority order, most to least preferred) of the appropriate * subclasses in the VcnGatewayConnectionConfig. See {@link - * VcnGatewayConnectionConfig.Builder#setVcnUnderlyingNetworkTemplates} - * - * @hide + * VcnGatewayConnectionConfig.Builder#setVcnUnderlyingNetworkPriorities} */ public abstract class VcnUnderlyingNetworkTemplate { /** @hide */ @@ -69,22 +66,23 @@ public abstract class VcnUnderlyingNetworkTemplate { public @interface NetworkQuality {} /** - * Used to configure the matching criteria of a network capability (See {@link - * NetworkCapabilities}). Denotes that networks with or without the capability are both - * acceptable to match the template. + * Used to configure the matching criteria of a network characteristic. This may include network + * capabilities, or cellular subscription information. Denotes that networks with or without the + * characteristic are both acceptable to match this template. */ public static final int MATCH_ANY = 0; /** - * Used to configure the matching criteria of a network capability (See {@link - * NetworkCapabilities}). Denotes that only network with the capability can match the template. + * Used to configure the matching criteria of a network characteristic. This may include network + * capabilities, or cellular subscription information. Denotes that a network MUST have the + * capability in order to match this template. */ public static final int MATCH_REQUIRED = 1; /** - * Used to configure the matching criteria of a network capability (See {@link - * NetworkCapabilities}). Denotes that only network without the capability can match the - * template. + * Used to configure the matching criteria of a network characteristic. This may include network + * capabilities, or cellular subscription information. Denotes that a network MUST NOT have the + * capability in order to match this template. */ public static final int MATCH_FORBIDDEN = 2; diff --git a/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java b/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java index fcf5b0943053d..272ca9dd75833 100644 --- a/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java +++ b/core/java/android/net/vcn/VcnWifiUnderlyingNetworkTemplate.java @@ -40,8 +40,6 @@ import java.util.Set; * networks. * *

See {@link VcnUnderlyingNetworkTemplate} - * - * @hide */ public final class VcnWifiUnderlyingNetworkTemplate extends VcnUnderlyingNetworkTemplate { private static final String SSIDS_KEY = "mSsids"; @@ -168,8 +166,13 @@ public final class VcnWifiUnderlyingNetworkTemplate extends VcnUnderlyingNetwork /** * Set the matching criteria for metered networks. * + *

A template where setMetered(MATCH_REQUIRED) will only match metered networks (one + * without NET_CAPABILITY_NOT_METERED). A template where setMetered(MATCH_FORBIDDEN) will + * only match a network that is not metered (one with NET_CAPABILITY_NOT_METERED). + * * @param matchCriteria the matching criteria for metered networks. Defaults to {@link - * #MATCH_ANY}. See {@link NetworkCapabilities#NET_CAPABILITY_NOT_METERED} + * #MATCH_ANY}. + * @see NetworkCapabilities#NET_CAPABILITY_NOT_METERED */ // The matching getter is defined in the super class. Please see {@link // VcnUnderlyingNetworkTemplate#getMetered()} @@ -186,7 +189,7 @@ public final class VcnWifiUnderlyingNetworkTemplate extends VcnUnderlyingNetwork * Set the SSIDs with which a network can match this priority rule. * * @param ssids the matching SSIDs. Network with one of the matching SSIDs can match this - * priority rule. Defaults to an empty set, allowing ANY SSID. + * priority rule. If the set is empty, any SSID will match. The default is an empty set. */ @NonNull public Builder setSsids(@NonNull Set ssids) { diff --git a/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java b/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java index 6933e6641d292..ca2e449ffc25b 100644 --- a/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java +++ b/services/core/java/com/android/server/vcn/routeselection/UnderlyingNetworkController.java @@ -401,7 +401,7 @@ public class UnderlyingNetworkController { new TreeSet<>( UnderlyingNetworkRecord.getComparator( mVcnContext, - mConnectionConfig.getVcnUnderlyingNetworkTemplates(), + mConnectionConfig.getVcnUnderlyingNetworkPriorities(), mSubscriptionGroup, mLastSnapshot, mCurrentRecord, @@ -502,7 +502,7 @@ public class UnderlyingNetworkController { pw.increaseIndent(); int index = 0; for (VcnUnderlyingNetworkTemplate priority : - mConnectionConfig.getVcnUnderlyingNetworkTemplates()) { + mConnectionConfig.getVcnUnderlyingNetworkPriorities()) { pw.println("Priority index: " + index); priority.dump(pw); index++; @@ -518,7 +518,7 @@ public class UnderlyingNetworkController { record.dump( mVcnContext, pw, - mConnectionConfig.getVcnUnderlyingNetworkTemplates(), + mConnectionConfig.getVcnUnderlyingNetworkPriorities(), mSubscriptionGroup, mLastSnapshot, mCurrentRecord, diff --git a/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java b/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java index d7884e40b4296..2aef9ae7ca327 100644 --- a/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java +++ b/tests/vcn/java/android/net/vcn/VcnGatewayConnectionConfigTest.java @@ -96,7 +96,7 @@ public class VcnGatewayConnectionConfigTest { // Public for use in VcnGatewayConnectionTest public static VcnGatewayConnectionConfig buildTestConfig() { final VcnGatewayConnectionConfig.Builder builder = - newBuilder().setVcnUnderlyingNetworkTemplates(UNDERLYING_NETWORK_TEMPLATES); + newBuilder().setVcnUnderlyingNetworkPriorities(UNDERLYING_NETWORK_TEMPLATES); return buildTestConfigWithExposedCaps(builder, EXPOSED_CAPS); } @@ -177,7 +177,7 @@ public class VcnGatewayConnectionConfigTest { @Test public void testBuilderRequiresNonNullNetworkTemplates() { try { - newBuilder().setVcnUnderlyingNetworkTemplates(null); + newBuilder().setVcnUnderlyingNetworkPriorities(null); fail("Expected exception due to invalid underlyingNetworkTemplates"); } catch (NullPointerException e) { } @@ -220,7 +220,7 @@ public class VcnGatewayConnectionConfigTest { Arrays.sort(exposedCaps); assertArrayEquals(EXPOSED_CAPS, exposedCaps); - assertEquals(UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkTemplates()); + assertEquals(UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkPriorities()); assertEquals(TUNNEL_CONNECTION_PARAMS, config.getTunnelConnectionParams()); assertArrayEquals(RETRY_INTERVALS_MS, config.getRetryIntervalsMillis()); @@ -241,7 +241,7 @@ public class VcnGatewayConnectionConfigTest { final VcnGatewayConnectionConfig config = new VcnGatewayConnectionConfig(configBundle); assertEquals( - DEFAULT_UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkTemplates()); + DEFAULT_UNDERLYING_NETWORK_TEMPLATES, config.getVcnUnderlyingNetworkPriorities()); } private static IkeTunnelConnectionParams buildTunnelConnectionParams(String ikePsk) { @@ -292,7 +292,7 @@ public class VcnGatewayConnectionConfigTest { new VcnGatewayConnectionConfig.Builder( "buildTestConfigWithVcnUnderlyingNetworkTemplates", TUNNEL_CONNECTION_PARAMS) - .setVcnUnderlyingNetworkTemplates(networkTemplates), + .setVcnUnderlyingNetworkPriorities(networkTemplates), EXPOSED_CAPS); }