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