Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 049c180a authored by Benedict Wong's avatar Benedict Wong
Browse files

Expose Basic VCN API surface 

This change exposes the Basics of the VCN API surface, including:
- VCN Configurations
- VCN Gateway Configuration superclass (Builder in subclasses)
- VcnManger with configuration management APIs

Bug: 168833866
Test: atest FrameworksVcnTests
Test: atest android.net.vcn
Change-Id: Ia1b3597d903dd84267f66546a90437f9ac45b2de
parent c5bc3bcd

core/api/current.txt

+40 −0
Original line number Diff line number Diff line
@@ -26092,6 +26092,46 @@ package android.net.sip { 














}



























package android.net.vcn {

























  public final class VcnConfig implements android.os.Parcelable {













    method public int describeContents();













    method @NonNull public java.util.Set<android.net.vcn.VcnGatewayConnectionConfig> getGatewayConnectionConfigs();













    method public void writeToParcel(@NonNull android.os.Parcel, int);













    field @NonNull public static final android.os.Parcelable.Creator<android.net.vcn.VcnConfig> CREATOR;













  }

























  public static final class VcnConfig.Builder {













    ctor public VcnConfig.Builder(@NonNull android.content.Context);













    method @NonNull public android.net.vcn.VcnConfig.Builder addGatewayConnectionConfig(@NonNull android.net.vcn.VcnGatewayConnectionConfig);













    method @NonNull public android.net.vcn.VcnConfig build();













  }

























  public final class VcnGatewayConnectionConfig {













    method @NonNull public int[] getExposedCapabilities();













    method @IntRange(from=android.net.vcn.VcnGatewayConnectionConfig.MIN_MTU_V6) public int getMaxMtu();













    method @NonNull public int[] getRequiredUnderlyingCapabilities();













    method @NonNull public long[] getRetryInterval();













  }

























  public static final class VcnGatewayConnectionConfig.Builder {













    ctor public VcnGatewayConnectionConfig.Builder();













    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder addExposedCapability(int);













    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder addRequiredUnderlyingCapability(int);













    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig build();













    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder removeExposedCapability(int);













    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder removeRequiredUnderlyingCapability(int);













    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setMaxMtu(@IntRange(from=android.net.vcn.VcnGatewayConnectionConfig.MIN_MTU_V6) int);













    method @NonNull public android.net.vcn.VcnGatewayConnectionConfig.Builder setRetryInterval(@NonNull long[]);













  }

























  public class VcnManager {













    method @RequiresPermission("carrier privileges") public void clearVcnConfig(@NonNull android.os.ParcelUuid) throws java.io.IOException;













    method @RequiresPermission("carrier privileges") public void setVcnConfig(@NonNull android.os.ParcelUuid, @NonNull android.net.vcn.VcnConfig) throws java.io.IOException;













  }

























}



























