Address API review comments

Added a flags field in ScanResult; along with flag
values and methods to read them.

Changed types of passpoint related fields.

Bug: 21342042
Bug: 21572290
Bug: 21343777

Change-Id: I413960de88b387853d11b9e10f92665e9c06a81b

4 files changed, 99 insertions, 62 deletions

diff --git a/wifi/java/android/net/wifi/ScanResult.java b/wifi/java/android/net/wifi/ScanResult.java
index 5dc70bd..fc6a3de 100644
--- a/wifi/java/android/net/wifi/ScanResult.java
+++ b/wifi/java/android/net/wifi/ScanResult.java
@@ -18,6 +18,7 @@ package android.net.wifi;
 
 import android.os.Parcel;
 import android.os.Parcelable;
+import android.util.Log;
 
 /**
  * Describes information about a detected access point. In addition
@@ -80,27 +81,30 @@ public class ScanResult implements Parcelable {
     public static final int CHANNEL_WIDTH_80MHZ_PLUS_MHZ = 4;
 
    /**
-    * AP Channel bandwidth
+    * AP Channel bandwidth; one of {@link #CHANNEL_WIDTH_20MHZ}, {@link #CHANNEL_WIDTH_40MHZ},
+    * {@link #CHANNEL_WIDTH_80MHZ}, {@link #CHANNEL_WIDTH_160MHZ}
+    * or {@link #CHANNEL_WIDTH_80MHZ_PLUS_MHZ}.
     */
     public int channelWidth;
 
     /**
      * Not used if the AP bandwidth is 20 MHz
-     * If the AP use 40, 80 or 160 MHz, this is the center frequency
-     * if the AP use 80 + 80 MHz, this is the center frequency of the first segment
+     * If the AP use 40, 80 or 160 MHz, this is the center frequency (in MHz)
+     * if the AP use 80 + 80 MHz, this is the center frequency of the first segment (in MHz)
      */
     public int centerFreq0;
 
     /**
      * Only used if the AP bandwidth is 80 + 80 MHz
-     * if the AP use 80 + 80 MHz, this is the center frequency of the second segment
+     * if the AP use 80 + 80 MHz, this is the center frequency of the second segment (in MHz)
      */
     public int centerFreq1;
 
     /**
-     * Whether the AP support 802.11mc Responder
+     * @deprecated use is80211mcResponder() instead
+     * @hide
      */
-   public boolean is80211McRTTResponder;
+    public boolean is80211McRTTResponder;
 
     /**
      * timestamp in microseconds (since boot) when
@@ -123,7 +127,7 @@ public class ScanResult implements Parcelable {
     /**
      * @hide
      * Update RSSI of the scan result
-     * @param previousRSSI
+     * @param previousRssi
      * @param previousSeen
      * @param maxAge
      */
