java.lang.Object | ||
android.location.LocationManager |
This class provides access to the system location services. These services allow applications to obtain periodic updates of the device's geographical location, or to fire an application-specified Intent when the device enters the proximity of a given geographical location.
You do not instantiate this class directly; instead, retrieve it through Context.getSystemService(Context.LOCATION_SERVICE).
Value | ||||
---|---|---|---|---|
String | GPS_PROVIDER | Name of the GPS location provider. | "gps" | |
String | KEY_PROXIMITY_ENTERING | Key used for the Bundle extra holding a boolean indicating whether a proximity alert is entering (true) or exiting (false).. | "entering" | |
String | NETWORK_PROVIDER | Name of the network location provider. | "network" |
void | addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent) | |||||
Sets a proximity alert for the location given by the position (latitude, longitude) and the given radius. | ||||||
void | addTestProvider(String name, boolean requiresNetwork, boolean requiresSatellite, boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude, boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy) | |||||
Creates a mock location provider and adds it to the set of active providers. | ||||||
void | clearTestProviderEnabled(String provider) | |||||
Removes any mock enabled value associated with the given provider. | ||||||
void | clearTestProviderLocation(String provider) | |||||
Removes any mock location associated with the given provider. | ||||||
void | clearTestProviderStatus(String provider) | |||||
Removes any mock status values associated with the given provider. | ||||||
List<String> | getAllProviders() | |||||
Returns a list of the names of all known location providers. | ||||||
String | getBestProvider(Criteria criteria, boolean enabledOnly) | |||||
Returns the name of the provider that best meets the given criteria. | ||||||
Location | getLastKnownLocation(String provider) | |||||
Returns a Location indicating the data from the last known location fix obtained from the given provider. | ||||||
LocationProvider | getProvider(String name) | |||||
Returns the information associated with the location provider of the given name, or null if no provider exists by that name. | ||||||
List<String> | getProviders(Criteria criteria, boolean enabledOnly) | |||||
Returns a list of the names of LocationProviders that satisfy the given criteria, or null if none do. | ||||||
List<String> | getProviders(boolean enabledOnly) | |||||
Returns a list of the names of location providers. | ||||||
boolean | isProviderEnabled(String provider) | |||||
Returns the current enabled/disabled status of the given provider. | ||||||
void | removeProximityAlert(PendingIntent intent) | |||||
Removes the proximity alert with the given PendingIntent. | ||||||
void | removeTestProvider(String provider) | |||||
Removes the mock location provider with the given name. | ||||||
void | removeUpdates(LocationListener listener) | |||||
Removes any current registration for location updates of the current activity with the given LocationListener. | ||||||
void | requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener) | |||||
Registers the current activity to be notified periodically by the named provider. | ||||||
void | requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener, Looper looper) | |||||
Registers the current activity to be notified periodically by the named provider. | ||||||
void | setTestProviderEnabled(String provider, boolean enabled) | |||||
Sets a mock enabled value for the given provider. | ||||||
void | setTestProviderLocation(String provider, Location loc) | |||||
Sets a mock location for the given provider. | ||||||
void | setTestProviderStatus(String provider, int status, Bundle extras, long updateTime) | |||||
Sets mock status values for the given provider. |
The extras Bundle for the GPS location provider can contain the following key/value pairs:
The fired Intent will have a boolean extra added with key KEY_PROXIMITY_ENTERING. If the value is true, the device is entering the proximity region; if false, it is exiting.
Due to the approximate nature of position estimation, if the device passes through the given area briefly, it is possible that no Intent will be fired. Similarly, an Intent could be fired if the device passes very close to the given area but does not actually enter it.
After the number of milliseconds given by the expiration parameter, the location manager will delete this proximity alert and no longer monitor it. A value of -1 indicates that there should be no expiration time.
Internally, this method uses both NETWORK_PROVIDER and GPS_PROVIDER.
latitude | the latitude of the central point of the alert region |
---|---|
longitude | the longitude of the central point of the alert region |
radius | the radius of the central point of the alert region, in meters |
expiration | time for this proximity alert, in milliseconds, or -1 to indicate no expiration |
intent | a PendingIntent that will be used to generate an Intent to fire when entry to or exit from the alert region is detected |
SecurityException | if no permission exists for the required providers. |
---|
name | the provider name |
---|
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if a provider with the given name already exists |
provider | the provider name |
---|
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if no provider with the given name exists |
provider | the provider name |
---|
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if no provider with the given name exists |
provider | the provider name |
---|
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if no provider with the given name exists |
Note that the requirement on monetary cost is not removed in this process.
criteria | the criteria that need to be matched |
---|---|
enabledOnly | if true then only a provider that is currently enabled is returned |
If the provider is currently disabled, null is returned.
provider | the name of the provider |
---|
SecurityException | if no suitable permission is present for the provider. |
---|---|
IllegalArgumentException | if provider is null or doesn't exist |
name | the provider name |
---|
IllegalArgumentException | if name is null |
---|---|
SecurityException | if the caller is not permitted to access the given provider. |
criteria | the criteria that the returned providers must match |
---|---|
enabledOnly | if true then only the providers which are currently enabled are returned. |
enabledOnly | if true then only the providers which are currently enabled are returned. |
---|
provider | the name of the provider |
---|
SecurityException | if no suitable permission is present for the provider. |
---|---|
IllegalArgumentException | if provider is null or doesn't exist |
intent | the PendingIntent that no longer needs to be notified of proximity alerts |
---|
provider | the provider name |
---|
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if no provider with the given name exists |
listener | {#link LocationListener} object that no longer needs location updates |
---|
IllegalArgumentException | if listener is null |
---|
It may take a while to receive the most recent location. If an immediate location is required, applications may use the getLastKnownLocation(String) method.
In case the provider is disabled by the user, updates will stop, and the onProviderDisabled(String) method will be called. As soon as the provider is enabled again, the onProviderEnabled(String) method will be called and location updates will start again.
The frequency of notification may be controlled using the minTime and minDistance parameters. If minTime milliseconds have elapsed since the last update and the position has changed by minDistance meters, a new notification may be provided. To obtain notifications as frequently as possible, set both parameters to 0.
The calling thread must be a Looper thread such as the main thread of the calling Activity.
provider | the name of the provider with which to register |
---|---|
minTime | the minimum time interval for notifications, in milliseconds |
minDistance | the minimum distance interval for notifications, in meters |
listener | a {#link LocationListener} whose onLocationChanged(Location) method will be called for each location update |
IllegalArgumentException | if provider is null or doesn't exist |
---|---|
IllegalArgumentException | if listener is null |
RuntimeException | if the calling thread has no Looper |
SecurityException | if no suitable permission is present for the provider. |
It may take a while to receive the most recent location. If an immediate location is required, applications may use the getLastKnownLocation(String) method.
In case the provider is disabled by the user, updates will stop, and the onProviderDisabled(String) method will be called. As soon as the provider is enabled again, the onProviderEnabled(String) method will be called and location updates will start again.
The frequency of notification may be controlled using the minTime and minDistance parameters. If minTime milliseconds have elapsed since the last update and the position has changed by minDistance meters, a new notification may be provided. To obtain notifications as frequently as possible, set both parameters to 0.
The supplied Looper is used to implement the callback mechanism.
provider | the name of the provider with which to register |
---|---|
minTime | the minimum time interval for notifications, in milliseconds |
minDistance | the minimum distance interval for notifications, in meters |
listener | a {#link LocationListener} whose onLocationChanged(Location) method will be called for each location update |
looper | a Looper object whose message queue will be used to implement the callback mechanism. |
IllegalArgumentException | if provider is null or doesn't exist |
---|---|
IllegalArgumentException | if listener is null |
IllegalArgumentException | if looper is null |
SecurityException | if no suitable permission is present for the provider. |
provider | the provider name |
---|---|
enabled | the mock enabled value |
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if no provider with the given name exists |
provider | the provider name |
---|---|
loc | the mock location |
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if no provider with the given name exists |
provider | the provider name |
---|---|
status | the mock status |
extras | a Bundle containing mock extras |
updateTime | the mock update time |
SecurityException | if the ACCESS_MOCK_LOCATION permission is not present |
---|---|
IllegalArgumentException | if no provider with the given name exists |
Copyright 2007 Google Inc. | Build 0.9_r1-98467 - 14 Aug 2008 18:48 |