src.android.location.Criteria Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of android-all Show documentation
Show all versions of android-all Show documentation
A library jar that provides APIs for Applications written for the Google Android Platform.
/*
* Copyright (C) 2007 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.location;
import android.annotation.IntDef;
import android.annotation.NonNull;
import android.os.Parcel;
import android.os.Parcelable;
import com.android.internal.util.Preconditions;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
/**
* A class indicating the application criteria for selecting a
* location provider. Providers may be ordered according to accuracy,
* power usage, ability to report altitude, speed, bearing, and monetary
* cost.
*/
public class Criteria implements Parcelable {
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef({NO_REQUIREMENT, POWER_LOW, POWER_MEDIUM, POWER_HIGH})
public @interface PowerRequirement {
}
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef({NO_REQUIREMENT, ACCURACY_LOW, ACCURACY_MEDIUM, ACCURACY_HIGH})
public @interface AccuracyRequirement {
}
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef({NO_REQUIREMENT, ACCURACY_FINE, ACCURACY_COARSE})
public @interface LocationAccuracyRequirement {
}
/**
* A constant indicating that the application does not choose to
* place requirement on a particular feature.
*/
public static final int NO_REQUIREMENT = 0;
/**
* A constant indicating a low power requirement.
*/
public static final int POWER_LOW = 1;
/**
* A constant indicating a medium power requirement.
*/
public static final int POWER_MEDIUM = 2;
/**
* A constant indicating a high power requirement.
*/
public static final int POWER_HIGH = 3;
/**
* A constant indicating a finer location accuracy requirement
*/
public static final int ACCURACY_FINE = 1;
/**
* A constant indicating an approximate accuracy requirement
*/
public static final int ACCURACY_COARSE = 2;
/**
* A constant indicating a low location accuracy requirement
* - may be used for horizontal, altitude, speed or bearing accuracy.
* For horizontal and vertical position this corresponds roughly to
* an accuracy of greater than 500 meters.
*/
public static final int ACCURACY_LOW = 1;
/**
* A constant indicating a medium accuracy requirement
* - currently used only for horizontal accuracy.
* For horizontal position this corresponds roughly to to an accuracy
* of between 100 and 500 meters.
*/
public static final int ACCURACY_MEDIUM = 2;
/**
* a constant indicating a high accuracy requirement
* - may be used for horizontal, altitude, speed or bearing accuracy.
* For horizontal and vertical position this corresponds roughly to
* an accuracy of less than 100 meters.
*/
public static final int ACCURACY_HIGH = 3;
private int mHorizontalAccuracy = NO_REQUIREMENT;
private int mVerticalAccuracy = NO_REQUIREMENT;
private int mSpeedAccuracy = NO_REQUIREMENT;
private int mBearingAccuracy = NO_REQUIREMENT;
private int mPowerRequirement = NO_REQUIREMENT;
private boolean mAltitudeRequired = false;
private boolean mBearingRequired = false;
private boolean mSpeedRequired = false;
private boolean mCostAllowed = false;
/**
* Constructs a new Criteria object. The new object will have no
* requirements on accuracy, power, or response time; will not
* require altitude, speed, or bearing; and will not allow monetary
* cost.
*/
public Criteria() {
}
/**
* Constructs a new Criteria object that is a copy of the given criteria.
*/
public Criteria(Criteria criteria) {
mHorizontalAccuracy = criteria.mHorizontalAccuracy;
mVerticalAccuracy = criteria.mVerticalAccuracy;
mSpeedAccuracy = criteria.mSpeedAccuracy;
mBearingAccuracy = criteria.mBearingAccuracy;
mPowerRequirement = criteria.mPowerRequirement;
mAltitudeRequired = criteria.mAltitudeRequired;
mBearingRequired = criteria.mBearingRequired;
mSpeedRequired = criteria.mSpeedRequired;
mCostAllowed = criteria.mCostAllowed;
}
/**
* Indicates the desired horizontal accuracy (latitude and longitude). Accuracy may be
* {@link #ACCURACY_LOW}, {@link #ACCURACY_MEDIUM}, {@link #ACCURACY_HIGH} or
* {@link #NO_REQUIREMENT}. More accurate location may consume more power and may take longer.
*
* @throws IllegalArgumentException if accuracy is not one of the supported constants
*/
public void setHorizontalAccuracy(@AccuracyRequirement int accuracy) {
mHorizontalAccuracy = Preconditions.checkArgumentInRange(accuracy, NO_REQUIREMENT,
ACCURACY_HIGH, "accuracy");
}
/**
* Returns a constant indicating the desired horizontal accuracy (latitude and longitude).
*
* @see #setHorizontalAccuracy(int)
*/
@AccuracyRequirement
public int getHorizontalAccuracy() {
return mHorizontalAccuracy;
}
/**
* Indicates the desired vertical accuracy (altitude). Accuracy may be {@link #ACCURACY_LOW},
* {@link #ACCURACY_MEDIUM}, {@link #ACCURACY_HIGH} or {@link #NO_REQUIREMENT}. More accurate
* location may consume more power and may take longer.
*
* @throws IllegalArgumentException if accuracy is not one of the supported constants
*/
public void setVerticalAccuracy(@AccuracyRequirement int accuracy) {
mVerticalAccuracy = Preconditions.checkArgumentInRange(accuracy, NO_REQUIREMENT,
ACCURACY_HIGH, "accuracy");
}
/**
* Returns a constant indicating the desired vertical accuracy (altitude).
*
* @see #setVerticalAccuracy(int)
*/
@AccuracyRequirement
public int getVerticalAccuracy() {
return mVerticalAccuracy;
}
/**
* Indicates the desired speed accuracy. Accuracy may be {@link #ACCURACY_LOW},
* {@link #ACCURACY_MEDIUM}, {@link #ACCURACY_HIGH}, or {@link #NO_REQUIREMENT}. More accurate
* location may consume more power and may take longer.
*
* @throws IllegalArgumentException if accuracy is not one of the supported constants
*/
public void setSpeedAccuracy(@AccuracyRequirement int accuracy) {
mSpeedAccuracy = Preconditions.checkArgumentInRange(accuracy, NO_REQUIREMENT, ACCURACY_HIGH,
"accuracy");
}
/**
* Returns a constant indicating the desired speed accuracy.
*
* @see #setSpeedAccuracy(int)
*/
@AccuracyRequirement
public int getSpeedAccuracy() {
return mSpeedAccuracy;
}
/**
* Indicates the desired bearing accuracy. Accuracy may be {@link #ACCURACY_LOW},
* {@link #ACCURACY_MEDIUM}, {@link #ACCURACY_HIGH}, or {@link #NO_REQUIREMENT}. More accurate
* location may consume more power and may take longer.
*
* @throws IllegalArgumentException if accuracy is not one of the supported constants
*/
public void setBearingAccuracy(@AccuracyRequirement int accuracy) {
mBearingAccuracy = Preconditions.checkArgumentInRange(accuracy, NO_REQUIREMENT,
ACCURACY_HIGH, "accuracy");
}
/**
* Returns a constant indicating the desired bearing accuracy.
*
* @see #setBearingAccuracy(int)
*/
@AccuracyRequirement
public int getBearingAccuracy() {
return mBearingAccuracy;
}
/**
* Indicates the desired accuracy for latitude and longitude. Accuracy may be
* {@link #ACCURACY_FINE} or {@link #ACCURACY_COARSE}. More accurate location may consume more
* power and may take longer.
*
* @throws IllegalArgumentException if accuracy is not one of the supported constants
*/
public void setAccuracy(@LocationAccuracyRequirement int accuracy) {
Preconditions.checkArgumentInRange(accuracy, NO_REQUIREMENT, ACCURACY_COARSE, "accuracy");
switch (accuracy) {
case NO_REQUIREMENT:
setHorizontalAccuracy(NO_REQUIREMENT);
break;
case ACCURACY_FINE:
setHorizontalAccuracy(ACCURACY_HIGH);
break;
case ACCURACY_COARSE:
setHorizontalAccuracy(ACCURACY_LOW);
break;
}
}
/**
* Returns a constant indicating desired accuracy of location.
*
* @see #setAccuracy(int)
*/
@LocationAccuracyRequirement
public int getAccuracy() {
if (mHorizontalAccuracy >= ACCURACY_HIGH) {
return ACCURACY_FINE;
} else {
return ACCURACY_COARSE;
}
}
/**
* Indicates the desired maximum power requirement. The power requirement parameter may be
* {@link #NO_REQUIREMENT}, {@link #POWER_LOW}, {@link #POWER_MEDIUM}, or {@link #POWER_HIGH}.
*/
public void setPowerRequirement(@PowerRequirement int powerRequirement) {
mPowerRequirement = Preconditions.checkArgumentInRange(powerRequirement, NO_REQUIREMENT,
POWER_HIGH, "powerRequirement");
}
/**
* Returns a constant indicating the desired maximum power requirement.
*
* @see #setPowerRequirement(int)
*/
@PowerRequirement
public int getPowerRequirement() {
return mPowerRequirement;
}
/**
* Indicates whether the provider is allowed to incur monetary cost.
*/
public void setCostAllowed(boolean costAllowed) {
mCostAllowed = costAllowed;
}
/**
* Returns whether the provider is allowed to incur monetary cost.
*/
public boolean isCostAllowed() {
return mCostAllowed;
}
/**
* Indicates whether the provider must provide altitude information. Not all fixes are
* guaranteed to contain such information.
*/
public void setAltitudeRequired(boolean altitudeRequired) {
mAltitudeRequired = altitudeRequired;
}
/**
* Returns whether the provider must provide altitude information.
*
* @see #setAltitudeRequired(boolean)
*/
public boolean isAltitudeRequired() {
return mAltitudeRequired;
}
/**
* Indicates whether the provider must provide speed information. Not all fixes are guaranteed
* to contain such information.
*/
public void setSpeedRequired(boolean speedRequired) {
mSpeedRequired = speedRequired;
}
/**
* Returns whether the provider must provide speed information.
*
* @see #setSpeedRequired(boolean)
*/
public boolean isSpeedRequired() {
return mSpeedRequired;
}
/**
* Indicates whether the provider must provide bearing information. Not all fixes are guaranteed
* to contain such information.
*/
public void setBearingRequired(boolean bearingRequired) {
mBearingRequired = bearingRequired;
}
/**
* Returns whether the provider must provide bearing information.
*
* @see #setBearingRequired(boolean)
*/
public boolean isBearingRequired() {
return mBearingRequired;
}
@NonNull
public static final Parcelable.Creator CREATOR =
new Parcelable.Creator() {
@Override
public Criteria createFromParcel(Parcel in) {
Criteria c = new Criteria();
c.mHorizontalAccuracy = in.readInt();
c.mVerticalAccuracy = in.readInt();
c.mSpeedAccuracy = in.readInt();
c.mBearingAccuracy = in.readInt();
c.mPowerRequirement = in.readInt();
c.mAltitudeRequired = in.readInt() != 0;
c.mBearingRequired = in.readInt() != 0;
c.mSpeedRequired = in.readInt() != 0;
c.mCostAllowed = in.readInt() != 0;
return c;
}
@Override
public Criteria[] newArray(int size) {
return new Criteria[size];
}
};
@Override
public int describeContents() {
return 0;
}
@Override
public void writeToParcel(Parcel parcel, int flags) {
parcel.writeInt(mHorizontalAccuracy);
parcel.writeInt(mVerticalAccuracy);
parcel.writeInt(mSpeedAccuracy);
parcel.writeInt(mBearingAccuracy);
parcel.writeInt(mPowerRequirement);
parcel.writeInt(mAltitudeRequired ? 1 : 0);
parcel.writeInt(mBearingRequired ? 1 : 0);
parcel.writeInt(mSpeedRequired ? 1 : 0);
parcel.writeInt(mCostAllowed ? 1 : 0);
}
@Override
public String toString() {
StringBuilder s = new StringBuilder();
s.append("Criteria[");
s.append("power=").append(requirementToString(mPowerRequirement)).append(", ");
s.append("accuracy=").append(requirementToString(mHorizontalAccuracy));
if (mVerticalAccuracy != NO_REQUIREMENT) {
s.append(", verticalAccuracy=").append(requirementToString(mVerticalAccuracy));
}
if (mSpeedAccuracy != NO_REQUIREMENT) {
s.append(", speedAccuracy=").append(requirementToString(mSpeedAccuracy));
}
if (mBearingAccuracy != NO_REQUIREMENT) {
s.append(", bearingAccuracy=").append(requirementToString(mBearingAccuracy));
}
if (mAltitudeRequired || mBearingRequired || mSpeedRequired) {
s.append(", required=[");
if (mAltitudeRequired) {
s.append("altitude, ");
}
if (mBearingRequired) {
s.append("bearing, ");
}
if (mSpeedRequired) {
s.append("speed, ");
}
s.setLength(s.length() - 2);
s.append("]");
}
if (mCostAllowed) {
s.append(", costAllowed");
}
s.append(']');
return s.toString();
}
private static String requirementToString(int power) {
switch (power) {
case NO_REQUIREMENT:
return "None";
//case ACCURACY_LOW:
case POWER_LOW:
return "Low";
//case ACCURACY_MEDIUM:
case POWER_MEDIUM:
return "Medium";
//case ACCURACY_HIGH:
case POWER_HIGH:
return "High";
default:
return "???";
}
}
}