Merge "Fix API council review comments. Also hide certain APIs(1/3)." into lmp-dev

7 files changed, 49 insertions, 50 deletions

diff --git a/api/current.txt b/api/current.txt
index 5a083d0..eacc452 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -6622,6 +6622,7 @@ package android.bluetooth.le {
     method public java.util.Map<android.os.ParcelUuid, byte[]> getServiceData();
     method public java.util.List<android.os.ParcelUuid> getServiceUuids();
     method public void writeToParcel(android.os.Parcel, int);
+    field public static final android.os.Parcelable.Creator CREATOR;
   }
 
   public static final class AdvertiseData.Builder {
@@ -6636,10 +6637,10 @@ package android.bluetooth.le {
 
   public final class AdvertiseSettings implements android.os.Parcelable {
     method public int describeContents();
-    method public boolean getIsConnectable();
     method public int getMode();
     method public int getTimeout();
     method public int getTxPowerLevel();
+    method public boolean isConnectable();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final int ADVERTISE_MODE_BALANCED = 1; // 0x1
     field public static final int ADVERTISE_MODE_LOW_LATENCY = 2; // 0x2
@@ -6648,13 +6649,14 @@ package android.bluetooth.le {
     field public static final int ADVERTISE_TX_POWER_LOW = 1; // 0x1
     field public static final int ADVERTISE_TX_POWER_MEDIUM = 2; // 0x2
     field public static final int ADVERTISE_TX_POWER_ULTRA_LOW = 0; // 0x0
+    field public static final android.os.Parcelable.Creator CREATOR;
   }
 
   public static final class AdvertiseSettings.Builder {
     ctor public AdvertiseSettings.Builder();
     method public android.bluetooth.le.AdvertiseSettings build();
     method public android.bluetooth.le.AdvertiseSettings.Builder setAdvertiseMode(int);
-    method public android.bluetooth.le.AdvertiseSettings.Builder setIsConnectable(boolean);
+    method public android.bluetooth.le.AdvertiseSettings.Builder setConnectable(boolean);
     method public android.bluetooth.le.AdvertiseSettings.Builder setTimeout(int);
     method public android.bluetooth.le.AdvertiseSettings.Builder setTxPowerLevel(int);
   }
@@ -6697,6 +6699,7 @@ package android.bluetooth.le {
     method public android.os.ParcelUuid getServiceUuidMask();
     method public boolean matches(android.bluetooth.le.ScanResult);
     method public void writeToParcel(android.os.Parcel, int);
+    field public static final android.os.Parcelable.Creator CREATOR;
   }
 
   public static final class ScanFilter.Builder {
@@ -6732,6 +6735,7 @@ package android.bluetooth.le {
     method public android.bluetooth.le.ScanRecord getScanRecord();
     method public long getTimestampNanos();
     method public void writeToParcel(android.os.Parcel, int);
+    field public static final android.os.Parcelable.Creator CREATOR;
   }
 
   public final class ScanSettings implements android.os.Parcelable {
@@ -6742,19 +6746,16 @@ package android.bluetooth.le {
     method public int getScanResultType();
     method public void writeToParcel(android.os.Parcel, int);
     field public static final int CALLBACK_TYPE_ALL_MATCHES = 1; // 0x1
-    field public static final int CALLBACK_TYPE_FIRST_MATCH = 2; // 0x2
-    field public static final int CALLBACK_TYPE_MATCH_LOST = 4; // 0x4
+    field public static final android.os.Parcelable.Creator CREATOR;
     field public static final int SCAN_MODE_BALANCED = 1; // 0x1
     field public static final int SCAN_MODE_LOW_LATENCY = 2; // 0x2
     field public static final int SCAN_MODE_LOW_POWER = 0; // 0x0
-    field public static final int SCAN_RESULT_TYPE_FULL = 0; // 0x0
   }
 
   public static final class ScanSettings.Builder {
     ctor public ScanSettings.Builder();
     method public android.bluetooth.le.ScanSettings build();
-    method public android.bluetooth.le.ScanSettings.Builder setCallbackType(int);
-    method public android.bluetooth.le.ScanSettings.Builder setReportDelayMillis(long);
+    method public android.bluetooth.le.ScanSettings.Builder setReportDelay(long);
     method public android.bluetooth.le.ScanSettings.Builder setScanMode(int);
   }
 
diff --git a/core/java/android/bluetooth/le/AdvertiseData.java b/core/java/android/bluetooth/le/AdvertiseData.java
index 843cd84..c7bfae9 100644
--- a/core/java/android/bluetooth/le/AdvertiseData.java
+++ b/core/java/android/bluetooth/le/AdvertiseData.java
@@ -172,9 +172,6 @@ public final class AdvertiseData implements Parcelable {
         dest.writeByte((byte) (getIncludeDeviceName() ? 1 : 0));
     }
 
-    /**
-     * @hide
-     */
     public static final Parcelable.Creator<AdvertiseData> CREATOR =
             new Creator<AdvertiseData>() {
             @Override
diff --git a/core/java/android/bluetooth/le/AdvertiseSettings.java b/core/java/android/bluetooth/le/AdvertiseSettings.java
index 71d7b5b..62c68a4 100644
--- a/core/java/android/bluetooth/le/AdvertiseSettings.java
+++ b/core/java/android/bluetooth/le/AdvertiseSettings.java
@@ -66,13 +66,13 @@ public final class AdvertiseSettings implements Parcelable {
     public static final int ADVERTISE_TX_POWER_HIGH = 3;
 
     /**
-     * The maximimum limited advertisement duration as specified by the Bluetooth SIG
+     * The maximum limited advertisement duration as specified by the Bluetooth SIG
      */
-    private static final int LIMITED_ADVERTISING_MAX_DURATION = 180;
+    private static final int LIMITED_ADVERTISING_MAX_MILLIS = 180 * 1000;
 
     private final int mAdvertiseMode;
     private final int mAdvertiseTxPowerLevel;
-    private final int mAdvertiseTimeoutSeconds;
+    private final int mAdvertiseTimeoutMillis;
     private final boolean mAdvertiseConnectable;
 
     private AdvertiseSettings(int advertiseMode, int advertiseTxPowerLevel,
@@ -80,14 +80,14 @@ public final class AdvertiseSettings implements Parcelable {
         mAdvertiseMode = advertiseMode;
         mAdvertiseTxPowerLevel = advertiseTxPowerLevel;
         mAdvertiseConnectable = advertiseConnectable;
-        mAdvertiseTimeoutSeconds = advertiseTimeout;
+        mAdvertiseTimeoutMillis = advertiseTimeout;
     }
 
     private AdvertiseSettings(Parcel in) {
         mAdvertiseMode = in.readInt();
         mAdvertiseTxPowerLevel = in.readInt();
         mAdvertiseConnectable = in.readInt() != 0 ? true : false;
-        mAdvertiseTimeoutSeconds = in.readInt();
+        mAdvertiseTimeoutMillis = in.readInt();
     }
 
     /**
@@ -107,15 +107,15 @@ public final class AdvertiseSettings implements Parcelable {
     /**
      * Returns whether the advertisement will indicate connectable.
      */
-    public boolean getIsConnectable() {
+    public boolean isConnectable() {
         return mAdvertiseConnectable;
     }
 
     /**
-     * Returns the advertising time limit in seconds.
+     * Returns the advertising time limit in milliseconds.
      */
     public int getTimeout() {
-        return mAdvertiseTimeoutSeconds;
+        return mAdvertiseTimeoutMillis;
     }
 
     @Override
@@ -123,7 +123,7 @@ public final class AdvertiseSettings implements Parcelable {
         return "Settings [mAdvertiseMode=" + mAdvertiseMode
              + ", mAdvertiseTxPowerLevel=" + mAdvertiseTxPowerLevel
              + ", mAdvertiseConnectable=" + mAdvertiseConnectable
-             + ", mAdvertiseTimeoutSeconds=" + mAdvertiseTimeoutSeconds + "]";
+             + ", mAdvertiseTimeoutMillis=" + mAdvertiseTimeoutMillis + "]";
     }
 
     @Override
@@ -136,12 +136,9 @@ public final class AdvertiseSettings implements Parcelable {
         dest.writeInt(mAdvertiseMode);
         dest.writeInt(mAdvertiseTxPowerLevel);
         dest.writeInt(mAdvertiseConnectable ? 1 : 0);
-        dest.writeInt(mAdvertiseTimeoutSeconds);
+        dest.writeInt(mAdvertiseTimeoutMillis);
     }
 
-    /**
-     * @hide
-     */
     public static final Parcelable.Creator<AdvertiseSettings> CREATOR =
             new Creator<AdvertiseSettings>() {
             @Override
@@ -161,7 +158,7 @@ public final class AdvertiseSettings implements Parcelable {
     public static final class Builder {
         private int mMode = ADVERTISE_MODE_LOW_POWER;
         private int mTxPowerLevel = ADVERTISE_TX_POWER_MEDIUM;
-        private int mTimeoutSeconds = 0;
+        private int mTimeoutMillis = 0;
         private boolean mConnectable = true;
 
         /**
@@ -204,26 +201,26 @@ public final class AdvertiseSettings implements Parcelable {
         /**
          * Set whether the advertisement type should be connectable or non-connectable.
          *
-         * @param isConnectable Controls whether the advertisment type will be connectable (true)
+         * @param connectable Controls whether the advertisment type will be connectable (true)
          *                    or non-connectable (false).
          */
-        public Builder setIsConnectable(boolean isConnectable) {
-            mConnectable = isConnectable;
+        public Builder setConnectable(boolean connectable) {
+            mConnectable = connectable;
             return this;
         }
 
         /**
          * Limit advertising to a given amount of time.
-         * @param timeoutSeconds Advertising time limit. May not exceed 180 seconds.
+         * @param timeoutMillis Advertising time limit. May not exceed 180000 milliseconds.
          *                       A value of 0 will disable the time limit.
-         * @throws IllegalArgumentException If the provided timeout is over 180s.
+         * @throws IllegalArgumentException If the provided timeout is over 180000 ms.
          */
-        public Builder setTimeout(int timeoutSeconds) {
-            if (timeoutSeconds < 0 || timeoutSeconds > LIMITED_ADVERTISING_MAX_DURATION) {
-                throw new IllegalArgumentException("timeoutSeconds invalid (must be 0-"
-                                    + LIMITED_ADVERTISING_MAX_DURATION + " seconds)");
+        public Builder setTimeout(int timeoutMillis) {
+            if (timeoutMillis < 0 || timeoutMillis > LIMITED_ADVERTISING_MAX_MILLIS) {
+                throw new IllegalArgumentException("timeoutMillis invalid (must be 0-"
+                                    + LIMITED_ADVERTISING_MAX_MILLIS + " milliseconds)");
             }
-            mTimeoutSeconds = timeoutSeconds;
+            mTimeoutMillis = timeoutMillis;
             return this;
         }
 
@@ -231,7 +228,7 @@ public final class AdvertiseSettings implements Parcelable {
          * Build the {@link AdvertiseSettings} object.
          */
         public AdvertiseSettings build() {
-            return new AdvertiseSettings(mMode, mTxPowerLevel, mConnectable, mTimeoutSeconds);
+            return new AdvertiseSettings(mMode, mTxPowerLevel, mConnectable, mTimeoutMillis);
         }
     }
 }
diff --git a/core/java/android/bluetooth/le/ScanCallback.java b/core/java/android/bluetooth/le/ScanCallback.java
index 5b37384..05782a8 100644
--- a/core/java/android/bluetooth/le/ScanCallback.java
+++ b/core/java/android/bluetooth/le/ScanCallback.java
@@ -47,8 +47,8 @@ public abstract class ScanCallback {
     /**
      * Callback when a BLE advertisement has been found.
      *
-     * @param callbackType Determines if this callback was triggered because of first match, a lost
-     *            match indication or a regular scan result.
+     * @param callbackType Determines how this callback was triggered. Currently could only be
+     *            {@link ScanSettings#CALLBACK_TYPE_ALL_MATCHES}.
      * @param result A Bluetooth LE scan result.
      */
     public void onScanResult(int callbackType, ScanResult result) {
@@ -64,6 +64,7 @@ public abstract class ScanCallback {
 
     /**
      * Callback when scan could not be started.
+     *
      * @param errorCode Error code (one of SCAN_FAILED_*) for scan failure.
      */
     public void onScanFailed(int errorCode) {
diff --git a/core/java/android/bluetooth/le/ScanFilter.java b/core/java/android/bluetooth/le/ScanFilter.java
index d1b93d2..5025218 100644
--- a/core/java/android/bluetooth/le/ScanFilter.java
+++ b/core/java/android/bluetooth/le/ScanFilter.java
@@ -138,8 +138,6 @@ public final class ScanFilter implements Parcelable {
 
     /**
      * A {@link android.os.Parcelable.Creator} to create {@link ScanFilter} from parcel.
-     *
-     * @hide
      */
     public static final Creator<ScanFilter>
             CREATOR = new Creator<ScanFilter>() {
diff --git a/core/java/android/bluetooth/le/ScanResult.java b/core/java/android/bluetooth/le/ScanResult.java
index a0bdaff..2fdfe7f 100644
--- a/core/java/android/bluetooth/le/ScanResult.java
+++ b/core/java/android/bluetooth/le/ScanResult.java
@@ -149,9 +149,6 @@ public final class ScanResult implements Parcelable {
                 + mTimestampNanos + '}';
     }
 
-    /**
-     * @hide
-     */
     public static final Parcelable.Creator<ScanResult> CREATOR = new Creator<ScanResult>() {
             @Override
         public ScanResult createFromParcel(Parcel source) {
diff --git a/core/java/android/bluetooth/le/ScanSettings.java b/core/java/android/bluetooth/le/ScanSettings.java
index b2ee6a8..7eae439 100644
--- a/core/java/android/bluetooth/le/ScanSettings.java
+++ b/core/java/android/bluetooth/le/ScanSettings.java
@@ -52,19 +52,28 @@ public final class ScanSettings implements Parcelable {
     /**
      * A result callback is only triggered for the first advertisement packet received that matches
      * the filter criteria.
+     *
+     * @hide
      */
+    @SystemApi
     public static final int CALLBACK_TYPE_FIRST_MATCH = 2;
 
     /**
      * Receive a callback when advertisements are no longer received from a device that has been
      * previously reported by a first match callback.
+     *
+     * @hide
      */
+    @SystemApi
     public static final int CALLBACK_TYPE_MATCH_LOST = 4;
 
     /**
      * Request full scan results which contain the device, rssi, advertising data, scan response as
      * well as the scan timestamp.
+     *
+     * @hide
      */
+    @SystemApi
     public static final int SCAN_RESULT_TYPE_FULL = 0;
 
     /**
@@ -137,9 +146,6 @@ public final class ScanSettings implements Parcelable {
         return 0;
     }
 
-    /**
-     * @hide
-     */
     public static final Parcelable.Creator<ScanSettings>
             CREATOR = new Creator<ScanSettings>() {
                     @Override
@@ -183,7 +189,9 @@ public final class ScanSettings implements Parcelable {
          *
          * @param callbackType The callback type flags for the scan.
          * @throws IllegalArgumentException If the {@code callbackType} is invalid.
+         * @hide
          */
+        @SystemApi
         public Builder setCallbackType(int callbackType) {
 
             if (!isValidCallbackType(callbackType)) {
@@ -226,14 +234,14 @@ public final class ScanSettings implements Parcelable {
         /**
          * Set report delay timestamp for Bluetooth LE scan.
          *
-         * @param reportDelayMillis Set to 0 to be notified of results immediately. Values &gt; 0
-         *            causes the scan results to be queued up and delivered after the requested
-         *            delay or when the internal buffers fill up.
+         * @param reportDelayMillis Delay of report in milliseconds. Set to 0 to be notified of
+         *            results immediately. Values &gt; 0 causes the scan results to be queued up and
+         *            delivered after the requested delay or when the internal buffers fill up.
          * @throws IllegalArgumentException If {@code reportDelayMillis} &lt; 0.
          */
-        public Builder setReportDelayMillis(long reportDelayMillis) {
+        public Builder setReportDelay(long reportDelayMillis) {
             if (reportDelayMillis < 0) {
-                throw new IllegalArgumentException("reportDelayMillis must be > 0");
+                throw new IllegalArgumentException("reportDelay must be > 0");
             }
             mReportDelayMillis = reportDelayMillis;
             return this;