Criteria.java revision 4e31c4fffbc42b4c2b5dca6431cfeef9e078f5b4
1/* 2 * Copyright (C) 2007 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.location; 18 19import android.os.Parcel; 20import android.os.Parcelable; 21 22/** 23 * A class indicating the application criteria for selecting a 24 * location provider. Providers maybe ordered according to accuracy, 25 * power usage, ability to report altitude, speed, 26 * and bearing, and monetary cost. 27 * 28 * @deprecated use {@link LocationRequest} instead, and also see notes 29 * at {@link LocationManager} 30 */ 31@Deprecated 32public class Criteria implements Parcelable { 33 /** 34 * A constant indicating that the application does not choose to 35 * place requirement on a particular feature. 36 */ 37 public static final int NO_REQUIREMENT = 0; 38 39 /** 40 * A constant indicating a low power requirement. 41 */ 42 public static final int POWER_LOW = 1; 43 44 /** 45 * A constant indicating a medium power requirement. 46 */ 47 public static final int POWER_MEDIUM = 2; 48 49 /** 50 * A constant indicating a high power requirement. 51 */ 52 public static final int POWER_HIGH = 3; 53 54 /** 55 * A constant indicating a finer location accuracy requirement 56 */ 57 public static final int ACCURACY_FINE = 1; 58 59 /** 60 * A constant indicating an approximate accuracy requirement 61 */ 62 public static final int ACCURACY_COARSE = 2; 63 64 /** 65 * A constant indicating a low location accuracy requirement 66 * - may be used for horizontal, altitude, speed or bearing accuracy. 67 * For horizontal and vertical position this corresponds roughly to 68 * an accuracy of greater than 500 meters. 69 */ 70 public static final int ACCURACY_LOW = 1; 71 72 /** 73 * A constant indicating a medium accuracy requirement 74 * - currently used only for horizontal accuracy. 75 * For horizontal position this corresponds roughly to to an accuracy 76 * of between 100 and 500 meters. 77 */ 78 public static final int ACCURACY_MEDIUM = 2; 79 80 /** 81 * a constant indicating a high accuracy requirement 82 * - may be used for horizontal, altitude, speed or bearing accuracy. 83 * For horizontal and vertical position this corresponds roughly to 84 * an accuracy of less than 100 meters. 85 */ 86 public static final int ACCURACY_HIGH = 3; 87 88 private int mHorizontalAccuracy = NO_REQUIREMENT; 89 private int mVerticalAccuracy = NO_REQUIREMENT; 90 private int mSpeedAccuracy = NO_REQUIREMENT; 91 private int mBearingAccuracy = NO_REQUIREMENT; 92 private int mPowerRequirement = NO_REQUIREMENT; 93 private boolean mAltitudeRequired = false; 94 private boolean mBearingRequired = false; 95 private boolean mSpeedRequired = false; 96 private boolean mCostAllowed = false; 97 98 /** 99 * Constructs a new Criteria object. The new object will have no 100 * requirements on accuracy, power, or response time; will not 101 * require altitude, speed, or bearing; and will not allow monetary 102 * cost. 103 */ 104 public Criteria() {} 105 106 /** 107 * Constructs a new Criteria object that is a copy of the given criteria. 108 */ 109 public Criteria(Criteria criteria) { 110 mHorizontalAccuracy = criteria.mHorizontalAccuracy; 111 mVerticalAccuracy = criteria.mVerticalAccuracy; 112 mSpeedAccuracy = criteria.mSpeedAccuracy; 113 mBearingAccuracy = criteria.mBearingAccuracy; 114 mPowerRequirement = criteria.mPowerRequirement; 115 mAltitudeRequired = criteria.mAltitudeRequired; 116 mBearingRequired = criteria.mBearingRequired; 117 mSpeedRequired = criteria.mSpeedRequired; 118 mCostAllowed = criteria.mCostAllowed; 119 } 120 121 /** 122 * Indicates the desired horizontal accuracy (latitude and longitude). 123 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_MEDIUM}, 124 * {@link #ACCURACY_HIGH} or {@link #NO_REQUIREMENT}. 125 * More accurate location may consume more power and may take longer. 126 * 127 * @throws IllegalArgumentException if accuracy is not one of the supported constants 128 */ 129 public void setHorizontalAccuracy(int accuracy) { 130 if (accuracy < NO_REQUIREMENT || accuracy > ACCURACY_HIGH) { 131 throw new IllegalArgumentException("accuracy=" + accuracy); 132 } 133 mHorizontalAccuracy = accuracy; 134 } 135 136 /** 137 * Returns a constant indicating the desired horizontal accuracy (latitude and longitude). 138 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_MEDIUM}, 139 * {@link #ACCURACY_HIGH} or {@link #NO_REQUIREMENT}. 140 */ 141 public int getHorizontalAccuracy() { 142 return mHorizontalAccuracy; 143 } 144 145 /** 146 * Indicates the desired vertical accuracy (altitude). 147 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_MEDIUM}, 148 * {@link #ACCURACY_HIGH} or {@link #NO_REQUIREMENT}. 149 * More accurate location may consume more power and may take longer. 150 * 151 * @throws IllegalArgumentException if accuracy is not one of the supported constants 152 */ 153 public void setVerticalAccuracy(int accuracy) { 154 if (accuracy < NO_REQUIREMENT || accuracy > ACCURACY_HIGH) { 155 throw new IllegalArgumentException("accuracy=" + accuracy); 156 } 157 mVerticalAccuracy = accuracy; 158 } 159 160 /** 161 * Returns a constant indicating the desired vertical accuracy (altitude). 162 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_HIGH}, 163 * or {@link #NO_REQUIREMENT}. 164 */ 165 public int getVerticalAccuracy() { 166 return mVerticalAccuracy; 167 } 168 169 /** 170 * Indicates the desired speed accuracy. 171 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_HIGH}, 172 * or {@link #NO_REQUIREMENT}. 173 * More accurate location may consume more power and may take longer. 174 * 175 * @throws IllegalArgumentException if accuracy is not one of the supported constants 176 */ 177 public void setSpeedAccuracy(int accuracy) { 178 if (accuracy < NO_REQUIREMENT || accuracy > ACCURACY_HIGH) { 179 throw new IllegalArgumentException("accuracy=" + accuracy); 180 } 181 mSpeedAccuracy = accuracy; 182 } 183 184 /** 185 * Returns a constant indicating the desired speed accuracy 186 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_HIGH}, 187 * or {@link #NO_REQUIREMENT}. 188 */ 189 public int getSpeedAccuracy() { 190 return mSpeedAccuracy; 191 } 192 193 /** 194 * Indicates the desired bearing accuracy. 195 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_HIGH}, 196 * or {@link #NO_REQUIREMENT}. 197 * More accurate location may consume more power and may take longer. 198 * 199 * @throws IllegalArgumentException if accuracy is not one of the supported constants 200 */ 201 public void setBearingAccuracy(int accuracy) { 202 if (accuracy < NO_REQUIREMENT || accuracy > ACCURACY_HIGH) { 203 throw new IllegalArgumentException("accuracy=" + accuracy); 204 } 205 mBearingAccuracy = accuracy; 206 } 207 208 /** 209 * Returns a constant indicating the desired bearing accuracy. 210 * Accuracy may be {@link #ACCURACY_LOW}, {@link #ACCURACY_HIGH}, 211 * or {@link #NO_REQUIREMENT}. 212 */ 213 public int getBearingAccuracy() { 214 return mBearingAccuracy; 215 } 216 217 /** 218 * Indicates the desired accuracy for latitude and longitude. Accuracy 219 * may be {@link #ACCURACY_FINE} if desired location 220 * is fine, else it can be {@link #ACCURACY_COARSE}. 221 * More accurate location may consume more power and may take longer. 222 * 223 * @throws IllegalArgumentException if accuracy is not one of the supported constants 224 */ 225 public void setAccuracy(int accuracy) { 226 if (accuracy < NO_REQUIREMENT || accuracy > ACCURACY_COARSE) { 227 throw new IllegalArgumentException("accuracy=" + accuracy); 228 } 229 if (accuracy == ACCURACY_FINE) { 230 mHorizontalAccuracy = ACCURACY_HIGH; 231 } else { 232 mHorizontalAccuracy = ACCURACY_LOW; 233 } 234 } 235 236 /** 237 * Returns a constant indicating desired accuracy of location 238 * Accuracy may be {@link #ACCURACY_FINE} if desired location 239 * is fine, else it can be {@link #ACCURACY_COARSE}. 240 */ 241 public int getAccuracy() { 242 if (mHorizontalAccuracy >= ACCURACY_HIGH) { 243 return ACCURACY_FINE; 244 } else { 245 return ACCURACY_COARSE; 246 } 247 } 248 249 /** 250 * Indicates the desired maximum power level. The level parameter 251 * must be one of NO_REQUIREMENT, POWER_LOW, POWER_MEDIUM, or 252 * POWER_HIGH. 253 */ 254 public void setPowerRequirement(int level) { 255 if (level < NO_REQUIREMENT || level > POWER_HIGH) { 256 throw new IllegalArgumentException("level=" + level); 257 } 258 mPowerRequirement = level; 259 } 260 261 /** 262 * Returns a constant indicating the desired power requirement. The 263 * returned 264 */ 265 public int getPowerRequirement() { 266 return mPowerRequirement; 267 } 268 269 /** 270 * Indicates whether the provider is allowed to incur monetary cost. 271 */ 272 public void setCostAllowed(boolean costAllowed) { 273 mCostAllowed = costAllowed; 274 } 275 276 /** 277 * Returns whether the provider is allowed to incur monetary cost. 278 */ 279 public boolean isCostAllowed() { 280 return mCostAllowed; 281 } 282 283 /** 284 * Indicates whether the provider must provide altitude information. 285 * Not all fixes are guaranteed to contain such information. 286 */ 287 public void setAltitudeRequired(boolean altitudeRequired) { 288 mAltitudeRequired = altitudeRequired; 289 } 290 291 /** 292 * Returns whether the provider must provide altitude information. 293 * Not all fixes are guaranteed to contain such information. 294 */ 295 public boolean isAltitudeRequired() { 296 return mAltitudeRequired; 297 } 298 299 /** 300 * Indicates whether the provider must provide speed information. 301 * Not all fixes are guaranteed to contain such information. 302 */ 303 public void setSpeedRequired(boolean speedRequired) { 304 mSpeedRequired = speedRequired; 305 } 306 307 /** 308 * Returns whether the provider must provide speed information. 309 * Not all fixes are guaranteed to contain such information. 310 */ 311 public boolean isSpeedRequired() { 312 return mSpeedRequired; 313 } 314 315 /** 316 * Indicates whether the provider must provide bearing information. 317 * Not all fixes are guaranteed to contain such information. 318 */ 319 public void setBearingRequired(boolean bearingRequired) { 320 mBearingRequired = bearingRequired; 321 } 322 323 /** 324 * Returns whether the provider must provide bearing information. 325 * Not all fixes are guaranteed to contain such information. 326 */ 327 public boolean isBearingRequired() { 328 return mBearingRequired; 329 } 330 331 public static final Parcelable.Creator<Criteria> CREATOR = 332 new Parcelable.Creator<Criteria>() { 333 @Override 334 public Criteria createFromParcel(Parcel in) { 335 Criteria c = new Criteria(); 336 c.mHorizontalAccuracy = in.readInt(); 337 c.mVerticalAccuracy = in.readInt(); 338 c.mSpeedAccuracy = in.readInt(); 339 c.mBearingAccuracy = in.readInt(); 340 c.mPowerRequirement = in.readInt(); 341 c.mAltitudeRequired = in.readInt() != 0; 342 c.mBearingRequired = in.readInt() != 0; 343 c.mSpeedRequired = in.readInt() != 0; 344 c.mCostAllowed = in.readInt() != 0; 345 return c; 346 } 347 348 @Override 349 public Criteria[] newArray(int size) { 350 return new Criteria[size]; 351 } 352 }; 353 354 @Override 355 public int describeContents() { 356 return 0; 357 } 358 359 @Override 360 public void writeToParcel(Parcel parcel, int flags) { 361 parcel.writeInt(mHorizontalAccuracy); 362 parcel.writeInt(mVerticalAccuracy); 363 parcel.writeInt(mSpeedAccuracy); 364 parcel.writeInt(mBearingAccuracy); 365 parcel.writeInt(mPowerRequirement); 366 parcel.writeInt(mAltitudeRequired ? 1 : 0); 367 parcel.writeInt(mBearingRequired ? 1 : 0); 368 parcel.writeInt(mSpeedRequired ? 1 : 0); 369 parcel.writeInt(mCostAllowed ? 1 : 0); 370 } 371 372 private static String powerToString(int power) { 373 switch (power) { 374 case NO_REQUIREMENT: 375 return "NO_REQ"; 376 case POWER_LOW: 377 return "LOW"; 378 case POWER_MEDIUM: 379 return "MEDIUM"; 380 case POWER_HIGH: 381 return "HIGH"; 382 default: 383 return "???"; 384 } 385 } 386 387 private static String accuracyToString(int accuracy) { 388 switch (accuracy) { 389 case NO_REQUIREMENT: 390 return "---"; 391 case ACCURACY_HIGH: 392 return "HIGH"; 393 case ACCURACY_MEDIUM: 394 return "MEDIUM"; 395 case ACCURACY_LOW: 396 return "LOW"; 397 default: 398 return "???"; 399 } 400 } 401 402 @Override 403 public String toString() { 404 StringBuilder s = new StringBuilder(); 405 s.append("Criteria[power=").append(powerToString(mPowerRequirement)); 406 s.append(" acc=").append(accuracyToString(mHorizontalAccuracy)); 407 s.append(']'); 408 return s.toString(); 409 } 410} 411