Expose VCN Network policy APIs.

This CL exposes APIs used for a) receiving VCN Network policy updates
and b) applying VCN Network policies to a given Network. Specifically,
these APIs should be used to receive notifications from VcnManager
whenever a VCN Network policy may have changed - generally, following a
VCN starting up, tearing down, or entering Safe Mode.

When a VcnNetworkPolicyListener is notified of a policy change, the
listener should query VcnManager#applyVcnNetworkPolicy to receive the
updated VcnNetworkPolicyResult. This policy result informs the listener
of their resulting NetworkCapabilities and also whether a Network
teardown is required as a consequence of the policy change.

Bug: 177020190
Test: atest FrameworksVcnTests
Change-Id: Ied78a57973a4ceaa7ef4cd9feee64478137497b8

3 files changed, 51 insertions, 10 deletions

diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index f1152da3070e..e492c06867a2 100644
--- a/core/api/system-current.txt
+++ b/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 {
diff --git a/core/java/android/net/vcn/VcnManager.java b/core/java/android/net/vcn/VcnManager.java
index 1c21844abf3d..729e68a6a911 100644
--- a/core/java/android/net/vcn/VcnManager.java
+++ b/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,
diff --git a/core/java/android/net/vcn/VcnNetworkPolicyResult.java b/core/java/android/net/vcn/VcnNetworkPolicyResult.java
index 8d011421cdeb..5e938200639c 100644
--- a/core/java/android/net/vcn/VcnNetworkPolicyResult.java
+++ b/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() {