1 /* 2 * Copyright (C) 2024 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 17 package android.bluetooth.le; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.SystemApi; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 25 import java.lang.annotation.ElementType; 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.RetentionPolicy; 28 import java.lang.annotation.Target; 29 30 /** 31 * The {@link ChannelSoundingParams} provide a way to adjust distance measurement preferences for 32 * {@link DISTANCE_MEASUREMENT_METHOD_CHANNEL_SOUNDING}. Use {@link ChannelSoundingParams.Builder} 33 * to create an instance of this class. 34 * 35 * @hide 36 */ 37 @SystemApi 38 public final class ChannelSoundingParams implements Parcelable { 39 40 /** @hide */ 41 @Retention(RetentionPolicy.SOURCE) 42 @IntDef( 43 value = { 44 SIGHT_TYPE_UNKNOWN, 45 SIGHT_TYPE_LINE_OF_SIGHT, 46 SIGHT_TYPE_NON_LINE_OF_SIGHT, 47 }) 48 @interface SightType {} 49 50 /** @hide */ 51 @Retention(RetentionPolicy.SOURCE) 52 @IntDef(value = {LOCATION_TYPE_UNKNOWN, LOCATION_TYPE_INDOOR, LOCATION_TYPE_OUTDOOR}) 53 @interface LocationType {} 54 55 /** @hide */ 56 @Target(ElementType.TYPE_USE) 57 @Retention(RetentionPolicy.SOURCE) 58 @IntDef( 59 value = { 60 CS_SECURITY_LEVEL_UNKNOWN, 61 CS_SECURITY_LEVEL_ONE, 62 CS_SECURITY_LEVEL_TWO, 63 CS_SECURITY_LEVEL_THREE, 64 CS_SECURITY_LEVEL_FOUR 65 }) 66 @interface CsSecurityLevel {} 67 68 /** 69 * Sight type is unknown. 70 * 71 * @hide 72 */ 73 @SystemApi public static final int SIGHT_TYPE_UNKNOWN = 0; 74 75 /** 76 * Remote device is in line of sight. 77 * 78 * @hide 79 */ 80 @SystemApi public static final int SIGHT_TYPE_LINE_OF_SIGHT = 1; 81 82 /** 83 * Remote device is not in line of sight. 84 * 85 * @hide 86 */ 87 @SystemApi public static final int SIGHT_TYPE_NON_LINE_OF_SIGHT = 2; 88 89 /** 90 * Location type is unknown. 91 * 92 * @hide 93 */ 94 @SystemApi public static final int LOCATION_TYPE_UNKNOWN = 0; 95 96 /** 97 * The location of the usecase is indoor. 98 * 99 * @hide 100 */ 101 @SystemApi public static final int LOCATION_TYPE_INDOOR = 1; 102 103 /** 104 * The location of the usecase is outdoor. 105 * 106 * @hide 107 */ 108 @SystemApi public static final int LOCATION_TYPE_OUTDOOR = 2; 109 110 /** 111 * Return value for {@link 112 * DistanceMeasurementManager#getChannelSoundingMaxSupportedSecurityLevel(BluetoothDevice)} and 113 * {@link DistanceMeasurementManager#getLocalChannelSoundingMaxSupportedSecurityLevel()} when 114 * Channel Sounding is not supported, or encounters an internal error. 115 * 116 * @hide 117 */ 118 @SystemApi public static final int CS_SECURITY_LEVEL_UNKNOWN = 0; 119 120 /** 121 * Either CS tone or CS RTT. 122 * 123 * @hide 124 */ 125 @SystemApi public static final int CS_SECURITY_LEVEL_ONE = 1; 126 127 /** 128 * 150 ns CS RTT accuracy and CS tones. 129 * 130 * @hide 131 */ 132 @SystemApi public static final int CS_SECURITY_LEVEL_TWO = 2; 133 134 /** 135 * 10 ns CS RTT accuracy and CS tones. 136 * 137 * @hide 138 */ 139 @SystemApi public static final int CS_SECURITY_LEVEL_THREE = 3; 140 141 /** 142 * Level 3 with the addition of CS RTT sounding sequence or random sequence payloads, and 143 * support of the Normalized Attack Detector Metric requirements. 144 * 145 * @hide 146 */ 147 @SystemApi public static final int CS_SECURITY_LEVEL_FOUR = 4; 148 149 private final int mSightType; 150 private final int mLocationType; 151 private final int mCsSecurityLevel; 152 153 /** @hide */ ChannelSoundingParams(int sightType, int locationType, int csSecurityLevel)154 public ChannelSoundingParams(int sightType, int locationType, int csSecurityLevel) { 155 mSightType = sightType; 156 mLocationType = locationType; 157 mCsSecurityLevel = csSecurityLevel; 158 } 159 160 /** 161 * Returns sight type of this ChannelSoundingParams. 162 * 163 * @hide 164 */ 165 @SystemApi 166 @SightType getSightType()167 public int getSightType() { 168 return mSightType; 169 } 170 171 /** 172 * Returns location type of this ChannelSoundingParams. 173 * 174 * @hide 175 */ 176 @SystemApi 177 @LocationType getLocationType()178 public int getLocationType() { 179 return mLocationType; 180 } 181 182 /** 183 * Returns CS security level of this ChannelSoundingParams. 184 * 185 * @hide 186 */ 187 @SystemApi 188 @CsSecurityLevel getCsSecurityLevel()189 public int getCsSecurityLevel() { 190 return mCsSecurityLevel; 191 } 192 193 /** 194 * {@inheritDoc} 195 * 196 * @hide 197 */ 198 @Override describeContents()199 public int describeContents() { 200 return 0; 201 } 202 203 /** 204 * {@inheritDoc} 205 * 206 * @hide 207 */ 208 @Override writeToParcel(@onNull Parcel out, int flags)209 public void writeToParcel(@NonNull Parcel out, int flags) { 210 out.writeInt(mSightType); 211 out.writeInt(mLocationType); 212 out.writeInt(mCsSecurityLevel); 213 } 214 215 /** A {@link Parcelable.Creator} to create {@link ChannelSoundingParams} from parcel. */ 216 public static final @NonNull Parcelable.Creator<ChannelSoundingParams> CREATOR = 217 new Parcelable.Creator<ChannelSoundingParams>() { 218 @Override 219 public @NonNull ChannelSoundingParams createFromParcel(@NonNull Parcel in) { 220 Builder builder = new Builder(); 221 builder.setSightType(in.readInt()); 222 builder.setLocationType(in.readInt()); 223 builder.setCsSecurityLevel(in.readInt()); 224 return builder.build(); 225 } 226 227 @Override 228 public @NonNull ChannelSoundingParams[] newArray(int size) { 229 return new ChannelSoundingParams[size]; 230 } 231 }; 232 233 /** 234 * Builder for {@link ChannelSoundingParams}. 235 * 236 * @hide 237 */ 238 @SystemApi 239 public static final class Builder { 240 private int mSightType = SIGHT_TYPE_UNKNOWN; 241 private int mLocationType = LOCATION_TYPE_UNKNOWN; 242 private int mCsSecurityLevel = CS_SECURITY_LEVEL_ONE; 243 244 /** 245 * Set sight type for the ChannelSoundingParams. 246 * 247 * @param sightType sight type of this ChannelSoundingParams 248 * @return the same Builder instance 249 * @hide 250 */ 251 @SystemApi setSightType(@ightType int sightType)252 public @NonNull Builder setSightType(@SightType int sightType) { 253 switch (sightType) { 254 case SIGHT_TYPE_UNKNOWN: 255 case SIGHT_TYPE_LINE_OF_SIGHT: 256 case SIGHT_TYPE_NON_LINE_OF_SIGHT: 257 mSightType = sightType; 258 break; 259 default: 260 throw new IllegalArgumentException("unknown sight type " + sightType); 261 } 262 return this; 263 } 264 265 /** 266 * Set location type for the ChannelSoundingParams. 267 * 268 * @param locationType location type of this ChannelSoundingParams 269 * @return the same Builder instance 270 * @hide 271 */ 272 @SystemApi setLocationType(@ocationType int locationType)273 public @NonNull Builder setLocationType(@LocationType int locationType) { 274 switch (locationType) { 275 case LOCATION_TYPE_UNKNOWN: 276 case LOCATION_TYPE_INDOOR: 277 case LOCATION_TYPE_OUTDOOR: 278 mLocationType = locationType; 279 break; 280 default: 281 throw new IllegalArgumentException("unknown location type " + locationType); 282 } 283 return this; 284 } 285 286 /** 287 * Set CS security level for the ChannelSoundingParams. 288 * 289 * <p>See: https://bluetooth.com/specifications/specs/channel-sounding-cr-pr/ 290 * 291 * @param csSecurityLevel cs security level of this ChannelSoundingParams 292 * @return the same Builder instance 293 * @hide 294 */ 295 @SystemApi setCsSecurityLevel(@sSecurityLevel int csSecurityLevel)296 public @NonNull Builder setCsSecurityLevel(@CsSecurityLevel int csSecurityLevel) { 297 switch (csSecurityLevel) { 298 case CS_SECURITY_LEVEL_ONE: 299 case CS_SECURITY_LEVEL_TWO: 300 case CS_SECURITY_LEVEL_THREE: 301 case CS_SECURITY_LEVEL_FOUR: 302 mCsSecurityLevel = csSecurityLevel; 303 break; 304 default: 305 throw new IllegalArgumentException( 306 "unknown CS security level " + csSecurityLevel); 307 } 308 return this; 309 } 310 311 /** 312 * Build the {@link ChannelSoundingParams} object. 313 * 314 * @hide 315 */ 316 @SystemApi build()317 public @NonNull ChannelSoundingParams build() { 318 return new ChannelSoundingParams(mSightType, mLocationType, mCsSecurityLevel); 319 } 320 } 321 } 322