Add javadoc for new location API's. (4e31c4ff) · Commits · e / os / android_frameworks_base

api/current.txt

+3 −3

Original line number	Diff line number	Diff line
		@@ -10549,7 +10549,7 @@ package android.location {
		method public android.os.Bundle getExtras();
		method public double getLatitude();
		method public double getLongitude();
		method public java.lang.String getProvider();
		method public deprecated java.lang.String getProvider();
		method public float getSpeed();
		method public long getTime();
		method public boolean hasAccuracy();
		@@ -10587,6 +10587,7 @@ package android.location {
		}

		public class LocationManager {
		method public void addGeofence(android.location.LocationRequest, android.location.Geofence, android.app.PendingIntent);
		method public boolean addGpsStatusListener(android.location.GpsStatus.Listener);
		method public boolean addNmeaListener(android.location.GpsStatus.NmeaListener);
		method public deprecated void addProximityAlert(double, double, float, long, android.app.PendingIntent);
		@@ -10598,7 +10599,7 @@ package android.location {
		method public deprecated java.lang.String getBestProvider(android.location.Criteria, boolean);
		method public android.location.GpsStatus getGpsStatus(android.location.GpsStatus);
		method public deprecated android.location.Location getLastKnownLocation(java.lang.String);
		method public android.location.Location getLastLocation(android.location.LocationRequest);
		method public android.location.Location getLastLocation();
		method public deprecated android.location.LocationProvider getProvider(java.lang.String);
		method public deprecated java.util.List<java.lang.String> getProviders(boolean);
		method public deprecated java.util.List<java.lang.String> getProviders(android.location.Criteria, boolean);
		@@ -10611,7 +10612,6 @@ package android.location {
		method public deprecated void removeTestProvider(java.lang.String);
		method public void removeUpdates(android.location.LocationListener);
		method public void removeUpdates(android.app.PendingIntent);
		method public void requestGeofence(android.location.LocationRequest, android.location.Geofence, android.app.PendingIntent);
		method public deprecated void requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener);
		method public deprecated void requestLocationUpdates(java.lang.String, long, float, android.location.LocationListener, android.os.Looper);
		method public deprecated void requestLocationUpdates(long, float, android.location.Criteria, android.location.LocationListener, android.os.Looper);

location/java/android/location/Criteria.java

+3 −1

Original line number	Diff line number	Diff line
		@@ -24,7 +24,9 @@ import android.os.Parcelable;
		* location provider. Providers maybe ordered according to accuracy,
		* power usage, ability to report altitude, speed,
		* and bearing, and monetary cost.
		* @deprecated {@link LocationRequest} instead
		*
		* @deprecated use {@link LocationRequest} instead, and also see notes
		* at {@link LocationManager}
		*/
		@Deprecated
		public class Criteria implements Parcelable {

location/java/android/location/Geofence.java

+9 −1

Original line number	Diff line number	Diff line
		@@ -20,7 +20,11 @@ import android.os.Parcel;
		import android.os.Parcelable;

		/**
		* Represents a Geofence
		* Represents a geographical boundary, also known as a geofence.
		*
		* <p>Currently only circular geofences are supported, but this object
		* is opaque so could be used in the future to represent polygons or other
		* shapes.
		*/
		public final class Geofence implements Parcelable {
		/** @hide */
		@@ -33,6 +37,7 @@ public final class Geofence implements Parcelable {

		/**
		* Create a horizontal, circular geofence.
		*
		* @param latitude latitude in degrees
		* @param longitude longitude in degrees
		* @param radius radius in meters
		@@ -152,6 +157,9 @@ public final class Geofence implements Parcelable {
		return result;
		}

		/**
		* Two geofences are equal if they have identical properties.
		*/
		@Override
		public boolean equals(Object obj) {
		if (this == obj)

location/java/android/location/Location.java

+140 −85

Original line number	Diff line number	Diff line
		@@ -27,15 +27,15 @@ import java.text.DecimalFormat;
		import java.util.StringTokenizer;

		/**
		* A class representing a geographic location sensed at a particular
		* time (a "fix"). A location consists of a latitude and longitude, a
		* UTC timestamp. and optionally information on altitude, speed, and
		* bearing.
		* A data class representing a geographic location.
		*
		* <p> Information specific to a particular provider or class of
		* providers may be communicated to the application using getExtras,
		* which returns a Bundle of key/value pairs. Each provider will only
		* provide those entries for which information is available.
		* <p>A location can consist of a latitude, longitude, timestamp,
		* and other information such as bearing, altitude and velocity.
		*
		* <p>All locations generated by the {@link 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.
		*/
		public class Location implements Parcelable {
		/**
		@@ -86,20 +86,19 @@ public class Location implements Parcelable {
		private float[] mResults = new float[2];

		/**
		* Constructs a new Location. By default, time, latitude,
		* longitude, and numSatellites are 0; hasAltitude, hasSpeed, and
		* hasBearing are false; and there is no extra information.
		* Construct a new Location with a named provider.
		*
		* <p>By default time, latitude and longitude are 0, and the location
		* has no bearing, altitude, speed, accuracy or extras.
		*
		* @param provider the name of the location provider that generated this
		* location fix.
		* @param provider the name of the provider that generated this location
		*/
		public Location(String provider) {
		mProvider = provider;
		}

		/**
		* Constructs a new Location object that is a copy of the given
		* location.
		* Construct a new Location object that is copied from an existing one.
		*/
		public Location(Location l) {
		set(l);
		@@ -447,9 +446,19 @@ public class Location implements Parcelable {
		}

		/**
		* Returns the name of the provider that generated this fix,
		* or null if it is not associated with a provider.
		* Returns the name of the provider that generated this fix.
		*
		* <p class="note">At API version 17 we deprecated {@link LocationProvider}
		* and all API methods that request a provider by name. The new API methods
		* will produce locations that could come from different sources, and even
		* locations that are fused from several sources. So you should generally
		* not care what provider is associated with a location object.
		*
		* @return the provider, or null if it has not been set
		*
		* @deprecated locations can now be sourced from many providers, or even fused
		*/
		@Deprecated
		public String getProvider() {
		return mProvider;
		}
		@@ -462,16 +471,19 @@ public class Location implements Parcelable {
		}

		/**
		* Return the UTC time of this fix, in milliseconds since January 1,
		* 1970.
		* Return the UTC time of this fix, in milliseconds since January 1, 1970.
		*
		* <p>Note that the UTC time on a device is not monotonic: it
		* can jump forwards or backwards unpredictably. So always use
		* {@link #getElapsedRealtimeNano()} when calculating time deltas.
		* <p>On the other hand, {@link #getTime()} is useful for presenting
		* {@link #getElapsedRealtimeNano} when calculating time deltas.
		*
		* <p>On the other hand, {@link #getTime} is useful for presenting
		* a human readable time to the user, or for carefully comparing
		* location fixes across reboot or across devices.
		* <p>This method will always return a valid timestamp on
		* Locations generated by a {@link LocationProvider}.
		*
		* <p>All locations generated by the {@link LocationManager}
		* are guaranteed to have a valid UTC time, however remember that
		* the system time may have changed since the location was generated.
		*
		* @return time of fix, in milliseconds since January 1, 1970.
		*/
		@@ -491,13 +503,16 @@ public class Location implements Parcelable {

		/**
		* Return the time of this fix, in elapsed real-time since system boot.
		*
		* <p>This value can be reliably compared to
		* {@link android.os.SystemClock#elapsedRealtimeNano()},
		* to calculate the age of a fix, and to compare Location fixes, since
		* elapsed real-time is guaranteed monotonic for each system boot, and
		* continues to increment even when the system is in deep sleep.
		* <p>This method will always return a valid timestamp on
		* Locations generated by a {@link LocationProvider}.
		* {@link android.os.SystemClock#elapsedRealtimeNano},
		* 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 {@link #getTime}.
		*
		* <p>All locations generated by the {@link LocationManager}
		* are guaranteed to have a valid elapsed real-time.
		*
		* @return elapsed real-time of fix, in nanoseconds since system boot.
		*/
		@@ -515,56 +530,59 @@ public class Location implements Parcelable {
		}

		/**
		* Return the latitude of this fix.
		* <p>This method will always return a valid latitude on
		* Locations generated by a {@link LocationProvider}.
		* Get the latitude, in degrees.
		*
		* <p>All locations generated by the {@link LocationManager}
		* will have a valid latitude.
		*/
		public double getLatitude() {
		return mLatitude;
		}

		/**
		* Sets the latitude of this fix.
		* Set the latitude, in degrees.
		*/
		public void setLatitude(double latitude) {
		mLatitude = latitude;
		}

		/**
		* Return the longitude of this fix.
		* <p>This method will always return a valid longitude on
		* Locations generated by a {@link LocationProvider}.
		* Get the longitude, in degrees.
		*
		* <p>All locations generated by the {@link LocationManager}
		* will have a valid longitude.
		*/
		public double getLongitude() {
		return mLongitude;
		}

		/**
		* Sets the longitude of this fix.
		* Set the longitude, in degrees.
		*/
		public void setLongitude(double longitude) {
		mLongitude = longitude;
		}

		/**
		* Returns true if this fix contains altitude information, false
		* otherwise.
		* True if this location has an altitude.
		*/
		public boolean hasAltitude() {
		return mHasAltitude;
		}

		/**
		* Returns the altitude of this fix. If {@link #hasAltitude} is false,
		* 0.0f is returned.
		* Get the altitude if available, in meters above sea level.
		*
		* <p>If this location does not have an altitude then 0.0 is returned.
		*/
		public double getAltitude() {
		return mAltitude;
		}

		/**
		* Sets the altitude of this fix. Following this call,
		* hasAltitude() will return true.
		* Set the altitude, in meters above sea level.
		*
		* <p>Following this call {@link #hasAltitude} will return true.
		*/
		public void setAltitude(double altitude) {
		mAltitude = altitude;
		@@ -572,8 +590,10 @@ public class Location implements Parcelable {
		}

		/**
		* Clears the altitude of this fix. Following this call,
		* hasAltitude() will return false.
		* Remove the altitude from this location.
		*
		* <p>Following this call {@link #hasAltitude} will return false,
		* and {@link #getAltitude} will return 0.0.
		*/
		public void removeAltitude() {
		mAltitude = 0.0f;
		@@ -581,24 +601,25 @@ public class Location implements Parcelable {
		}

		/**
		* Returns true if this fix contains speed information, false
		* otherwise. The default implementation returns false.
		* True if this location has a speed.
		*/
		public boolean hasSpeed() {
		return mHasSpeed;
		}

		/**
		* Returns the speed of the device over ground in meters/second.
		* If hasSpeed() is false, 0.0f is returned.
		* Get the speed if it is available, in meters/second over ground.
		*
		* <p>If this location does not have a speed then 0.0 is returned.
		*/
		public float getSpeed() {
		return mSpeed;
		}

		/**
		* Sets the speed of this fix, in meters/second. Following this
		* call, hasSpeed() will return true.
		* Set the speed, in meters/second over ground.
		*
		* <p>Following this call {@link #hasSpeed} will return true.
		*/
		public void setSpeed(float speed) {
		mSpeed = speed;
		@@ -606,8 +627,10 @@ public class Location implements Parcelable {
		}

		/**
		* Clears the speed of this fix. Following this call, hasSpeed()
		* will return false.
		* Remove the speed from this location.
		*
		* <p>Following this call {@link #hasSpeed} will return false,
		* and {@link #getSpeed} will return 0.0.
		*/
		public void removeSpeed() {
		mSpeed = 0.0f;
		@@ -615,24 +638,32 @@ public class Location implements Parcelable {
		}

		/**
		* Returns true if the provider is able to report bearing information,
		* false otherwise. The default implementation returns false.
		* True if this location has a bearing.
		*/
		public boolean hasBearing() {
		return mHasBearing;
		}

		/**
		* Returns the direction of travel in degrees East of true
		* North. If hasBearing() is false, 0.0 is returned.
		* Get the bearing, in degrees.
		*
		* <p>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.
		*
		* <p>If this location does not have a bearing then 0.0 is returned.
		*/
		public float getBearing() {
		return mBearing;
		}

		/**
		* Sets the bearing of this fix. Following this call, hasBearing()
		* will return true.
		* Set the bearing, in degrees.
		*
		* <p>Bearing is the horizontal direction of travel of this device,
		* and is not related to the device orientation.
		*
		* <p>The input will be wrapped into the range (0.0, 360.0].
		*/
		public void setBearing(float bearing) {
		while (bearing < 0.0f) {
		@@ -646,8 +677,10 @@ public class Location implements Parcelable {
		}

		/**
		* Clears the bearing of this fix. Following this call, hasBearing()
		* will return false.
		* Remove the bearing from this location.
		*
		* <p>Following this call {@link #hasBearing} will return false,
		* and {@link #getBearing} will return 0.0.
		*/
		public void removeBearing() {
		mBearing = 0.0f;
		@@ -655,35 +688,47 @@ public class Location implements Parcelable {
		}

		/**
		* Return true if this Location has an associated accuracy.
		* <p>All Location objects generated by a {@link LocationProvider}
		* will have an accuracy.
		* True if this location has an accuracy.
		*
		* <p>All locations generated by the {@link LocationManager} have an
		* accuracy.
		*/
		public boolean hasAccuracy() {
		return mHasAccuracy;
		}

		/**
		* Return the accuracy of this Location fix.
		* <p>Accuracy is measured in meters, and indicates the
		* radius of 95% confidence.
		* In other words, there is a 95% probability that the
		* true location is within a circle centered at the reported
		* location, with radius of the reported accuracy.
		* <p>This is only a measure of horizontal accuracy, and does
		* not indicate the accuracy of bearing, velocity or altitude
		* if those are included in this Location.
		* <p>If {@link #hasAccuracy} is false, 0.0 is returned.
		* <p>All Location object generated by a {@link LocationProvider}
		* will have a valid accuracy.
		* Get the estimated accuracy of this location, in meters.
		*
		* <p>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.
		*
		* <p>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.
		*
		* <p>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.
		*
		* <p>If this location does not have an accuracy, then 0.0 is returned.
		* All locations generated by the {@link LocationManager} include
		* an accuracy.
		*/
		public float getAccuracy() {
		return mAccuracy;
		}

		/**
		* Sets the accuracy of this fix. Following this call, hasAccuracy()
		* will return true.
		* Set the estimated accuracy of this location, meters.
		*
		* <p>See {@link #getAccuracy} for the definition of accuracy.
		*
		* <p>Following this call {@link #hasAccuracy} will return true.
		*/
		public void setAccuracy(float accuracy) {
		mAccuracy = accuracy;
		@@ -691,8 +736,10 @@ public class Location implements Parcelable {
		}

		/**
		* Clears the accuracy of this fix. Following this call, hasAccuracy()
		* will return false.
		* Remove the accuracy from this location.
		*
		* <p>Following this call {@link #hasAccuracy} will return false, and
		* {@link #getAccuracy} will return 0.0.
		*/
		public void removeAccuracy() {
		mAccuracy = 0.0f;
		@@ -700,8 +747,14 @@ public class Location implements Parcelable {
		}

		/**
		* Return true if this Location object has enough data set to
		* be considered a valid fix from a {@link LocationProvider}.
		* Return true if this Location object is complete.
		*
		* <p>A location object is currently considered complete if it has
		* a valid provider, accuracy, wall-clock time and elapsed real-time.
		*
		* <p>All locations supplied by the {@link LocationManager} to
		* applications must be complete.
		*
		* @see #makeComplete
		* @hide
		*/
		@@ -714,9 +767,11 @@ public class Location implements Parcelable {
		}

		/**
		* Helper to fill in incomplete fields.
		* Only use this to assist in backwards compatibility
		* with Location objects received from applications.
		* Helper to fill incomplete fields.
		*
		* <p>Used to assist in backwards compatibility with
		* Location objects received from applications.
		*
		* @see #isComplete
		* @hide
		*/