Docstring Updates for applyTransportModeTransform

-Add anotations to usages of PolicyDirection for
 apply...() methods.
-Update the comments on DIRECTION_IN and DIRECTION_OUT
 to better reflect their current usage.
-Add a better explanation to the rekey procedure doc.
-Remove disused createTunnelInterface() stub.

Bug: 73751066
Test: make docs
Merged-In: I9f2ec864466148a18899f1e952c74a525902ccbc
Change-Id: I9f2ec864466148a18899f1e952c74a525902ccbc
(cherry picked from commit f4cdf25a906d0f52ffd76508d660b843b13b3ff8)

core/java/android/net/IpSecManager.java

@@ -58,14 +58,18 @@ public final class IpSecManager {
     private static final String TAG = "IpSecManager";
 
     /**
-     * For direction-specific attributes of an {@link IpSecTransform}, indicates that an attribute
+     * Used when applying a transform to direct traffic through an {@link IpSecTransform}
-     * applies to traffic towards the host.
+     * towards the host.
+     *
+     * <p>See {@link #applyTransportModeTransform(Socket, int, IpSecTransform)}.
      */
     public static final int DIRECTION_IN = 0;
 
     /**
-     * For direction-specific attributes of an {@link IpSecTransform}, indicates that an attribute
+     * Used when applying a transform to direct traffic through an {@link IpSecTransform}
-     * applies to traffic from the host.
+     * away from the host.
+     *
+     * <p>See {@link #applyTransportModeTransform(Socket, int, IpSecTransform)}.
      */
     public static final int DIRECTION_OUT = 1;
 
@@ -301,19 +305,21 @@ public final class IpSecManager {
      *
      * <h4>Rekey Procedure</h4>
      *
-     * <p>When applying a new tranform to a socket, the previous transform will be removed. However,
+     * <p>When applying a new tranform to a socket in the outbound direction, the previous transform
-     * inbound traffic on the old transform will continue to be decrypted until that transform is
+     * will be removed and the new transform will take effect immediately, sending all traffic on
-     * deallocated by calling {@link IpSecTransform#close()}. This overlap allows rekey procedures
+     * the new transform; however, when applying a transform in the inbound direction, traffic
-     * where both transforms are valid until both endpoints are using the new transform and all
+     * on the old transform will continue to be decrypted and delivered until that transform is
-     * in-flight packets have been received.
+     * deallocated by calling {@link IpSecTransform#close()}. This overlap allows lossless rekey
+     * procedures where both transforms are valid until both endpoints are using the new transform
+     * and all in-flight packets have been received.
      *
      * @param socket a stream socket
-     * @param direction the policy direction either {@link #DIRECTION_IN} or {@link #DIRECTION_OUT}
+     * @param direction the direction in which the transform should be applied
      * @param transform a transport mode {@code IpSecTransform}
      * @throws IOException indicating that the transform could not be applied
      */
     public void applyTransportModeTransform(
-            Socket socket, int direction, IpSecTransform transform)
+            Socket socket, @PolicyDirection int direction, IpSecTransform transform)
             throws IOException {
         applyTransportModeTransform(socket.getFileDescriptor$(), direction, transform);
     }
@@ -334,19 +340,22 @@ public final class IpSecManager {
      *
      * <h4>Rekey Procedure</h4>
      *
-     * <p>When applying a new tranform to a socket, the previous transform will be removed. However,
+     * <p>When applying a new tranform to a socket in the outbound direction, the previous transform
-     * inbound traffic on the old transform will continue to be decrypted until that transform is
+     * will be removed and the new transform will take effect immediately, sending all traffic on
-     * deallocated by calling {@link IpSecTransform#close()}. This overlap allows rekey procedures
+     * the new transform; however, when applying a transform in the inbound direction, traffic
-     * where both transforms are valid until both endpoints are using the new transform and all
+     * on the old transform will continue to be decrypted and delivered until that transform is
-     * in-flight packets have been received.
+     * deallocated by calling {@link IpSecTransform#close()}. This overlap allows lossless rekey
+     * procedures where both transforms are valid until both endpoints are using the new transform
+     * and all in-flight packets have been received.
      *
      * @param socket a datagram socket
-     * @param direction the policy direction either DIRECTION_IN or DIRECTION_OUT
+     * @param direction the direction in which the transform should be applied
      * @param transform a transport mode {@code IpSecTransform}
      * @throws IOException indicating that the transform could not be applied
      */
     public void applyTransportModeTransform(
-            DatagramSocket socket, int direction, IpSecTransform transform) throws IOException {
+            DatagramSocket socket, @PolicyDirection int direction, IpSecTransform transform)
+            throws IOException {
         applyTransportModeTransform(socket.getFileDescriptor$(), direction, transform);
     }
 
@@ -366,19 +375,21 @@ public final class IpSecManager {
      *
      * <h4>Rekey Procedure</h4>
      *
-     * <p>When applying a new tranform to a socket, the previous transform will be removed. However,
+     * <p>When applying a new tranform to a socket in the outbound direction, the previous transform
-     * inbound traffic on the old transform will continue to be decrypted until that transform is
+     * will be removed and the new transform will take effect immediately, sending all traffic on
-     * deallocated by calling {@link IpSecTransform#close()}. This overlap allows rekey procedures
+     * the new transform; however, when applying a transform in the inbound direction, traffic
-     * where both transforms are valid until both endpoints are using the new transform and all
+     * on the old transform will continue to be decrypted and delivered until that transform is
-     * in-flight packets have been received.
+     * deallocated by calling {@link IpSecTransform#close()}. This overlap allows lossless rekey
+     * procedures where both transforms are valid until both endpoints are using the new transform
+     * and all in-flight packets have been received.
      *
      * @param socket a socket file descriptor
-     * @param direction the policy direction either DIRECTION_IN or DIRECTION_OUT
+     * @param direction the direction in which the transform should be applied
      * @param transform a transport mode {@code IpSecTransform}
      * @throws IOException indicating that the transform could not be applied
      */
     public void applyTransportModeTransform(
-            FileDescriptor socket, int direction, IpSecTransform transform)
+            FileDescriptor socket, @PolicyDirection int direction, IpSecTransform transform)
             throws IOException {
         // We dup() the FileDescriptor here because if we don't, then the ParcelFileDescriptor()
         // constructor takes control and closes the user's FD when we exit the method.
@@ -389,21 +400,6 @@ public final class IpSecManager {
         }
     }
 
-    /**
-     * Apply an active Tunnel Mode IPsec Transform to a network, which will tunnel all traffic to
-     * and from that network's interface with IPsec (applies an outer IP header and IPsec Header to
-     * all traffic, and expects an additional IP header and IPsec Header on all inbound traffic).
-     * Applications should probably not use this API directly. Instead, they should use {@link
-     * VpnService} to provide VPN capability in a more generic fashion.
-     *
-     * <p>TODO: Update javadoc for tunnel mode APIs at the same time the APIs are re-worked.
-     *
-     * @param net a {@link Network} that will be tunneled via IP Sec.
-     * @param transform an {@link IpSecTransform}, which must be an active Tunnel Mode transform.
-     * @hide
-     */
-    public void applyTunnelModeTransform(Network net, IpSecTransform transform) {}
-
     /**
      * Remove an IPsec transform from a stream socket.
      *
@@ -770,7 +766,12 @@ public final class IpSecManager {
     }
 
     /**
-     * Apply a transform to the IpSecTunnelInterface
+     * Apply an active Tunnel Mode IPsec Transform to a {@link IpSecTunnelInterface}, which will
+     * tunnel all traffic for the given direction through the underlying network's interface with
+     * IPsec (applies an outer IP header and IPsec Header to all traffic, and expects an additional
+     * IP header and IPsec Header on all inbound traffic).
+     * <p>Applications should probably not use this API directly.
+     *
      *
      * @param tunnel The {@link IpSecManager#IpSecTunnelInterface} that will use the supplied
      *        transform.
@@ -783,8 +784,8 @@ public final class IpSecManager {
      */
     @SystemApi
     @RequiresPermission(android.Manifest.permission.NETWORK_STACK)
-    public void applyTunnelModeTransform(IpSecTunnelInterface tunnel, int direction,
+    public void applyTunnelModeTransform(IpSecTunnelInterface tunnel,
-            IpSecTransform transform) throws IOException {
+            @PolicyDirection int direction, IpSecTransform transform) throws IOException {
         try {
             mService.applyTunnelModeTransform(
                     tunnel.getResourceId(), direction, transform.getResourceId());
@@ -792,6 +793,7 @@ public final class IpSecManager {
             throw e.rethrowFromSystemServer();
         }
     }
+
     /**
      * Construct an instance of IpSecManager within an application context.
      *