Merge "Expose VCN Network policy APIs." am: 32a2e39563

Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/1544188

MUST ONLY BE SUBMITTED BY AUTOMERGER

Change-Id: Idd1b88665ce81f637c96a2b16bdb2206ab223097

core/api/system-current.txt

@@ -6850,6 +6850,28 @@ package android.net.util {
 
 }
 
+package android.net.vcn {
+
+  public class VcnManager {
+    method @RequiresPermission(android.Manifest.permission.NETWORK_FACTORY) public void addVcnNetworkPolicyListener(@NonNull java.util.concurrent.Executor, @NonNull android.net.vcn.VcnManager.VcnNetworkPolicyListener);
+    method @NonNull @RequiresPermission(android.Manifest.permission.NETWORK_FACTORY) public android.net.vcn.VcnNetworkPolicyResult applyVcnNetworkPolicy(@NonNull android.net.NetworkCapabilities, @NonNull android.net.LinkProperties);
+    method public void removeVcnNetworkPolicyListener(@NonNull android.net.vcn.VcnManager.VcnNetworkPolicyListener);
+  }
+
+  public static interface VcnManager.VcnNetworkPolicyListener {
+    method public void onPolicyChanged();
+  }
+
+  public final class VcnNetworkPolicyResult implements android.os.Parcelable {
+    method public int describeContents();
+    method @NonNull public android.net.NetworkCapabilities getNetworkCapabilities();
+    method public boolean isTeardownRequested();
+    method public void writeToParcel(@NonNull android.os.Parcel, int);
+    field @NonNull public static final android.os.Parcelable.Creator<android.net.vcn.VcnNetworkPolicyResult> CREATOR;
+  }
+
+}
+
 package android.net.wifi {
 
   public final class WifiMigration {

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

@@ -21,6 +21,7 @@ import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.annotation.RequiresPermission;
+import android.annotation.SystemApi;
 import android.annotation.SystemService;
 import android.content.Context;
 import android.net.LinkProperties;
@@ -231,13 +232,20 @@ public class VcnManager {
         }
     }
 
-    // TODO: make VcnNetworkPolicyListener @SystemApi
     /**
-     * VcnNetworkPolicyListener is the interface through which internal system components can
-     * register to receive updates for VCN-underlying Network policies from the System Server.
+     * VcnNetworkPolicyListener is the interface through which internal system components (e.g.
+     * Network Factories) can register to receive updates for VCN-underlying Network policies from
+     * the System Server.
+     *
+     * <p>Any Network Factory that brings up Networks capable of being VCN-underlying Networks
+     * should register a VcnNetworkPolicyListener. VcnManager will then use this listener to notify
+     * the registrant when VCN Network policies change. Upon receiving this signal, the listener
+     * must check {@link VcnManager} for the current Network policy result for each of its Networks
+     * via {@link #applyVcnNetworkPolicy(NetworkCapabilities, LinkProperties)}.
      *
      * @hide
      */
+    @SystemApi
     public interface VcnNetworkPolicyListener {
         /**
          * Notifies the implementation that the VCN's underlying Network policy has changed.
@@ -252,6 +260,9 @@ public class VcnManager {
     /**
      * Add a listener for VCN-underlying Network policy updates.
      *
+     * <p>A {@link VcnNetworkPolicyListener} is eligible to begin receiving callbacks once it is
+     * registered. No callbacks are guaranteed upon registration.
+     *
      * @param executor the Executor that will be used for invoking all calls to the specified
      *     Listener
      * @param listener the VcnNetworkPolicyListener to be added
@@ -259,6 +270,7 @@ public class VcnManager {
      * @throws IllegalStateException if the specified VcnNetworkPolicyListener is already registered
      * @hide
      */
+    @SystemApi
     @RequiresPermission(android.Manifest.permission.NETWORK_FACTORY)
     public void addVcnNetworkPolicyListener(
             @NonNull Executor executor, @NonNull VcnNetworkPolicyListener listener) {
@@ -287,6 +299,7 @@ public class VcnManager {
      * @param listener the VcnNetworkPolicyListener that will be removed
      * @hide
      */
+    @SystemApi
     public void removeVcnNetworkPolicyListener(@NonNull VcnNetworkPolicyListener listener) {
         requireNonNull(listener, "listener must not be null");
 
@@ -319,6 +332,7 @@ public class VcnManager {
      * @hide
      */
     @NonNull
+    @SystemApi
     @RequiresPermission(android.Manifest.permission.NETWORK_FACTORY)
     public VcnNetworkPolicyResult applyVcnNetworkPolicy(
             @NonNull NetworkCapabilities networkCapabilities,

core/java/android/net/vcn/VcnNetworkPolicyResult.java

@@ -17,6 +17,7 @@
 package android.net.vcn;
 
 import android.annotation.NonNull;
+import android.annotation.SystemApi;
 import android.net.NetworkCapabilities;
 import android.os.Parcel;
 import android.os.Parcelable;
@@ -27,12 +28,13 @@ import java.util.Objects;
  * VcnNetworkPolicyResult represents the Network policy result for a Network transport applying its
  * VCN policy via {@link VcnManager#applyVcnNetworkPolicy(NetworkCapabilities, LinkProperties)}.
  *
- * <p>Transports that are bringing up networks capable of acting as a VCN's underlying network
- * should query for policy state upon any capability changes (e.g. changing of TRUSTED bit), and
- * when prompted by VcnManagementService via VcnNetworkPolicyListener.
+ * <p>Bearers that are bringing up networks capable of acting as a VCN's underlying network should
+ * query for Network policy results upon any capability changes (e.g. changing of TRUSTED bit), and
+ * when prompted by VcnManagementService via {@link VcnManager.VcnNetworkPolicyListener}.
  *
  * @hide
  */
+@SystemApi
 public final class VcnNetworkPolicyResult implements Parcelable {
     private final boolean mIsTearDownRequested;
     private final NetworkCapabilities mNetworkCapabilities;
@@ -51,16 +53,19 @@ public final class VcnNetworkPolicyResult implements Parcelable {
     }
 
     /**
-     * Returns whether this Carrier VCN policy policy result requires that the underlying Network
-     * should be torn down.
+     * Returns whether this VCN policy result requires that the underlying Network should be torn
+     * down.
+     *
+     * <p>Upon querying for the current Network policy result, the bearer must check this method,
+     * and MUST tear down the corresponding Network if it returns true.
      */
     public boolean isTeardownRequested() {
         return mIsTearDownRequested;
     }
 
     /**
-     * Returns the NetworkCapabilities with Carrier VCN policy bits applied to the provided
-     * capabilities.
+     * Returns the NetworkCapabilities that the bearer should be using for the corresponding
+     * Network.
      */
     @NonNull
     public NetworkCapabilities getNetworkCapabilities() {