@@ -206,26 +210,56 @@ public class ScanResult implements Parcelable {
     public int distanceCm;
 
     /**
-     * The standard deviation of the distance to the AP, if available.
+     * The standard deviation of the distance to the access point, if available.
      * Else {@link UNSPECIFIED}.
      * {@hide}
      */
     public int distanceSdCm;
 
+    public static final long FLAG_PASSPOINT_NETWORK               = 0x0000000000000001;
+    public static final long FLAG_80211mc_RESPONDER               = 0x0000000000000002;
+
     /**
-     * Indicates if the scan result represents a passpoint AP
+     * Defines flags; such as {@link #FLAG_PASSPOINT_NETWORK}.
      */
-    public boolean passpointNetwork;
+    public long flags;
 
     /**
-     * Indicates if venue name
+     * sets a flag in {@link #flags} field
+     * @param flag flag to set
+     * @hide
      */
-    public String venueName;
+    public void setFlag(long flag) {
+        flags |= flag;
+    }
 
     /**
-     * Indicates operator name
+     * clears a flag in {@link #flags} field
+     * @param flag flag to set
+     * @hide
      */
-    public String operatorFriendlyName;
+    public void clearFlag(long flag) {
+        flags &= ~flag;
+    }
+
+    public boolean is80211mcResponder() {
+        return (flags & FLAG_80211mc_RESPONDER) != 0;
+    }
+
+    public boolean isPasspointNetwork() {
+        return (flags & FLAG_PASSPOINT_NETWORK) != 0;
+    }
+
+    /**
+     * Indicates venue name (such as 'San Francisco Airport') published by access point; only
+     * available on passpoint network and if published by access point.
+     */
+    public CharSequence venueName;
+
+    /**
+     * Indicates passpoint operator name published by access point.
+     */
+    public CharSequence operatorFriendlyName;
 
     /**
      * {@hide}
@@ -267,7 +301,7 @@ public class ScanResult implements Parcelable {
      **/
     public byte[] bytes;
 
-    /** information element from beacon
+    /** information elements from beacon
      * @hide
      */
     public static class InformationElement {
@@ -303,8 +337,7 @@ public class ScanResult implements Parcelable {
         this.channelWidth = UNSPECIFIED;
         this.centerFreq0 = UNSPECIFIED;
         this.centerFreq1 = UNSPECIFIED;
-        this.is80211McRTTResponder = false;
-        this.passpointNetwork = false;
+        this.flags = 0;
     }
 
     /** {@hide} */
@@ -322,8 +355,7 @@ public class ScanResult implements Parcelable {
         this.channelWidth = UNSPECIFIED;
         this.centerFreq0 = UNSPECIFIED;
         this.centerFreq1 = UNSPECIFIED;
-        this.is80211McRTTResponder = false;
-        this.passpointNetwork = false;
+        this.flags = 0;
     }
 
     /** {@hide} */
@@ -342,8 +374,11 @@ public class ScanResult implements Parcelable {
         this.channelWidth = channelWidth;
         this.centerFreq0 = centerFreq0;
         this.centerFreq1 = centerFreq1;
-        this.is80211McRTTResponder = is80211McRTTResponder;
-        this.passpointNetwork = false;
+        if (is80211McRTTResponder) {
+            this.flags = FLAG_80211mc_RESPONDER;
+        } else {
+            this.flags = 0;
+        }
     }
 
     /** copy constructor {@hide} */
@@ -358,7 +393,6 @@ public class ScanResult implements Parcelable {
             channelWidth = source.channelWidth;
             centerFreq0 = source.centerFreq0;
             centerFreq1 = source.centerFreq1;
-            is80211McRTTResponder = source.is80211McRTTResponder;
             timestamp = source.timestamp;
             distanceCm = source.distanceCm;
             distanceSdCm = source.distanceSdCm;
@@ -369,9 +403,9 @@ public class ScanResult implements Parcelable {
             numUsage = source.numUsage;
             numIpConfigFailures = source.numIpConfigFailures;
             isAutoJoinCandidate = source.isAutoJoinCandidate;
-            passpointNetwork = source.passpointNetwork;
             venueName = source.venueName;
             operatorFriendlyName = source.operatorFriendlyName;
+            flags = source.flags;
         }
     }
 
@@ -405,15 +439,16 @@ public class ScanResult implements Parcelable {
         sb.append(", distanceSd: ").append((distanceSdCm != UNSPECIFIED ? distanceSdCm : "?")).
                 append("(cm)");
 
-        sb.append(", passpoint: ").append(passpointNetwork ? "yes" : "no");
+        sb.append(", passpoint: ");
+        sb.append(((flags & FLAG_PASSPOINT_NETWORK) != 0) ? "yes" : "no");
         if (autoJoinStatus != 0) {
             sb.append(", status: ").append(autoJoinStatus);
         }
         sb.append(", ChannelBandwidth: ").append(channelWidth);
         sb.append(", centerFreq0: ").append(centerFreq0);
         sb.append(", centerFreq1: ").append(centerFreq1);
-        sb.append(", 80211mcResponder: ").append(is80211McRTTResponder?
-                "is supported":"is not supported");
+        sb.append(", 80211mcResponder: ");
+        sb.append(((flags & FLAG_80211mc_RESPONDER) != 0) ? "is supported" : "is not supported");
         return sb.toString();
     }
 
@@ -440,7 +475,6 @@ public class ScanResult implements Parcelable {
         dest.writeInt(channelWidth);
         dest.writeInt(centerFreq0);
         dest.writeInt(centerFreq1);
-        dest.writeInt(is80211McRTTResponder ? 1 : 0);
         dest.writeLong(seen);
         dest.writeInt(autoJoinStatus);
         dest.writeInt(untrusted ? 1 : 0);
@@ -448,9 +482,9 @@ public class ScanResult implements Parcelable {
         dest.writeInt(numUsage);
         dest.writeInt(numIpConfigFailures);
         dest.writeInt(isAutoJoinCandidate);
-        dest.writeInt(passpointNetwork ? 1 : 0);
-        dest.writeString(venueName);
-        dest.writeString(operatorFriendlyName);
+        dest.writeString((venueName != null) ? venueName.toString() : "");
+        dest.writeString((operatorFriendlyName != null) ? operatorFriendlyName.toString() : "");
+        dest.writeLong(this.flags);
 
         if (informationElements != null) {
             dest.writeInt(informationElements.length);
@@ -474,18 +508,19 @@ public class ScanResult implements Parcelable {
                 }
                 ScanResult sr = new ScanResult(
                     wifiSsid,
-                    in.readString(),
-                    in.readString(),
-                    in.readInt(),
-                    in.readInt(),
-                    in.readLong(),
-                    in.readInt(),
-                    in.readInt(),
-                    in.readInt(),
-                    in.readInt(),
-                    in.readInt(),
-                    in.readInt() == 1
+                    in.readString(),                    /* BSSID */
+                    in.readString(),                    /* capabilities */
+                    in.readInt(),                       /* level */
+                    in.readInt(),                       /* frequency */
+                    in.readLong(),                      /* timestamp */
+                    in.readInt(),                       /* distanceCm */
+                    in.readInt(),                       /* distanceSdCm */
+                    in.readInt(),                       /* channelWidth */
+                    in.readInt(),                       /* centerFreq0 */
+                    in.readInt(),                       /* centerFreq1 */
+                    false                               /* rtt responder, fixed with flags below */
                 );
+
                 sr.seen = in.readLong();
                 sr.autoJoinStatus = in.readInt();
                 sr.untrusted = in.readInt() != 0;
@@ -493,9 +528,9 @@ public class ScanResult implements Parcelable {
                 sr.numUsage = in.readInt();
                 sr.numIpConfigFailures = in.readInt();
                 sr.isAutoJoinCandidate = in.readInt();
-                sr.passpointNetwork = in.readInt() == 1;
                 sr.venueName = in.readString();
                 sr.operatorFriendlyName = in.readString();
+                sr.flags = in.readLong();
                 int n = in.readInt();
                 if (n != 0) {
                     sr.informationElements = new InformationElement[n];
diff --git a/wifi/java/android/net/wifi/WifiConfiguration.java b/wifi/java/android/net/wifi/WifiConfiguration.java
index 5d55ec6..5d834f6 100644
--- a/wifi/java/android/net/wifi/WifiConfiguration.java
+++ b/wifi/java/android/net/wifi/WifiConfiguration.java
@@ -344,14 +344,15 @@ public class WifiConfiguration implements Parcelable {
     public String FQDN;
 
     /**
-     * Service provider name, for Passpoint credential.
+     * Name of passpoint credential provider
      */
     public String providerFriendlyName;
 
     /**
-     * Roaming Consortium Id, for Passpoint credential.
+     * Roaming Consortium Id list for passpoint credential; identifies a set of networks where
+     * passpoint credential will be considered valid
      */
-    public HashSet<Long> roamingConsortiumIds;
+    public Long[] roamingConsortiumIds;
 
     /**
      * @hide
@@ -906,7 +907,7 @@ public class WifiConfiguration implements Parcelable {
         SSID = null;
         BSSID = null;
         FQDN = null;
-        roamingConsortiumIds = new HashSet<Long>();
+        roamingConsortiumIds = new Long[0];
         priority = 0;
         hiddenSSID = false;
         disableReason = DISABLED_UNKNOWN_REASON;
@@ -1437,11 +1438,7 @@ public class WifiConfiguration implements Parcelable {
             SSID = source.SSID;
             BSSID = source.BSSID;
             FQDN = source.FQDN;
-            roamingConsortiumIds = new HashSet<Long>();
-            for (Long roamingConsortiumId : source.roamingConsortiumIds) {
-                roamingConsortiumIds.add(roamingConsortiumId);
-            }
-
+            roamingConsortiumIds = source.roamingConsortiumIds.clone();
             providerFriendlyName = source.providerFriendlyName;
             preSharedKey = source.preSharedKey;
 
@@ -1546,7 +1543,7 @@ public class WifiConfiguration implements Parcelable {
         dest.writeString(autoJoinBSSID);
         dest.writeString(FQDN);
         dest.writeString(providerFriendlyName);
-        dest.writeInt(roamingConsortiumIds.size());
+        dest.writeInt(roamingConsortiumIds.length);
         for (Long roamingConsortiumId : roamingConsortiumIds) {
             dest.writeLong(roamingConsortiumId);
         }
@@ -1622,8 +1619,9 @@ public class WifiConfiguration implements Parcelable {
                 config.FQDN = in.readString();
                 config.providerFriendlyName = in.readString();
                 int numRoamingConsortiumIds = in.readInt();
+                config.roamingConsortiumIds = new Long[numRoamingConsortiumIds];
                 for (int i = 0; i < numRoamingConsortiumIds; i++) {
-                    config.roamingConsortiumIds.add(in.readLong());
+                    config.roamingConsortiumIds[i] = in.readLong();
                 }
                 config.preSharedKey = in.readString();
                 for (int i = 0; i < config.wepKeys.length; i++) {
diff --git a/wifi/java/android/net/wifi/WifiEnterpriseConfig.java b/wifi/java/android/net/wifi/WifiEnterpriseConfig.java
index 3525ec2..e611ea4 100644
--- a/wifi/java/android/net/wifi/WifiEnterpriseConfig.java
+++ b/wifi/java/android/net/wifi/WifiEnterpriseConfig.java
@@ -604,12 +604,13 @@ public class WifiEnterpriseConfig implements Parcelable {
      * Get the domain_suffix_match value. See setDomSuffixMatch.
      * @return The domain value.
      */
-    public String getDomainSubjectMatch() {
+    public String getDomainSuffixMatch() {
         return getFieldValue(DOM_SUFFIX_MATCH_KEY, "");
     }
 
     /**
-     * Set realm for passpoint credential
+     * Set realm for passpoint credential; realm identifies a set of networks where your
+     * passpoint credential can be used
      * @param realm the realm
      */
     public void setRealm(String realm) {
@@ -617,7 +618,7 @@ public class WifiEnterpriseConfig implements Parcelable {
     }
 
     /**
-     * Get realm for passpoint credential
+     * Get realm for passpoint credential; see {@link #setRealm(String)} for more information
      * @return the realm
      */
     public String getRealm() {
@@ -625,15 +626,16 @@ public class WifiEnterpriseConfig implements Parcelable {
     }
 
     /**
-     * Set plmn for passpoint credential
-     * @param plmn the plmn value derived from mcc & mnc
+     * Set plmn (Public Land Mobile Network) of the provider of passpoint credential
+     * @param plmn the plmn value derived from mcc (mobile country code) & mnc (mobile network code)
      */
     public void setPlmn(String plmn) {
         setFieldValue(PLMN_KEY, plmn, "");
     }
 
     /**
-     * Get plmn for passpoint credential
+     * Get plmn (Public Land Mobile Network) for passpoint credential; see {@link #setPlmn
+     * (String)} for more information
      * @return the plmn
      */
     public String getPlmn() {
diff --git a/wifi/java/android/net/wifi/WifiManager.java b/wifi/java/android/net/wifi/WifiManager.java
index 64fa0e5..d00c654 100644
--- a/wifi/java/android/net/wifi/WifiManager.java
+++ b/wifi/java/android/net/wifi/WifiManager.java
@@ -399,14 +399,16 @@ public class WifiManager {
     public static final int CHANGE_REASON_CONFIG_CHANGE = 2;
     /**
      * An access point scan has completed, and results are available from the supplicant.
-     * Call {@link #getScanResults()} to obtain the results.
+     * Call {@link #getScanResults()} to obtain the results. {@link #EXTRA_RESULTS_UPDATED}
+     * indicates if the scan was completed successfully.
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String SCAN_RESULTS_AVAILABLE_ACTION = "android.net.wifi.SCAN_RESULTS";
 
     /**
-     * The result of previous scan, reported with {@link #SCAN_RESULTS_AVAILABLE_ACTION}.
-     * @return true scan was successful, results updated
+     * Lookup key for a {@code boolean} representing the result of previous {@link #startScan}
+     * operation, reported with {@link #SCAN_RESULTS_AVAILABLE_ACTION}.
+     * @return true scan was successful, results are updated
      * @return false scan was not successful, results haven't been updated since previous scan
      */
     public static final String EXTRA_RESULTS_UPDATED = "resultsUpdated";