public class Location extends Object implements Parcelable
A location can consist of a latitude, longitude, timestamp, and other information such as bearing, altitude and velocity.
All locations generated by the LocationManager
are
guaranteed to have a valid latitude, longitude, and timestamp
(both UTC time and elapsed real-time since boot), all other
parameters are optional.
Parcelable.ClassLoaderCreator<T>, Parcelable.Creator<T>
Modifier and Type | Field and Description |
---|---|
static Parcelable.Creator<Location> |
CREATOR |
static String |
EXTRA_COARSE_LOCATION
Bundle key for a version of the location that has been fed through
LocationFudger.
|
static String |
EXTRA_NO_GPS_LOCATION
Bundle key for a version of the location containing no GPS data.
|
static int |
FORMAT_DEGREES
Constant used to specify formatting of a latitude or longitude
in the form "[+-]DDD.DDDDD where D indicates degrees.
|
static int |
FORMAT_MINUTES
Constant used to specify formatting of a latitude or longitude
in the form "[+-]DDD:MM.MMMMM" where D indicates degrees and
M indicates minutes of arc (1 minute = 1/60th of a degree).
|
static int |
FORMAT_SECONDS
Constant used to specify formatting of a latitude or longitude
in the form "DDD:MM:SS.SSSSS" where D indicates degrees, M
indicates minutes of arc, and S indicates seconds of arc (1
minute = 1/60th of a degree, 1 second = 1/3600th of a degree).
|
CONTENTS_FILE_DESCRIPTOR, PARCELABLE_ELIDE_DUPLICATES, PARCELABLE_WRITE_RETURN_VALUE
Constructor and Description |
---|
Location(Location l)
Construct a new Location object that is copied from an existing one.
|
Location(String provider)
Construct a new Location with a named provider.
|
Modifier and Type | Method and Description |
---|---|
float |
bearingTo(Location dest)
Returns the approximate initial bearing in degrees East of true
North when traveling along the shortest path between this
location and the given location.
|
static String |
convert(double coordinate,
int outputType)
Converts a coordinate to a String representation.
|
static double |
convert(String coordinate)
Converts a String in one of the formats described by
FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS into a
double.
|
int |
describeContents()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation.
|
static void |
distanceBetween(double startLatitude,
double startLongitude,
double endLatitude,
double endLongitude,
float[] results)
Computes the approximate distance in meters between two
locations, and optionally the initial and final bearings of the
shortest path between them.
|
float |
distanceTo(Location dest)
Returns the approximate distance in meters between this
location and the given location.
|
void |
dump(Printer pw,
String prefix) |
float |
getAccuracy()
Get the estimated accuracy of this location, in meters.
|
double |
getAltitude()
Get the altitude if available, in meters above the WGS 84 reference
ellipsoid.
|
float |
getBearing()
Get the bearing, in degrees.
|
long |
getElapsedRealtimeNanos()
Return the time of this fix, in elapsed real-time since system boot.
|
Location |
getExtraLocation(String key)
Returns one of the optional extra
Location s that can be attached
to this Location. |
Bundle |
getExtras()
Returns additional provider-specific information about the
location fix as a Bundle.
|
double |
getLatitude()
Get the latitude, in degrees.
|
double |
getLongitude()
Get the longitude, in degrees.
|
String |
getProvider()
Returns the name of the provider that generated this fix.
|
float |
getSpeed()
Get the speed if it is available, in meters/second over ground.
|
long |
getTime()
Return the UTC time of this fix, in milliseconds since January 1, 1970.
|
boolean |
hasAccuracy()
True if this location has an accuracy.
|
boolean |
hasAltitude()
True if this location has an altitude.
|
boolean |
hasBearing()
True if this location has a bearing.
|
boolean |
hasSpeed()
True if this location has a speed.
|
boolean |
isComplete()
Return true if this Location object is complete.
|
boolean |
isFromMockProvider()
Returns true if the Location came from a mock provider.
|
void |
makeComplete()
Helper to fill incomplete fields.
|
void |
removeAccuracy()
Remove the accuracy from this location.
|
void |
removeAltitude()
Remove the altitude from this location.
|
void |
removeBearing()
Remove the bearing from this location.
|
void |
removeSpeed()
Remove the speed from this location.
|
void |
reset()
Clears the contents of the location.
|
void |
set(Location l)
Sets the contents of the location to the values from the given location.
|
void |
setAccuracy(float accuracy)
Set the estimated accuracy of this location, meters.
|
void |
setAltitude(double altitude)
Set the altitude, in meters above the WGS 84 reference ellipsoid.
|
void |
setBearing(float bearing)
Set the bearing, in degrees.
|
void |
setElapsedRealtimeNanos(long time)
Set the time of this fix, in elapsed real-time since system boot.
|
void |
setExtraLocation(String key,
Location value)
Attaches an extra
Location to this Location. |
void |
setExtras(Bundle extras)
Sets the extra information associated with this fix to the
given Bundle.
|
void |
setIsFromMockProvider(boolean isFromMockProvider)
Flag this Location as having come from a mock provider or not.
|
void |
setLatitude(double latitude)
Set the latitude, in degrees.
|
void |
setLongitude(double longitude)
Set the longitude, in degrees.
|
void |
setProvider(String provider)
Sets the name of the provider that generated this fix.
|
void |
setSpeed(float speed)
Set the speed, in meters/second over ground.
|
void |
setTime(long time)
Set the UTC time of this fix, in milliseconds since January 1,
1970.
|
String |
toString()
Returns a string representation of the object.
|
void |
writeToParcel(Parcel parcel,
int flags)
Flatten this object in to a Parcel.
|
public static final int FORMAT_DEGREES
public static final int FORMAT_MINUTES
public static final int FORMAT_SECONDS
public static final String EXTRA_COARSE_LOCATION
public static final String EXTRA_NO_GPS_LOCATION
public static final Parcelable.Creator<Location> CREATOR
public Location(String provider)
By default time, latitude and longitude are 0, and the location has no bearing, altitude, speed, accuracy or extras.
provider
- the name of the provider that generated this locationpublic Location(Location l)
public void set(Location l)
public void reset()
public static String convert(double coordinate, int outputType)
convert(String)
.IllegalArgumentException
- if coordinate is less than
-180.0, greater than 180.0, or is not a number.IllegalArgumentException
- if outputType is not one of
FORMAT_DEGREES, FORMAT_MINUTES, or FORMAT_SECONDS.public static double convert(String coordinate)
convert(double, int)
.NullPointerException
- if coordinate is nullIllegalArgumentException
- if the coordinate is not
in one of the valid formats.public static void distanceBetween(double startLatitude, double startLongitude, double endLatitude, double endLongitude, float[] results)
The computed distance is stored in results[0]. If results has length 2 or greater, the initial bearing is stored in results[1]. If results has length 3 or greater, the final bearing is stored in results[2].
startLatitude
- the starting latitudestartLongitude
- the starting longitudeendLatitude
- the ending latitudeendLongitude
- the ending longituderesults
- an array of floats to hold the resultsIllegalArgumentException
- if results is null or has length < 1public float distanceTo(Location dest)
dest
- the destination locationpublic float bearingTo(Location dest)
dest
- the destination locationpublic String getProvider()
public void setProvider(String provider)
public long getTime()
Note that the UTC time on a device is not monotonic: it
can jump forwards or backwards unpredictably. So always use
getElapsedRealtimeNanos()
when calculating time deltas.
On the other hand, getTime()
is useful for presenting
a human readable time to the user, or for carefully comparing
location fixes across reboot or across devices.
All locations generated by the LocationManager
are guaranteed to have a valid UTC time, however remember that
the system time may have changed since the location was generated.
public void setTime(long time)
time
- UTC time of this fix, in milliseconds since January 1, 1970public long getElapsedRealtimeNanos()
This value can be reliably compared to
SystemClock.elapsedRealtimeNanos()
,
to calculate the age of a fix and to compare Location fixes. This
is reliable because elapsed real-time is guaranteed monotonic for
each system boot and continues to increment even when the system
is in deep sleep (unlike getTime()
.
All locations generated by the LocationManager
are guaranteed to have a valid elapsed real-time.
public void setElapsedRealtimeNanos(long time)
time
- elapsed real-time of fix, in nanoseconds since system boot.public double getLatitude()
All locations generated by the LocationManager
will have a valid latitude.
public void setLatitude(double latitude)
public double getLongitude()
All locations generated by the LocationManager
will have a valid longitude.
public void setLongitude(double longitude)
public boolean hasAltitude()
public double getAltitude()
If this location does not have an altitude then 0.0 is returned.
public void setAltitude(double altitude)
Following this call hasAltitude()
will return true.
public void removeAltitude()
Following this call hasAltitude()
will return false,
and getAltitude()
will return 0.0.
public boolean hasSpeed()
public float getSpeed()
If this location does not have a speed then 0.0 is returned.
public void setSpeed(float speed)
Following this call hasSpeed()
will return true.
public void removeSpeed()
Following this call hasSpeed()
will return false,
and getSpeed()
will return 0.0.
public boolean hasBearing()
public float getBearing()
Bearing is the horizontal direction of travel of this device, and is not related to the device orientation. It is guaranteed to be in the range (0.0, 360.0] if the device has a bearing.
If this location does not have a bearing then 0.0 is returned.
public void setBearing(float bearing)
Bearing is the horizontal direction of travel of this device, and is not related to the device orientation.
The input will be wrapped into the range (0.0, 360.0].
public void removeBearing()
Following this call hasBearing()
will return false,
and getBearing()
will return 0.0.
public boolean hasAccuracy()
All locations generated by the LocationManager
have an
accuracy.
public float getAccuracy()
We define accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's latitude and longitude, and with a radius equal to the accuracy, then there is a 68% probability that the true location is inside the circle.
In statistical terms, it is assumed that location errors are random with a normal distribution, so the 68% confidence circle represents one standard deviation. Note that in practice, location errors do not always follow such a simple distribution.
This accuracy estimation is only concerned with horizontal accuracy, and does not indicate the accuracy of bearing, velocity or altitude if those are included in this Location.
If this location does not have an accuracy, then 0.0 is returned.
All locations generated by the LocationManager
include
an accuracy.
public void setAccuracy(float accuracy)
See getAccuracy()
for the definition of accuracy.
Following this call hasAccuracy()
will return true.
public void removeAccuracy()
Following this call hasAccuracy()
will return false, and
getAccuracy()
will return 0.0.
public boolean isComplete()
A location object is currently considered complete if it has a valid provider, accuracy, wall-clock time and elapsed real-time.
All locations supplied by the LocationManager
to
applications must be complete.
makeComplete()
public void makeComplete()
Used to assist in backwards compatibility with Location objects received from applications.
isComplete()
public Bundle getExtras()
A number of common key/value pairs are listed below. Providers that use any of the keys on this list must provide the corresponding value as described below.
public void setExtras(Bundle extras)
public String toString()
Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
public int describeContents()
Parcelable
Parcelable.writeToParcel(Parcel, int)
,
the return value of this method must include the
Parcelable.CONTENTS_FILE_DESCRIPTOR
bit.describeContents
in interface Parcelable
Parcelable.CONTENTS_FILE_DESCRIPTOR
public void writeToParcel(Parcel parcel, int flags)
Parcelable
writeToParcel
in interface Parcelable
parcel
- The Parcel in which the object should be written.flags
- Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE
.public Location getExtraLocation(String key)
Location
s that can be attached
to this Location.key
- the key associated with the desired extra Locationpublic void setExtraLocation(String key, Location value)
Location
to this Location.key
- the key associated with the Location extravalue
- the Location to attachpublic boolean isFromMockProvider()
public void setIsFromMockProvider(boolean isFromMockProvider)
isFromMockProvider
- true if this Location came from a mock provider, false otherwise