package android.nfc {





























  public class FormatException extends java.lang.Exception {

























core/java/android/net/vcn/VcnConfig.java



+5
−14




























Original line number
Diff line number
Diff line








@@ -20,6 +20,7 @@ import static com.android.internal.annotations.VisibleForTesting.Visibility;













import android.annotation.NonNull;















import android.annotation.Nullable;















import android.content.Context;













import android.net.NetworkRequest;















import android.os.Parcel;















import android.os.Parcelable;















import android.os.PersistableBundle;









@@ -41,7 +42,6 @@ import java.util.Set;













 * brought up on demand based on active {@link NetworkRequest}(s).















 *















 * @see VcnManager for more information on the Virtual Carrier Network feature













 * @hide















 */















public final class VcnConfig implements Parcelable {















    @NonNull private static final String TAG = VcnConfig.class.getSimpleName();









@@ -56,7 +56,8 @@ public final class VcnConfig implements Parcelable {













            @NonNull String packageName,















            @NonNull Set<VcnGatewayConnectionConfig> gatewayConnectionConfigs) {















        mPackageName = packageName;













        mGatewayConnectionConfigs = Collections.unmodifiableSet(gatewayConnectionConfigs);













        mGatewayConnectionConfigs =













                Collections.unmodifiableSet(new ArraySet<>(gatewayConnectionConfigs));































        validate();















    }










@@ -96,11 +97,7 @@ public final class VcnConfig implements Parcelable {













        return mPackageName;















    }





























    /**













     * Retrieves the set of configured tunnels.













     *













     * @hide













     */













    /** Retrieves the set of configured GatewayConnection(s). */















    @NonNull















    public Set<VcnGatewayConnectionConfig> getGatewayConnectionConfigs() {















        return Collections.unmodifiableSet(mGatewayConnectionConfigs);










@@ -168,11 +165,7 @@ public final class VcnConfig implements Parcelable {













                }















            };





























    /**













     * This class is used to incrementally build {@link VcnConfig} objects.













     *













     * @hide













     */













    /** This class is used to incrementally build {@link VcnConfig} objects. */















    public static final class Builder {















        @NonNull private final String mPackageName;

























@@ -190,7 +183,6 @@ public final class VcnConfig implements Parcelable {













         *















         * @param gatewayConnectionConfig the configuration for an individual gateway connection















         * @return this {@link Builder} instance, for chaining













         * @hide















         */















        @NonNull















        public Builder addGatewayConnectionConfig(









@@ -205,7 +197,6 @@ public final class VcnConfig implements Parcelable {













         * Builds and validates the VcnConfig.















         *















         * @return an immutable VcnConfig instance













         * @hide















         */















        @NonNull















        public VcnConfig build() {

































core/java/android/net/vcn/VcnGatewayConnectionConfig.java



+24
−38




























Original line number
Diff line number
Diff line








@@ -21,6 +21,8 @@ import android.annotation.IntDef;













import android.annotation.IntRange;















import android.annotation.NonNull;















import android.annotation.Nullable;













import android.annotation.SuppressLint;













import android.net.Network;















import android.net.NetworkCapabilities;















import android.os.PersistableBundle;















import android.util.ArraySet;










@@ -55,28 +57,23 @@ import java.util.concurrent.TimeUnit;













 * subscription group under which this configuration is registered (see {@link















 * VcnManager#setVcnConfig}).















 *













 * <p>Services that can be provided by a VCN network, or required for underlying networks are













 * limited to services provided by cellular networks:













 * <p>As an abstraction of a cellular network, services that can be provided by a VCN network, or













 * required for underlying networks are limited to services provided by cellular networks:















 *















 * <ul>













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_MMS}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_SUPL}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_DUN}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_FOTA}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_IMS}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_CBS}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_IA}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_RCS}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_XCAP}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_EIMS}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_INTERNET}













 *   <li>{@link android.net.NetworkCapabilities.NET_CAPABILITY_MCX}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_MMS}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_SUPL}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_DUN}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_FOTA}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_IMS}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_CBS}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_IA}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_RCS}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_XCAP}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_EIMS}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_INTERNET}













 *   <li>{@link NetworkCapabilities#NET_CAPABILITY_MCX}















 * </ul>













 *













 * <p>The meteredness and roaming of the VCN {@link Network} will be determined by that of the













 * underlying Network(s).













 *













 * @hide















 */















public final class VcnGatewayConnectionConfig {















    // TODO: Use MIN_MTU_V6 once it is public, @hide










@@ -249,8 +246,7 @@ public final class VcnGatewayConnectionConfig {













     * ascending numerical order.















     *















     * @see Builder#addExposedCapability(int)













     * @see Builder#clearExposedCapability(int)













     * @hide













     * @see Builder#removeExposedCapability(int)















     */















    @NonNull















    public int[] getExposedCapabilities() {










@@ -278,8 +274,7 @@ public final class VcnGatewayConnectionConfig {













     * <p>The returned integer-value capabilities will be sorted in ascending numerical order.















     *















     * @see Builder#addRequiredUnderlyingCapability(int)













     * @see Builder#clearRequiredUnderlyingCapability(int)













     * @hide













     * @see Builder#removeRequiredUnderlyingCapability(int)















     */















    @NonNull















    public int[] getRequiredUnderlyingCapabilities() {









@@ -305,7 +300,6 @@ public final class VcnGatewayConnectionConfig {













     * Retrieves the configured retry intervals.















     *















     * @see Builder#setRetryInterval(long[])













     * @hide















     */















    @NonNull















    public long[] getRetryInterval() {









@@ -317,7 +311,7 @@ public final class VcnGatewayConnectionConfig {













     *















     * <p>Left to prevent the need to make major changes while changes are actively in flight.















     *













     * @deprecated use getRequiredUnderlyingCapabilities() instead













     * @deprecated use getRetryInterval() instead















     * @hide















     */















    @Deprecated









@@ -329,8 +323,7 @@ public final class VcnGatewayConnectionConfig {













    /**















     * Retrieves the maximum MTU allowed for this Gateway Connection.















     *













     * @see Builder.setMaxMtu(int)













     * @hide













     * @see Builder#setMaxMtu(int)















     */















    @IntRange(from = MIN_MTU_V6)















    public int getMaxMtu() {










@@ -388,8 +381,6 @@ public final class VcnGatewayConnectionConfig {





























    /**















     * This class is used to incrementally build {@link VcnGatewayConnectionConfig} objects.













     *













     * @hide















     */















    public static final class Builder {















        @NonNull private final Set<Integer> mExposedCapabilities = new ArraySet();









@@ -409,7 +400,6 @@ public final class VcnGatewayConnectionConfig {













         * @return this {@link Builder} instance, for chaining















         * @see VcnGatewayConnectionConfig for a list of capabilities may be exposed by a Gateway















         *     Connection













         * @hide















         */















        @NonNull















        public Builder addExposedCapability(@VcnSupportedCapability int exposedCapability) {









@@ -427,10 +417,10 @@ public final class VcnGatewayConnectionConfig {













         * @return this {@link Builder} instance, for chaining















         * @see VcnGatewayConnectionConfig for a list of capabilities may be exposed by a Gateway















         *     Connection













         * @hide















         */















        @NonNull













        public Builder clearExposedCapability(@VcnSupportedCapability int exposedCapability) {













        @SuppressLint("BuilderSetStyle") // For consistency with NetCaps.Builder add/removeCap













        public Builder removeExposedCapability(@VcnSupportedCapability int exposedCapability) {















            checkValidCapability(exposedCapability);































            mExposedCapabilities.remove(exposedCapability);









@@ -445,7 +435,6 @@ public final class VcnGatewayConnectionConfig {













         * @return this {@link Builder} instance, for chaining















         * @see VcnGatewayConnectionConfig for a list of capabilities may be required of underlying















         *     networks













         * @hide















         */















        @NonNull















        public Builder addRequiredUnderlyingCapability(









@@ -468,10 +457,10 @@ public final class VcnGatewayConnectionConfig {













         * @return this {@link Builder} instance, for chaining















         * @see VcnGatewayConnectionConfig for a list of capabilities may be required of underlying















         *     networks













         * @hide















         */















        @NonNull













        public Builder clearRequiredUnderlyingCapability(













        @SuppressLint("BuilderSetStyle") // For consistency with NetCaps.Builder add/removeCap













        public Builder removeRequiredUnderlyingCapability(















                @VcnSupportedCapability int underlyingCapability) {















            checkValidCapability(underlyingCapability);


























@@ -501,7 +490,6 @@ public final class VcnGatewayConnectionConfig {













         *     15m]}















         * @return this {@link Builder} instance, for chaining















         * @see VcnManager for additional discussion on fail-safe mode













         * @hide















         */















        @NonNull















        public Builder setRetryInterval(@NonNull long[] retryIntervalsMs) {









@@ -523,7 +511,6 @@ public final class VcnGatewayConnectionConfig {













         * @param maxMtu the maximum MTU allowed for this Gateway Connection. Must be greater than















         *     the IPv6 minimum MTU of 1280. Defaults to 1500.















         * @return this {@link Builder} instance, for chaining













         * @hide















         */















        @NonNull















        public Builder setMaxMtu(@IntRange(from = MIN_MTU_V6) int maxMtu) {









@@ -538,7 +525,6 @@ public final class VcnGatewayConnectionConfig {













         * Builds and validates the VcnGatewayConnectionConfig.















         *















         * @return an immutable VcnGatewayConnectionConfig instance













         * @hide















         */















        @NonNull















        public VcnGatewayConnectionConfig build() {

































core/java/android/net/vcn/VcnManager.java



+9
−15




























Original line number
Diff line number
Diff line








@@ -39,12 +39,12 @@ import java.util.concurrent.Executor;













/**















 * VcnManager publishes APIs for applications to configure and manage Virtual Carrier Networks.















 *













 * <p>A VCN creates a virtualization layer to allow MVNOs to aggregate heterogeneous physical













 * <p>A VCN creates a virtualization layer to allow carriers to aggregate heterogeneous physical















 * networks, unifying them as a single carrier network. This enables infrastructure flexibility on













 * the part of MVNOs without impacting user connectivity, abstracting the physical network













 * the part of carriers without impacting user connectivity, abstracting the physical network















 * technologies as an implementation detail of their public network.















 *













 * <p>Each VCN virtualizes an Carrier's network by building tunnels to a carrier's core network over













 * <p>Each VCN virtualizes a carrier's network by building tunnels to a carrier's core network over















 * carrier-managed physical links and supports a IP mobility layer to ensure seamless transitions















 * between the underlying networks. Each VCN is configured based on a Subscription Group (see {@link















 * android.telephony.SubscriptionManager}) and aggregates all networks that are brought up based on









@@ -62,8 +62,6 @@ import java.util.concurrent.Executor;













 * tasks. In Safe Mode, the system will allow underlying cellular networks to be used as default.















 * Additionally, during Safe Mode, the VCN will continue to retry the connections, and will















 * automatically exit Safe Mode if all active tunnels connect successfully.













 *













 * @hide















 */















@SystemService(Context.VCN_MANAGEMENT_SERVICE)















public class VcnManager {










@@ -101,7 +99,6 @@ public class VcnManager {













        return Collections.unmodifiableMap(REGISTERED_POLICY_LISTENERS);















    }





























    // TODO: Make setVcnConfig(), clearVcnConfig() Public API















    /**















     * Sets the VCN configuration for a given subscription group.















     *









@@ -113,11 +110,10 @@ public class VcnManager {













     *















     * @param subscriptionGroup the subscription group that the configuration should be applied to















     * @param config the configuration parameters for the VCN













     * @throws SecurityException if the caller does not have carrier privileges, or is not running













     *     as the primary user













     * @throws IOException if the configuration failed to be persisted. A caller encountering this













     *     exception should attempt to retry (possibly after a delay).













     * @hide













     * @throws SecurityException if the caller does not have carrier privileges for the provided













     *     subscriptionGroup, or is not running as the primary user













     * @throws IOException if the configuration failed to be saved and persisted to disk. This may













     *     occur due to temporary disk errors, or more permanent conditions such as a full disk.















     */















    @RequiresPermission("carrier privileges") // TODO (b/72967236): Define a system-wide constant















    public void setVcnConfig(@NonNull ParcelUuid subscriptionGroup, @NonNull VcnConfig config)









@@ -134,7 +130,6 @@ public class VcnManager {













        }















    }





























    // TODO: Make setVcnConfig(), clearVcnConfig() Public API















    /**















     * Clears the VCN configuration for a given subscription group.















     *









@@ -145,9 +140,8 @@ public class VcnManager {













     * @param subscriptionGroup the subscription group that the configuration should be applied to















     * @throws SecurityException if the caller does not have carrier privileges, or is not running















     *     as the primary user













     * @throws IOException if the configuration failed to be cleared. A caller encountering this













     *     exception should attempt to retry (possibly after a delay).













     * @hide













     * @throws IOException if the configuration failed to be cleared from disk. This may occur due













     *     to temporary disk errors, or more permanent conditions such as a full disk.















     */















    @RequiresPermission("carrier privileges") // TODO (b/72967236): Define a system-wide constant















    public void clearVcnConfig(@NonNull ParcelUuid subscriptionGroup) throws IOException {