Merge "[AWARE] Update network API: make open/encrypted explicit"

8 files changed, 56 insertions, 91 deletions

diff --git a/api/current.txt b/api/current.txt
index b69cf01fb8ba..b5a99caa1513 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -25157,7 +25157,8 @@ package android.net.wifi.aware {
   }
 
   public class DiscoverySession {
-    method public java.lang.String createNetworkSpecifier(android.net.wifi.aware.PeerHandle, byte[]);
+    method public java.lang.String createNetworkSpecifierOpen(android.net.wifi.aware.PeerHandle);
+    method public java.lang.String createNetworkSpecifierPassphrase(android.net.wifi.aware.PeerHandle, java.lang.String);
     method public void destroy();
     method public void sendMessage(android.net.wifi.aware.PeerHandle, int, byte[]);
   }
@@ -25245,7 +25246,8 @@ package android.net.wifi.aware {
   }
 
   public class WifiAwareSession {
-    method public java.lang.String createNetworkSpecifier(int, byte[], byte[]);
+    method public java.lang.String createNetworkSpecifierOpen(int, byte[]);
+    method public java.lang.String createNetworkSpecifierPassphrase(int, byte[], java.lang.String);
     method public void destroy();
     method public void publish(android.net.wifi.aware.PublishConfig, android.net.wifi.aware.DiscoverySessionCallback, android.os.Handler);
     method public void subscribe(android.net.wifi.aware.SubscribeConfig, android.net.wifi.aware.DiscoverySessionCallback, android.os.Handler);
diff --git a/api/system-current.txt b/api/system-current.txt
index 914cda1a68d4..c2338d8327d6 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -27715,7 +27715,9 @@ package android.net.wifi.aware {
   }
 
   public class DiscoverySession {
-    method public java.lang.String createNetworkSpecifier(android.net.wifi.aware.PeerHandle, byte[]);
+    method public java.lang.String createNetworkSpecifierOpen(android.net.wifi.aware.PeerHandle);
+    method public java.lang.String createNetworkSpecifierPassphrase(android.net.wifi.aware.PeerHandle, java.lang.String);
+    method public java.lang.String createNetworkSpecifierPmk(android.net.wifi.aware.PeerHandle, byte[]);
     method public void destroy();
     method public void sendMessage(android.net.wifi.aware.PeerHandle, int, byte[]);
   }
@@ -27803,7 +27805,9 @@ package android.net.wifi.aware {
   }
 
   public class WifiAwareSession {
-    method public java.lang.String createNetworkSpecifier(int, byte[], byte[]);
+    method public java.lang.String createNetworkSpecifierOpen(int, byte[]);
+    method public java.lang.String createNetworkSpecifierPassphrase(int, byte[], java.lang.String);
+    method public java.lang.String createNetworkSpecifierPmk(int, byte[], byte[]);
     method public void destroy();
     method public void publish(android.net.wifi.aware.PublishConfig, android.net.wifi.aware.DiscoverySessionCallback, android.os.Handler);
     method public void subscribe(android.net.wifi.aware.SubscribeConfig, android.net.wifi.aware.DiscoverySessionCallback, android.os.Handler);
diff --git a/api/test-current.txt b/api/test-current.txt
index 317328d6e57d..bc0b5b0643a8 100644
--- a/api/test-current.txt
+++ b/api/test-current.txt
@@ -25230,7 +25230,8 @@ package android.net.wifi.aware {
   }
 
   public class DiscoverySession {
-    method public java.lang.String createNetworkSpecifier(android.net.wifi.aware.PeerHandle, byte[]);
+    method public java.lang.String createNetworkSpecifierOpen(android.net.wifi.aware.PeerHandle);
+    method public java.lang.String createNetworkSpecifierPassphrase(android.net.wifi.aware.PeerHandle, java.lang.String);
     method public void destroy();
     method public void sendMessage(android.net.wifi.aware.PeerHandle, int, byte[]);
   }
@@ -25318,7 +25319,8 @@ package android.net.wifi.aware {
   }
 
   public class WifiAwareSession {
-    method public java.lang.String createNetworkSpecifier(int, byte[], byte[]);
+    method public java.lang.String createNetworkSpecifierOpen(int, byte[]);
+    method public java.lang.String createNetworkSpecifierPassphrase(int, byte[], java.lang.String);
     method public void destroy();
     method public void publish(android.net.wifi.aware.PublishConfig, android.net.wifi.aware.DiscoverySessionCallback, android.os.Handler);
     method public void subscribe(android.net.wifi.aware.SubscribeConfig, android.net.wifi.aware.DiscoverySessionCallback, android.os.Handler);
diff --git a/wifi/java/android/net/wifi/aware/DiscoverySession.java b/wifi/java/android/net/wifi/aware/DiscoverySession.java
index 156c3fdf336c..82b3792a331c 100644
--- a/wifi/java/android/net/wifi/aware/DiscoverySession.java
+++ b/wifi/java/android/net/wifi/aware/DiscoverySession.java
@@ -18,6 +18,7 @@ package android.net.wifi.aware;
 
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.annotation.SystemApi;
 import android.net.wifi.RttManager;
 import android.util.Log;
 
@@ -33,7 +34,8 @@ import java.lang.ref.WeakReference;
  * <ul>
  *     <li>Sending messages: {@link #sendMessage(PeerHandle, int, byte[])} method.
  *     <li>Creating a network-specifier when requesting a Aware connection:
- *     {@link #createNetworkSpecifier(PeerHandle, byte[])}.
+ *     {@link #createNetworkSpecifierOpen(PeerHandle)} or
+ *     {@link #createNetworkSpecifierPassphrase(PeerHandle, String)}.
  * </ul>
  * The {@link #destroy()} method must be called to destroy discovery sessions once they are
  * no longer needed.
@@ -255,7 +257,7 @@ public class DiscoverySession {
      * <p>
      * This method should be used when setting up a connection with a peer discovered through Aware
      * discovery or communication (in such scenarios the MAC address of the peer is shielded by
-     * an opaque peer ID handle). If a Aware connection is needed to a peer discovered using other
+     * an opaque peer ID handle). If an Aware connection is needed to a peer discovered using other
      * OOB (out-of-band) mechanism then use the alternative
      * {@link WifiAwareSession#createNetworkSpecifierOpen(int, byte[])} method - which uses the
      * peer's MAC address.
@@ -263,24 +265,22 @@ public class DiscoverySession {
      * Note: per the Wi-Fi Aware specification the roles are fixed - a Subscriber is an INITIATOR
      * and a Publisher is a RESPONDER.
      * <p>
-     * To set up an encrypted link use the {@link #createNetworkSpecifierPmk(PeerHandle, byte[])}
-     * or {@link #createNetworkSpecifierPassphrase(PeerHandle, String)} APIs.
+     * To set up an encrypted link use the
+     * {@link #createNetworkSpecifierPassphrase(PeerHandle, String)} API.
      *
      * @param peerHandle The peer's handle obtained through
      * {@link DiscoverySessionCallback#onServiceDiscovered(PeerHandle, byte[], java.util.List)}
      *                   or
      *                   {@link DiscoverySessionCallback#onMessageReceived(PeerHandle, byte[])}.
      *                   On a RESPONDER this value is used to gate the acceptance of a connection
-     *                   request from only that peer. A RESPONDER may specify a null - indicating
-     *                   that it will accept connection requests from any device.
+     *                   request from only that peer. A RESPONDER may specify a {@code null} -
+     *                   indicating that it will accept connection requests from any device.
      *
      * @return A string to be used to construct
      * {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} to pass to
      * {@link android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest,
      * android.net.ConnectivityManager.NetworkCallback)}
      * [or other varieties of that API].
-     *
-     * @hide
      */
     public String createNetworkSpecifierOpen(@Nullable PeerHandle peerHandle) {
         if (mTerminated) {
@@ -309,7 +309,7 @@ public class DiscoverySession {
      * <p>
      * This method should be used when setting up a connection with a peer discovered through Aware
      * discovery or communication (in such scenarios the MAC address of the peer is shielded by
-     * an opaque peer ID handle). If a Aware connection is needed to a peer discovered using other
+     * an opaque peer ID handle). If an Aware connection is needed to a peer discovered using other
      * OOB (out-of-band) mechanism then use the alternative
      * {@link WifiAwareSession#createNetworkSpecifierPassphrase(int, byte[], String)} method -
      * which uses the peer's MAC address.
@@ -322,12 +322,11 @@ public class DiscoverySession {
      * byte[], java.util.List)} or
      * {@link DiscoverySessionCallback#onMessageReceived(PeerHandle,
      * byte[])}. On a RESPONDER this value is used to gate the acceptance of a connection request
-     *                   from only that peer. A RESPONDER may specify a null - indicating that
-     *                   it will accept connection requests from any device.
+     *                   from only that peer. A RESPONDER may specify a {@code null} - indicating
+     *                   that it will accept connection requests from any device.
      * @param passphrase The passphrase to be used to encrypt the link. The PMK is generated from
      *                   the passphrase. Use the
-     *                   {@link #createNetworkSpecifierPmk(PeerHandle, byte[])} to specify the
-     *                   PMK directly or {@link #createNetworkSpecifierOpen(PeerHandle)} to
+     *                   {@link #createNetworkSpecifierOpen(PeerHandle)} API to
      *                   specify an open (unencrypted) link.
      *
      * @return A string to be used to construct
@@ -335,8 +334,6 @@ public class DiscoverySession {
      * {@link android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest,
      * android.net.ConnectivityManager.NetworkCallback)}
      * [or other varieties of that API].
-     *
-     * * @hide
      */
     public String createNetworkSpecifierPassphrase(@Nullable PeerHandle peerHandle,
             @NonNull String passphrase) {
@@ -371,7 +368,7 @@ public class DiscoverySession {
      * <p>
      * This method should be used when setting up a connection with a peer discovered through Aware
      * discovery or communication (in such scenarios the MAC address of the peer is shielded by
-     * an opaque peer ID handle). If a Aware connection is needed to a peer discovered using other
+     * an opaque peer ID handle). If an Aware connection is needed to a peer discovered using other
      * OOB (out-of-band) mechanism then use the alternative
      * {@link WifiAwareSession#createNetworkSpecifierPmk(int, byte[], byte[])} method - which uses
      * the peer's MAC address.
@@ -400,6 +397,7 @@ public class DiscoverySession {
      *
      * @hide
      */
+    @SystemApi
     public String createNetworkSpecifierPmk(@Nullable PeerHandle peerHandle,
             @NonNull byte[] pmk) {
         if (pmk == null || pmk.length == 0) {
@@ -423,27 +421,4 @@ public class DiscoverySession {
 
         return mgr.createNetworkSpecifier(mClientId, role, mSessionId, peerHandle, pmk, null);
     }
-
-    /**
-     * Place-holder for {@code createNetworkSpecifierOpen(PeerHandle)}. Present to enable
-     * development of replacements CL without causing an API change. Will be removed when new
-     * APIs are exposed.
-     *
-     * @param peerHandle The peer's handle obtained through
-     * {@link DiscoverySessionCallback#onServiceDiscovered(PeerHandle,
-     * byte[], java.util.List)} or
-     * {@link DiscoverySessionCallback#onMessageReceived(PeerHandle,
-     * byte[])}. On a RESPONDER this value is used to gate the acceptance of a connection request
-     *                   from only that peer. A RESPONDER may specify a null - indicating that
-     *                   it will accept connection requests from any device.
-     * @param token Deprecated and ignored.
-     * @return A string to be used to construct
-     * {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} to pass to
-     * {@link android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest,
-     * android.net.ConnectivityManager.NetworkCallback)}
-     * [or other varieties of that API].
-     */
-    public String createNetworkSpecifier(@Nullable PeerHandle peerHandle, @Nullable byte[] token) {
-        return createNetworkSpecifierOpen(peerHandle);
-    }
 }
diff --git a/wifi/java/android/net/wifi/aware/IdentityChangedListener.java b/wifi/java/android/net/wifi/aware/IdentityChangedListener.java
index cae8706933dc..81a06e825439 100644
--- a/wifi/java/android/net/wifi/aware/IdentityChangedListener.java
+++ b/wifi/java/android/net/wifi/aware/IdentityChangedListener.java
@@ -24,7 +24,8 @@ package android.net.wifi.aware;
  * your identity - e.g. by starting a discovery session. This actual MAC address of the
  * interface may also be useful if the application uses alternative (non-Aware) discovery but needs
  * to set up a Aware connection. The provided Aware discovery interface MAC address can then be used
- * in {@link WifiAwareSession#createNetworkSpecifier(int, byte[], byte[])}.
+ * in {@link WifiAwareSession#createNetworkSpecifierOpen(int, byte[])} or
+ * {@link WifiAwareSession#createNetworkSpecifierPassphrase(int, byte[], String)}.
  */
 public class IdentityChangedListener {
     /**
diff --git a/wifi/java/android/net/wifi/aware/PeerHandle.java b/wifi/java/android/net/wifi/aware/PeerHandle.java
index bbe9f5451713..cd45c524934a 100644
--- a/wifi/java/android/net/wifi/aware/PeerHandle.java
+++ b/wifi/java/android/net/wifi/aware/PeerHandle.java
@@ -19,9 +19,10 @@ package android.net.wifi.aware;
 /**
  * Opaque object used to represent a Wi-Fi Aware peer. Obtained from discovery sessions in
  * {@link DiscoverySessionCallback#onServiceDiscovered(PeerHandle, byte[], java.util.List)}, used
- * when sending messages e,g, {@link PublishDiscoverySession#sendMessage(PeerHandle, int, byte[])},
+ * when sending messages e,g, {@link DiscoverySession#sendMessage(PeerHandle, int, byte[])},
  * or when configuring a network link to a peer, e.g.
- * {@link PublishDiscoverySession#createNetworkSpecifier(PeerHandle, byte[])}.
+ * {@link DiscoverySession#createNetworkSpecifierOpen(PeerHandle)} or
+ * {@link DiscoverySession#createNetworkSpecifierPassphrase(PeerHandle, String)}.
  */
 public class PeerHandle {
     /** @hide */
diff --git a/wifi/java/android/net/wifi/aware/WifiAwareManager.java b/wifi/java/android/net/wifi/aware/WifiAwareManager.java
index 7b6805c3da92..4d3957aece91 100644
--- a/wifi/java/android/net/wifi/aware/WifiAwareManager.java
+++ b/wifi/java/android/net/wifi/aware/WifiAwareManager.java
@@ -65,8 +65,10 @@ import java.util.List;
  * <li>Create a Aware network specifier to be used with
  * {@link ConnectivityManager#requestNetwork(NetworkRequest, ConnectivityManager.NetworkCallback)}
  * to set-up a Aware connection with a peer. Refer to
- * {@link DiscoverySession#createNetworkSpecifier(PeerHandle, byte[])} and
- * {@link WifiAwareSession#createNetworkSpecifier(int, byte[], byte[])}.
+ * {@link DiscoverySession#createNetworkSpecifierOpen(PeerHandle)},
+ * {@link DiscoverySession#createNetworkSpecifierPassphrase(PeerHandle, String)},
+ * {@link WifiAwareSession#createNetworkSpecifierOpen(int, byte[])}, and
+ * {@link WifiAwareSession#createNetworkSpecifierPassphrase(int, byte[], String)}.
  * </ul>
  * <p>
  *     Aware may not be usable when Wi-Fi is disabled (and other conditions). To validate that
@@ -115,8 +117,10 @@ import java.util.List;
  *        <li>{@link NetworkRequest.Builder#addTransportType(int)} of
  *        {@link android.net.NetworkCapabilities#TRANSPORT_WIFI_AWARE}.
  *        <li>{@link NetworkRequest.Builder#setNetworkSpecifier(String)} using
- *        {@link WifiAwareSession#createNetworkSpecifier(int, byte[], byte[])} or
- *        {@link DiscoverySession#createNetworkSpecifier(PeerHandle, byte[])}.
+ *        {@link WifiAwareSession#createNetworkSpecifierOpen(int, byte[])},
+ *        {@link WifiAwareSession#createNetworkSpecifierPassphrase(int, byte[], String)},
+ *        {@link DiscoverySession#createNetworkSpecifierOpen(PeerHandle)}, or
+ *        {@link DiscoverySession#createNetworkSpecifierPassphrase(PeerHandle, String)}.
  *    </ul>
  */
 public class WifiAwareManager {
@@ -206,8 +210,10 @@ public class WifiAwareManager {
      * Connection creation role is that of INITIATOR. Used to create a network specifier string
      * when requesting a Aware network.
      *
-     * @see DiscoverySession#createNetworkSpecifier(PeerHandle, byte[])
-     * @see WifiAwareSession#createNetworkSpecifier(int, byte[], byte[])
+     * @see DiscoverySession#createNetworkSpecifierOpen(PeerHandle)
+     * @see DiscoverySession#createNetworkSpecifierPassphrase(PeerHandle, String)
+     * @see WifiAwareSession#createNetworkSpecifierOpen(int, byte[])
+     * @see WifiAwareSession#createNetworkSpecifierPassphrase(int, byte[], String)
      */
     public static final int WIFI_AWARE_DATA_PATH_ROLE_INITIATOR = 0;
 
@@ -215,8 +221,10 @@ public class WifiAwareManager {
      * Connection creation role is that of RESPONDER. Used to create a network specifier string
      * when requesting a Aware network.
      *
-     * @see DiscoverySession#createNetworkSpecifier(PeerHandle, byte[])
-     * @see WifiAwareSession#createNetworkSpecifier(int, byte[], byte[])
+     * @see DiscoverySession#createNetworkSpecifierOpen(PeerHandle)
+     * @see DiscoverySession#createNetworkSpecifierPassphrase(PeerHandle, String)
+     * @see WifiAwareSession#createNetworkSpecifierOpen(int, byte[])
+     * @see WifiAwareSession#createNetworkSpecifierPassphrase(int, byte[], String)
      */
     public static final int WIFI_AWARE_DATA_PATH_ROLE_RESPONDER = 1;
 
diff --git a/wifi/java/android/net/wifi/aware/WifiAwareSession.java b/wifi/java/android/net/wifi/aware/WifiAwareSession.java
index f48f64184bfb..895defb9a540 100644
--- a/wifi/java/android/net/wifi/aware/WifiAwareSession.java
+++ b/wifi/java/android/net/wifi/aware/WifiAwareSession.java
@@ -18,6 +18,7 @@ package android.net.wifi.aware;
 
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.annotation.SystemApi;
 import android.os.Binder;
 import android.os.Handler;
 import android.os.Looper;
@@ -193,15 +194,15 @@ public class WifiAwareSession {
      *     when using Aware discovery use the alternative network specifier method -
      *     {@link DiscoverySession#createNetworkSpecifierOpen(PeerHandle)}.
      * <p>
-     * To set up an encrypted link use the {@link #createNetworkSpecifierPmk(int, byte[], byte[])}
-     * or {@link #createNetworkSpecifierPassphrase(int, byte[], String)} APIs.
+     * To set up an encrypted link use the
+     * {@link #createNetworkSpecifierPassphrase(int, byte[], String)} API.
      *
      * @param role  The role of this device:
      *              {@link WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_INITIATOR} or
      *              {@link WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_RESPONDER}
      * @param peer  The MAC address of the peer's Aware discovery interface. On a RESPONDER this
      *              value is used to gate the acceptance of a connection request from only that
-     *              peer. A RESPONDER may specify a null - indicating that it will accept
+     *              peer. A RESPONDER may specify a {@code null} - indicating that it will accept
      *              connection requests from any device.
      *
      * @return A string to be used to construct
@@ -209,8 +210,6 @@ public class WifiAwareSession {
      * {@link android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest,
      * android.net.ConnectivityManager.NetworkCallback)}
      * [or other varieties of that API].
-     *
-     * @hide
      */
     public String createNetworkSpecifierOpen(@WifiAwareManager.DataPathRole int role,
             @Nullable byte[] peer) {
@@ -242,12 +241,10 @@ public class WifiAwareSession {
      *              {@link WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_RESPONDER}
      * @param peer  The MAC address of the peer's Aware discovery interface. On a RESPONDER this
      *              value is used to gate the acceptance of a connection request from only that
-     *              peer. A RESPONDER may specify a null - indicating that it will accept
+     *              peer. A RESPONDER may specify a {@code null} - indicating that it will accept
      *              connection requests from any device.
      * @param passphrase The passphrase to be used to encrypt the link. The PMK is generated from
-     *                   the passphrase. Use the
-     *                   {@link #createNetworkSpecifierPmk(int, byte[], byte[])} to specify the
-     *                   PMK directly or {@link #createNetworkSpecifierOpen(int, byte[])} to
+     *                   the passphrase. Use {@link #createNetworkSpecifierOpen(int, byte[])} to
      *                   specify an open (unencrypted) link.
      *
      * @return A string to be used to construct
@@ -255,8 +252,6 @@ public class WifiAwareSession {
      * {@link android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest,
      * android.net.ConnectivityManager.NetworkCallback)}
      * [or other varieties of that API].
-     *
-     * @hide
      */
     public String createNetworkSpecifierPassphrase(@WifiAwareManager.DataPathRole int role,
             @Nullable byte[] peer, @NonNull String passphrase) {
@@ -307,6 +302,7 @@ public class WifiAwareSession {
      *
      * @hide
      */
+    @SystemApi
     public String createNetworkSpecifierPmk(@WifiAwareManager.DataPathRole int role,
             @Nullable byte[] peer, @NonNull byte[] pmk) {
         WifiAwareManager mgr = mMgr.get();
@@ -323,28 +319,4 @@ public class WifiAwareSession {
         }
         return mgr.createNetworkSpecifier(mClientId, role, peer, pmk, null);
     }
-
-    /**
-     * Place-holder for {@code #createNetworkSpecifierOpen(int, byte[])}. Present to enable
-     * development of replacements CL without causing an API change. Will be removed when new
-     * APIs are exposed.
-     *
-     * @param role  The role of this device:
-     *              {@link WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_INITIATOR} or
-     *              {@link WifiAwareManager#WIFI_AWARE_DATA_PATH_ROLE_RESPONDER}
-     * @param peer  The MAC address of the peer's Aware discovery interface. On a RESPONDER this
-     *              value is used to gate the acceptance of a connection request from only that
-     *              peer. A RESPONDER may specify a null - indicating that it will accept
-     *              connection requests from any device.
-     * @param token Deprecated and ignored.
-     * @return A string to be used to construct
-     * {@link android.net.NetworkRequest.Builder#setNetworkSpecifier(String)} to pass to
-     * {@link android.net.ConnectivityManager#requestNetwork(android.net.NetworkRequest,
-     * android.net.ConnectivityManager.NetworkCallback)}
-     * [or other varieties of that API].
-     */
-    public String createNetworkSpecifier(@WifiAwareManager.DataPathRole int role,
-            @Nullable byte[] peer, @Nullable byte[] token) {
-        return createNetworkSpecifierOpen(role, peer);
-    }
 }