ScanSettings.java revision 9fb1791e1a6859bfb14006a6d101cdecc88f3f95
1/* 2 * Copyright (C) 2014 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.bluetooth.le; 18 19import android.os.Parcel; 20import android.os.Parcelable; 21 22/** 23 * Settings for Bluetooth LE scan. 24 */ 25public final class ScanSettings implements Parcelable { 26 /** 27 * Perform Bluetooth LE scan in low power mode. This is the default scan mode as it consumes the 28 * least power. 29 */ 30 public static final int SCAN_MODE_LOW_POWER = 0; 31 /** 32 * Perform Bluetooth LE scan in balanced power mode. 33 */ 34 public static final int SCAN_MODE_BALANCED = 1; 35 /** 36 * Scan using highest duty cycle. It's recommended only using this mode when the application is 37 * running in foreground. 38 */ 39 public static final int SCAN_MODE_LOW_LATENCY = 2; 40 41 /** 42 * Callback each time when a bluetooth advertisement is found. 43 */ 44 public static final int CALLBACK_TYPE_ON_UPDATE = 0; 45 /** 46 * Callback when a bluetooth advertisement is found for the first time. 47 * @hide 48 */ 49 public static final int CALLBACK_TYPE_ON_FOUND = 1; 50 /** 51 * Callback when a bluetooth advertisement is found for the first time, then lost. 52 * 53 * @hide 54 */ 55 public static final int CALLBACK_TYPE_ON_LOST = 2; 56 57 /** 58 * Full scan result which contains device mac address, rssi, advertising and scan response and 59 * scan timestamp. 60 */ 61 public static final int SCAN_RESULT_TYPE_FULL = 0; 62 /** 63 * Truncated scan result which contains device mac address, rssi and scan timestamp. Note it's 64 * possible for an app to get more scan results that it asks if there are multiple apps using 65 * this type. TODO: decide whether we could unhide this setting. 66 * 67 * @hide 68 */ 69 public static final int SCAN_RESULT_TYPE_TRUNCATED = 1; 70 71 // Bluetooth LE scan mode. 72 private int mScanMode; 73 74 // Bluetooth LE scan callback type 75 private int mCallbackType; 76 77 // Bluetooth LE scan result type 78 private int mScanResultType; 79 80 // Time of delay for reporting the scan result 81 private long mReportDelayNanos; 82 83 public int getScanMode() { 84 return mScanMode; 85 } 86 87 public int getCallbackType() { 88 return mCallbackType; 89 } 90 91 public int getScanResultType() { 92 return mScanResultType; 93 } 94 95 /** 96 * Returns report delay timestamp based on the device clock. 97 */ 98 public long getReportDelayNanos() { 99 return mReportDelayNanos; 100 } 101 102 private ScanSettings(int scanMode, int callbackType, int scanResultType, 103 long reportDelayNanos) { 104 mScanMode = scanMode; 105 mCallbackType = callbackType; 106 mScanResultType = scanResultType; 107 mReportDelayNanos = reportDelayNanos; 108 } 109 110 private ScanSettings(Parcel in) { 111 mScanMode = in.readInt(); 112 mCallbackType = in.readInt(); 113 mScanResultType = in.readInt(); 114 mReportDelayNanos = in.readLong(); 115 } 116 117 @Override 118 public void writeToParcel(Parcel dest, int flags) { 119 dest.writeInt(mScanMode); 120 dest.writeInt(mCallbackType); 121 dest.writeInt(mScanResultType); 122 dest.writeLong(mReportDelayNanos); 123 } 124 125 @Override 126 public int describeContents() { 127 return 0; 128 } 129 130 public static final Parcelable.Creator<ScanSettings> 131 CREATOR = new Creator<ScanSettings>() { 132 @Override 133 public ScanSettings[] newArray(int size) { 134 return new ScanSettings[size]; 135 } 136 137 @Override 138 public ScanSettings createFromParcel(Parcel in) { 139 return new ScanSettings(in); 140 } 141 }; 142 143 /** 144 * Builder for {@link ScanSettings}. 145 */ 146 public static final class Builder { 147 private int mScanMode = SCAN_MODE_LOW_POWER; 148 private int mCallbackType = CALLBACK_TYPE_ON_UPDATE; 149 private int mScanResultType = SCAN_RESULT_TYPE_FULL; 150 private long mReportDelayNanos = 0; 151 152 /** 153 * Set scan mode for Bluetooth LE scan. 154 * 155 * @param scanMode The scan mode can be one of 156 * {@link ScanSettings#SCAN_MODE_LOW_POWER}, 157 * {@link ScanSettings#SCAN_MODE_BALANCED} or 158 * {@link ScanSettings#SCAN_MODE_LOW_LATENCY}. 159 * @throws IllegalArgumentException If the {@code scanMode} is invalid. 160 */ 161 public Builder setScanMode(int scanMode) { 162 if (scanMode < SCAN_MODE_LOW_POWER || scanMode > SCAN_MODE_LOW_LATENCY) { 163 throw new IllegalArgumentException("invalid scan mode " + scanMode); 164 } 165 mScanMode = scanMode; 166 return this; 167 } 168 169 /** 170 * Set callback type for Bluetooth LE scan. 171 * 172 * @param callbackType The callback type for the scan. Can only be 173 * {@link ScanSettings#CALLBACK_TYPE_ON_UPDATE}. 174 * @throws IllegalArgumentException If the {@code callbackType} is invalid. 175 */ 176 public Builder setCallbackType(int callbackType) { 177 if (callbackType < CALLBACK_TYPE_ON_UPDATE 178 || callbackType > CALLBACK_TYPE_ON_LOST) { 179 throw new IllegalArgumentException("invalid callback type - " + callbackType); 180 } 181 mCallbackType = callbackType; 182 return this; 183 } 184 185 /** 186 * Set scan result type for Bluetooth LE scan. 187 * 188 * @param scanResultType Type for scan result, could be either 189 * {@link ScanSettings#SCAN_RESULT_TYPE_FULL} or 190 * {@link ScanSettings#SCAN_RESULT_TYPE_TRUNCATED}. 191 * @throws IllegalArgumentException If the {@code scanResultType} is invalid. 192 * 193 * @hide 194 */ 195 public Builder setScanResultType(int scanResultType) { 196 if (scanResultType < SCAN_RESULT_TYPE_FULL 197 || scanResultType > SCAN_RESULT_TYPE_TRUNCATED) { 198 throw new IllegalArgumentException( 199 "invalid scanResultType - " + scanResultType); 200 } 201 mScanResultType = scanResultType; 202 return this; 203 } 204 205 /** 206 * Set report delay timestamp for Bluetooth LE scan. 207 */ 208 public Builder setReportDelayNanos(long reportDelayNanos) { 209 mReportDelayNanos = reportDelayNanos; 210 return this; 211 } 212 213 /** 214 * Build {@link ScanSettings}. 215 */ 216 public ScanSettings build() { 217 return new ScanSettings(mScanMode, mCallbackType, mScanResultType, 218 mReportDelayNanos); 219 } 220 } 221} 222