1 files changed, 54 insertions, 39 deletions

diff --git a/framework/java/android/bluetooth/le/ScanSettings.java b/framework/java/android/bluetooth/le/ScanSettings.java
index 7c0f9e12f7..20977026d3 100644
--- a/framework/java/android/bluetooth/le/ScanSettings.java
+++ b/framework/java/android/bluetooth/le/ScanSettings.java
@@ -16,54 +16,66 @@
 
 package android.bluetooth.le;
 
+import android.annotation.SystemApi;
 import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * Settings for Bluetooth LE scan.
+ * Bluetooth LE scan settings are passed to {@link BluetoothLeScanner#startScan}
+ * to define the parameters for the scan.
  */
 public final class ScanSettings implements Parcelable {
     /**
-     * Perform Bluetooth LE scan in low power mode. This is the default scan mode as it consumes the
-     * least power.
+     * Perform Bluetooth LE scan in low power mode.
+     * This is the default scan mode as it consumes the least power.
      */
     public static final int SCAN_MODE_LOW_POWER = 0;
+
     /**
      * Perform Bluetooth LE scan in balanced power mode.
+     * Scan results are returned at a rate that provides a good trade-off between scan
+     * frequency and power consumption.
      */
     public static final int SCAN_MODE_BALANCED = 1;
+
     /**
-     * Scan using highest duty cycle. It's recommended only using this mode when the application is
-     * running in foreground.
+     * Scan using highest duty cycle.
+     * It's recommended to only use this mode when the application is running in the foreground.
      */
     public static final int SCAN_MODE_LOW_LATENCY = 2;
 
     /**
-     * Callback each time when a bluetooth advertisement is found.
+     * Triggger a callback for every Bluetooth advertisement found that matches the
+     * filter criteria. If no filter is active, all advertisement packets are reported.
      */
-    public static final int CALLBACK_TYPE_ON_UPDATE = 0;
+    public static final int CALLBACK_TYPE_ALL_MATCHES = 1;
+
     /**
-     * Callback when a bluetooth advertisement is found for the first time.
+     * A result callback is only triggered for the first advertisement packet received that
+     * matches the filter criteria.
      */
-    public static final int CALLBACK_TYPE_ON_FOUND = 1;
+    public static final int CALLBACK_TYPE_FIRST_MATCH = 2;
+
     /**
-     * Callback when a bluetooth advertisement is found for the first time, then lost.
+     * Receive a callback when advertisements are no longer received from a device that has been
+     * previously reported by a first match callback.
      */
-    public static final int CALLBACK_TYPE_ON_LOST = 2;
+    public static final int CALLBACK_TYPE_MATCH_LOST = 4;
 
     /**
-     * Full scan result which contains device mac address, rssi, advertising and scan response and
-     * scan timestamp.
+     * Request full scan results which contain the device, rssi, advertising data, scan response
+     * as well as the scan timestamp.
      */
     public static final int SCAN_RESULT_TYPE_FULL = 0;
+
     /**
-     * Truncated scan result which contains device mac address, rssi and scan timestamp. Note it's
-     * possible for an app to get more scan results that it asks if there are multiple apps using
-     * this type. TODO: decide whether we could unhide this setting.
-     *
+     * Request abbreviated scan results which contain the device, rssi and scan timestamp.
+     * <p><b>Note:</b> It is possible for an application to get more scan results than
+     * it asked for, if there are multiple apps using this type.
      * @hide
      */
-    public static final int SCAN_RESULT_TYPE_TRUNCATED = 1;
+    @SystemApi
+    public static final int SCAN_RESULT_TYPE_ABBREVIATED = 1;
 
     // Bluetooth LE scan mode.
     private int mScanMode;
@@ -75,7 +87,7 @@ public final class ScanSettings implements Parcelable {
     private int mScanResultType;
 
     // Time of delay for reporting the scan result
-    private long mReportDelayNanos;
+    private long mReportDelaySeconds;
 
     public int getScanMode() {
         return mScanMode;
@@ -92,23 +104,23 @@ public final class ScanSettings implements Parcelable {
     /**
      * Returns report delay timestamp based on the device clock.
      */
-    public long getReportDelayNanos() {
-        return mReportDelayNanos;
+    public long getReportDelaySeconds() {
+        return mReportDelaySeconds;
     }
 
     private ScanSettings(int scanMode, int callbackType, int scanResultType,
-            long reportDelayNanos) {
+            long reportDelaySeconds) {
         mScanMode = scanMode;
         mCallbackType = callbackType;
         mScanResultType = scanResultType;
-        mReportDelayNanos = reportDelayNanos;
+        mReportDelaySeconds = reportDelaySeconds;
     }
 
     private ScanSettings(Parcel in) {
         mScanMode = in.readInt();
         mCallbackType = in.readInt();
         mScanResultType = in.readInt();
-        mReportDelayNanos = in.readLong();
+        mReportDelaySeconds = in.readLong();
     }
 
     @Override
@@ -116,7 +128,7 @@ public final class ScanSettings implements Parcelable {
         dest.writeInt(mScanMode);
         dest.writeInt(mCallbackType);
         dest.writeInt(mScanResultType);
-        dest.writeLong(mReportDelayNanos);
+        dest.writeLong(mReportDelaySeconds);
     }
 
     @Override
@@ -142,15 +154,14 @@ public final class ScanSettings implements Parcelable {
      */
     public static final class Builder {
         private int mScanMode = SCAN_MODE_LOW_POWER;
-        private int mCallbackType = CALLBACK_TYPE_ON_UPDATE;
+        private int mCallbackType = CALLBACK_TYPE_ALL_MATCHES;
         private int mScanResultType = SCAN_RESULT_TYPE_FULL;
-        private long mReportDelayNanos = 0;
+        private long mReportDelaySeconds = 0;
 
         /**
          * Set scan mode for Bluetooth LE scan.
          *
-         * @param scanMode The scan mode can be one of
-         *            {@link ScanSettings#SCAN_MODE_LOW_POWER},
+         * @param scanMode The scan mode can be one of {@link ScanSettings#SCAN_MODE_LOW_POWER},
          *            {@link ScanSettings#SCAN_MODE_BALANCED} or
          *            {@link ScanSettings#SCAN_MODE_LOW_LATENCY}.
          * @throws IllegalArgumentException If the {@code scanMode} is invalid.
@@ -166,13 +177,13 @@ public final class ScanSettings implements Parcelable {
         /**
          * Set callback type for Bluetooth LE scan.
          *
-         * @param callbackType The callback type for the scan. Can only be
-         *            {@link ScanSettings#CALLBACK_TYPE_ON_UPDATE}.
+         * @param callbackType The callback type flags for the scan.
          * @throws IllegalArgumentException If the {@code callbackType} is invalid.
          */
         public Builder setCallbackType(int callbackType) {
-            if (callbackType < CALLBACK_TYPE_ON_UPDATE
-                    || callbackType > CALLBACK_TYPE_ON_LOST) {
+            if (callbackType < CALLBACK_TYPE_ALL_MATCHES
+             || callbackType > (CALLBACK_TYPE_FIRST_MATCH | CALLBACK_TYPE_MATCH_LOST)
+             || (callbackType & CALLBACK_TYPE_ALL_MATCHES) != CALLBACK_TYPE_ALL_MATCHES) {
                 throw new IllegalArgumentException("invalid callback type - " + callbackType);
             }
             mCallbackType = callbackType;
@@ -184,14 +195,14 @@ public final class ScanSettings implements Parcelable {
          *
          * @param scanResultType Type for scan result, could be either
          *            {@link ScanSettings#SCAN_RESULT_TYPE_FULL} or
-         *            {@link ScanSettings#SCAN_RESULT_TYPE_TRUNCATED}.
+         *            {@link ScanSettings#SCAN_RESULT_TYPE_ABBREVIATED}.
          * @throws IllegalArgumentException If the {@code scanResultType} is invalid.
-         *
          * @hide
          */
+        @SystemApi
         public Builder setScanResultType(int scanResultType) {
             if (scanResultType < SCAN_RESULT_TYPE_FULL
-                    || scanResultType > SCAN_RESULT_TYPE_TRUNCATED) {
+                    || scanResultType > SCAN_RESULT_TYPE_ABBREVIATED) {
                 throw new IllegalArgumentException(
                         "invalid scanResultType - " + scanResultType);
             }
@@ -201,9 +212,13 @@ public final class ScanSettings implements Parcelable {
 
         /**
          * Set report delay timestamp for Bluetooth LE scan.
+         * @param reportDelaySeconds 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.
          */
-        public Builder setReportDelayNanos(long reportDelayNanos) {
-            mReportDelayNanos = reportDelayNanos;
+        public Builder setReportDelaySeconds(long reportDelaySeconds) {
+            mReportDelaySeconds = reportDelaySeconds;
             return this;
         }
 
@@ -212,7 +227,7 @@ public final class ScanSettings implements Parcelable {
          */
         public ScanSettings build() {
             return new ScanSettings(mScanMode, mCallbackType, mScanResultType,
-                    mReportDelayNanos);
+                    mReportDelaySeconds);
         }
     }
 }