You do not * instantiate this class directly; instead, retrieve it through * {@link android.content.Context#getSystemService * Context.getSystemService(Context.LOCATION_SERVICE)}. * *
For more information about using location services, read the * Location and Maps * developer guide.
*The extras Bundle for the GPS location provider can contain the * following key/value pairs: * *
Note that the requirement on monetary cost is not removed * in this process. * * @param criteria the criteria that need to be matched * @param enabledOnly if true then only a provider that is currently enabled is returned * @return name of the provider that best matches the requirements */ public String getBestProvider(Criteria criteria, boolean enabledOnly) { if (criteria == null) { throw new IllegalArgumentException("criteria==null"); } try { return mService.getBestProvider(criteria, enabledOnly); } catch (RemoteException ex) { Log.e(TAG, "getBestProvider: RemoteException", ex); } return null; } /** * Registers the current activity to be notified periodically by * the named provider. Periodically, the supplied LocationListener will * be called with the current Location or with status updates. * *
It may take a while to receive the first location update. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
In case the provider is disabled by the user, updates will stop, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will * be called and location updates will start again. * *
The update interval can be controlled using the minTime parameter. * The elapsed time between location updates will never be less than * minTime, although it can be more depending on the Location Provider * implementation and the update interval requested by other applications. * *
Choosing a sensible value for minTime is important to conserve * battery life. Each location update requires power from * GPS, WIFI, Cell and other radios. Select a minTime value as high as * possible while still providing a reasonable user experience. * If your application is not in the foreground and showing * location to the user then your application should avoid using an active * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}), * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes) * or greater. If your application is in the foreground and showing * location to the user then it is appropriate to select a faster * update interval. * *
The minDistance parameter can also be used to control the * frequency of location updates. If it is greater than 0 then the * location provider will only send your application an update when * the location has changed by at least minDistance meters, AND * at least minTime milliseconds have passed. However it is more * difficult for location providers to save power using the minDistance * parameter, so minTime should be the primary tool to conserving battery * life. * *
If your application wants to passively observe location * updates triggered by other applications, but not consume * any additional power otherwise, then use the {@link #PASSIVE_PROVIDER} * This provider does not actively turn on or modify active location * providers, so you do not need to be as careful about minTime and * minDistance. However if your application performs heavy work * on a location update (such as network activity) then you should * select non-zero values for minTime and/or minDistance to rate-limit * your update frequency in the case another application enables a * location provider with extremely fast updates. * *
The calling thread must be a {@link android.os.Looper} thread such as * the main thread of the calling Activity. * *
Prior to Jellybean, the minTime parameter was * only a hint, and some location provider implementations ignored it. * From Jellybean and onwards it is mandatory for Android compatible * devices to observe both the minTime and minDistance parameters. * * @param provider the name of the provider with which to register * @param minTime minimum time interval between location updates, in milliseconds * @param minDistance minimum distance between location updates, in meters * @param listener a {#link LocationListener} whose * {@link LocationListener#onLocationChanged} method will be called for * each location update * * @throws IllegalArgumentException if provider is null or doesn't exist * on this device * @throws IllegalArgumentException if listener is null * @throws RuntimeException if the calling thread has no Looper * @throws SecurityException if no suitable permission is present for the provider. */ public void requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener) { if (provider == null) { throw new IllegalArgumentException("provider==null"); } if (listener == null) { throw new IllegalArgumentException("listener==null"); } _requestLocationUpdates(provider, null, minTime, minDistance, false, listener, null); } /** * Registers the current activity to be notified periodically by * the named provider. Periodically, the supplied LocationListener will * be called with the current Location or with status updates. * *
It may take a while to receive the first location update. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
In case the provider is disabled by the user, updates will stop, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will * be called and location updates will start again. * *
The update interval can be controlled using the minTime parameter. * The elapsed time between location updates will never be less than * minTime, although it can be more depending on the Location Provider * implementation and the update interval requested by other applications. * *
Choosing a sensible value for minTime is important to conserve * battery life. Each location update requires power from * GPS, WIFI, Cell and other radios. Select a minTime value as high as * possible while still providing a reasonable user experience. * If your application is not in the foreground and showing * location to the user then your application should avoid using an active * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}), * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes) * or greater. If your application is in the foreground and showing * location to the user then it is appropriate to select a faster * update interval. * *
The minDistance parameter can also be used to control the * frequency of location updates. If it is greater than 0 then the * location provider will only send your application an update when * the location has changed by at least minDistance meters, AND * at least minTime milliseconds have passed. However it is more * difficult for location providers to save power using the minDistance * parameter, so minTime should be the primary tool to conserving battery * life. * *
If your application wants to passively observe location * updates triggered by other applications, but not consume * any additional power otherwise, then use the {@link #PASSIVE_PROVIDER} * This provider does not actively turn on or modify active location * providers, so you do not need to be as careful about minTime and * minDistance. However if your application performs heavy work * on a location update (such as network activity) then you should * select non-zero values for minTime and/or minDistance to rate-limit * your update frequency in the case another application enables a * location provider with extremely fast updates. * *
The supplied Looper is used to implement the callback mechanism. * *
Prior to Jellybean, the minTime parameter was * only a hint, and some location provider implementations ignored it. * From Jellybean and onwards it is mandatory for Android compatible * devices to observe both the minTime and minDistance parameters. * * @param provider the name of the provider with which to register * @param minTime minimum time interval between location updates, in milliseconds * @param minDistance minimum distance between location updates, in meters * @param listener a {#link LocationListener} whose * {@link LocationListener#onLocationChanged} method will be called for * each location update * @param looper a Looper object whose message queue will be used to * implement the callback mechanism, or null to make callbacks on the * main thread * * @throws IllegalArgumentException if provider is null or doesn't exist * @throws IllegalArgumentException if listener is null * @throws SecurityException if no suitable permission is present for the provider. */ public void requestLocationUpdates(String provider, long minTime, float minDistance, LocationListener listener, Looper looper) { if (provider == null) { throw new IllegalArgumentException("provider==null"); } if (listener == null) { throw new IllegalArgumentException("listener==null"); } _requestLocationUpdates(provider, null, minTime, minDistance, false, listener, looper); } /** * Registers the current activity to be notified periodically based on * the supplied criteria. Periodically, the supplied LocationListener will * be called with the current Location or with status updates. * *
It may take a while to receive the first location update. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
In case the provider is disabled by the user, updates will stop, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will * be called and location updates will start again. * *
The update interval can be controlled using the minTime parameter. * The elapsed time between location updates will never be less than * minTime, although it can be more depending on the Location Provider * implementation and the update interval requested by other applications. * *
Choosing a sensible value for minTime is important to conserve * battery life. Each location update requires power from * GPS, WIFI, Cell and other radios. Select a minTime value as high as * possible while still providing a reasonable user experience. * If your application is not in the foreground and showing * location to the user then your application should avoid using an active * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}), * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes) * or greater. If your application is in the foreground and showing * location to the user then it is appropriate to select a faster * update interval. * *
The minDistance parameter can also be used to control the * frequency of location updates. If it is greater than 0 then the * location provider will only send your application an update when * the location has changed by at least minDistance meters, AND * at least minTime milliseconds have passed. However it is more * difficult for location providers to save power using the minDistance * parameter, so minTime should be the primary tool to conserving battery * life. * *
The supplied Looper is used to implement the callback mechanism. * *
Prior to Jellybean, the minTime parameter was * only a hint, and some location provider implementations ignored it. * From Jellybean and onwards it is mandatory for Android compatible * devices to observe both the minTime and minDistance parameters. * * @param minTime minimum time interval between location updates, in milliseconds * @param minDistance minimum distance between location updates, in meters * @param criteria contains parameters for the location manager to choose the * appropriate provider and parameters to compute the location * @param listener a {#link LocationListener} whose * {@link LocationListener#onLocationChanged} method will be called for * each location update * @param looper a Looper object whose message queue will be used to * implement the callback mechanism, or null to make callbacks on the * main thread. * * @throws IllegalArgumentException if criteria is null * @throws IllegalArgumentException if listener is null * @throws SecurityException if no suitable permission is present for the provider. */ public void requestLocationUpdates(long minTime, float minDistance, Criteria criteria, LocationListener listener, Looper looper) { if (criteria == null) { throw new IllegalArgumentException("criteria==null"); } if (listener == null) { throw new IllegalArgumentException("listener==null"); } _requestLocationUpdates(null, criteria, minTime, minDistance, false, listener, looper); } private void _requestLocationUpdates(String provider, Criteria criteria, long minTime, float minDistance, boolean singleShot, LocationListener listener, Looper looper) { if (minTime < 0L) { minTime = 0L; } if (minDistance < 0.0f) { minDistance = 0.0f; } try { synchronized (mListeners) { ListenerTransport transport = mListeners.get(listener); if (transport == null) { transport = new ListenerTransport(listener, looper); } mListeners.put(listener, transport); mService.requestLocationUpdates(provider, criteria, minTime, minDistance, singleShot, transport); } } catch (RemoteException ex) { Log.e(TAG, "requestLocationUpdates: DeadObjectException", ex); } } /** * Registers the current activity to be notified periodically by * the named provider. Periodically, the supplied PendingIntent will * be broadcast with the current Location or with status updates. * *
Location updates are sent with a key of * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value. * *
It may take a while to receive the first location update. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
The update interval can be controlled using the minTime parameter. * The elapsed time between location updates will never be less than * minTime, although it can be more depending on the Location Provider * implementation and the update interval requested by other applications. * *
Choosing a sensible value for minTime is important to conserve * battery life. Each location update requires power from * GPS, WIFI, Cell and other radios. Select a minTime value as high as * possible while still providing a reasonable user experience. * If your application is not in the foreground and showing * location to the user then your application should avoid using an active * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}), * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes) * or greater. If your application is in the foreground and showing * location to the user then it is appropriate to select a faster * update interval. * *
The minDistance parameter can also be used to control the * frequency of location updates. If it is greater than 0 then the * location provider will only send your application an update when * the location has changed by at least minDistance meters, AND * at least minTime milliseconds have passed. However it is more * difficult for location providers to save power using the minDistance * parameter, so minTime should be the primary tool to conserving battery * life. * *
If your application wants to passively observe location * updates triggered by other applications, but not consume * any additional power otherwise, then use the {@link #PASSIVE_PROVIDER} * This provider does not actively turn on or modify active location * providers, so you do not need to be as careful about minTime and * minDistance. However if your application performs heavy work * on a location update (such as network activity) then you should * select non-zero values for minTime and/or minDistance to rate-limit * your update frequency in the case another application enables a * location provider with extremely fast updates. * *
If the provider is disabled by the user, updates will stop, * and an intent will be sent with an extra with key * {@link #KEY_PROVIDER_ENABLED} and a boolean value of false. * If the provider is re-enabled, an intent will be sent with an * extra with key {@link #KEY_PROVIDER_ENABLED} and a boolean value of * true and location updates will start again. * *
If the provider's status changes, an intent will be sent with * an extra with key {@link #KEY_STATUS_CHANGED} and an integer value * indicating the new status. Any extras associated with the status * update will be sent as well. * *
Prior to Jellybean, the minTime parameter was * only a hint, and some location provider implementations ignored it. * From Jellybean and onwards it is mandatory for Android compatible * devices to observe both the minTime and minDistance parameters. * * @param provider the name of the provider with which to register * @param minTime minimum time interval between location updates, in milliseconds * @param minDistance minimum distance between location updates, in meters * @param intent a {#link PendingIntent} to be sent for each location update * * @throws IllegalArgumentException if provider is null or doesn't exist * on this device * @throws IllegalArgumentException if intent is null * @throws SecurityException if no suitable permission is present for the provider. */ public void requestLocationUpdates(String provider, long minTime, float minDistance, PendingIntent intent) { if (provider == null) { throw new IllegalArgumentException("provider==null"); } if (intent == null) { throw new IllegalArgumentException("intent==null"); } _requestLocationUpdates(provider, null, minTime, minDistance, false, intent); } /** * Registers the current activity to be notified periodically based on * the supplied criteria. Periodically, the supplied PendingIntent will * be broadcast with the current Location or with status updates. * *
Location updates are sent with a key of * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value. * *
It may take a while to receive the first location update. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
The update interval can be controlled using the minTime parameter. * The elapsed time between location updates will never be less than * minTime, although it can be more depending on the Location Provider * implementation and the update interval requested by other applications. * *
Choosing a sensible value for minTime is important to conserve * battery life. Each location update requires power from * GPS, WIFI, Cell and other radios. Select a minTime value as high as * possible while still providing a reasonable user experience. * If your application is not in the foreground and showing * location to the user then your application should avoid using an active * provider (such as {@link #NETWORK_PROVIDER} or {@link #GPS_PROVIDER}), * but if you insist then select a minTime of 5 * 60 * 1000 (5 minutes) * or greater. If your application is in the foreground and showing * location to the user then it is appropriate to select a faster * update interval. * *
The minDistance parameter can also be used to control the * frequency of location updates. If it is greater than 0 then the * location provider will only send your application an update when * the location has changed by at least minDistance meters, AND * at least minTime milliseconds have passed. However it is more * difficult for location providers to save power using the minDistance * parameter, so minTime should be the primary tool to conserving battery * life. * *
If the provider is disabled by the user, updates will stop, * and an intent will be sent with an extra with key * {@link #KEY_PROVIDER_ENABLED} and a boolean value of false. * If the provider is re-enabled, an intent will be sent with an * extra with key {@link #KEY_PROVIDER_ENABLED} and a boolean value of * true and location updates will start again. * *
If the provider's status changes, an intent will be sent with * an extra with key {@link #KEY_STATUS_CHANGED} and an integer value * indicating the new status. Any extras associated with the status * update will be sent as well. * *
Prior to Jellybean, the minTime parameter was * only a hint, and some location provider implementations ignored it. * From Jellybean and onwards it is mandatory for Android compatible * devices to observe both the minTime and minDistance parameters. * * @param minTime minimum time interval between location updates, in milliseconds * @param minDistance minimum distance between location updates, in meters * @param criteria contains parameters for the location manager to choose the * appropriate provider and parameters to compute the location * @param intent a {#link PendingIntent} to be sent for each location update * * @throws IllegalArgumentException if criteria is null * @throws IllegalArgumentException if intent is null * @throws SecurityException if no suitable permission is present for the provider. */ public void requestLocationUpdates(long minTime, float minDistance, Criteria criteria, PendingIntent intent) { if (criteria == null) { throw new IllegalArgumentException("criteria==null"); } if (intent == null) { throw new IllegalArgumentException("intent==null"); } _requestLocationUpdates(null, criteria, minTime, minDistance, false, intent); } private void _requestLocationUpdates(String provider, Criteria criteria, long minTime, float minDistance, boolean singleShot, PendingIntent intent) { if (minTime < 0L) { minTime = 0L; } if (minDistance < 0.0f) { minDistance = 0.0f; } try { mService.requestLocationUpdatesPI(provider, criteria, minTime, minDistance, singleShot, intent); } catch (RemoteException ex) { Log.e(TAG, "requestLocationUpdates: RemoteException", ex); } } /** * Requests a single location update from the named provider. * *
It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
In case the provider is disabled by the user, the update will not be received, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will * be called and location updates will start again. * *
The supplied Looper is used to implement the callback mechanism. * * @param provider the name of the provider with which to register * @param listener a {#link LocationListener} whose * {@link LocationListener#onLocationChanged} method will be called when * the location update is available * @param looper a Looper object whose message queue will be used to * implement the callback mechanism, or null to make callbacks on the * main thread * * @throws IllegalArgumentException if provider is null or doesn't exist * @throws IllegalArgumentException if listener is null * @throws SecurityException if no suitable permission is present for the provider */ public void requestSingleUpdate(String provider, LocationListener listener, Looper looper) { if (provider == null) { throw new IllegalArgumentException("provider==null"); } if (listener == null) { throw new IllegalArgumentException("listener==null"); } _requestLocationUpdates(provider, null, 0L, 0.0f, true, listener, looper); } /** * Requests a single location update based on the specified criteria. * *
It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
In case the provider is disabled by the user, the update will not be received, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will * be called and location updates will start again. * *
The supplied Looper is used to implement the callback mechanism. * * @param criteria contains parameters for the location manager to choose the * appropriate provider and parameters to compute the location * @param listener a {#link LocationListener} whose * {@link LocationListener#onLocationChanged} method will be called when * the location update is available * @param looper a Looper object whose message queue will be used to * implement the callback mechanism, or null to make callbacks on the * main thread * * @throws IllegalArgumentException if criteria is null * @throws IllegalArgumentException if listener is null * @throws SecurityException if no suitable permission is present to access * the location services */ public void requestSingleUpdate(Criteria criteria, LocationListener listener, Looper looper) { if (criteria == null) { throw new IllegalArgumentException("criteria==null"); } if (listener == null) { throw new IllegalArgumentException("listener==null"); } _requestLocationUpdates(null, criteria, 0L, 0.0f, true, listener, looper); } /** * Requests a single location update from the named provider. * *
It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
Location updates are sent with a key of * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value. * *
In case the provider is disabled by the user, the update will not be received, * and the {@link LocationListener#onProviderDisabled(String)} * method will be called. As soon as the provider is enabled again, * the {@link LocationListener#onProviderEnabled(String)} method will * be called and location updates will start again. * * @param provider the name of the provider with which to register * @param intent a {#link PendingIntent} to be sent for the location update * * @throws IllegalArgumentException if provider is null or doesn't exist * @throws IllegalArgumentException if intent is null * @throws SecurityException if no suitable permission is present for the provider */ public void requestSingleUpdate(String provider, PendingIntent intent) { if (provider == null) { throw new IllegalArgumentException("provider==null"); } if (intent == null) { throw new IllegalArgumentException("intent==null"); } _requestLocationUpdates(provider, null, 0L, 0.0f, true, intent); } /** * Requests a single location update based on the specified criteria. * *
It may take a while to receive the most recent location. If * an immediate location is required, applications may use the * {@link #getLastKnownLocation(String)} method. * *
Location updates are sent with a key of * {@link #KEY_LOCATION_CHANGED} and a {@link android.location.Location} value. * *
If the provider is disabled by the user, an update will not be * received, and an intent will be sent with an extra with key * {@link #KEY_PROVIDER_ENABLED} and a boolean value of false. * If the provider is re-enabled, an intent will be sent with an * extra with key {@link #KEY_PROVIDER_ENABLED} and a boolean value of * true and the location update will occur. * * @param criteria contains parameters for the location manager to choose the * appropriate provider and parameters to compute the location * @param intent a {#link PendingIntent} to be sent for the location update * * @throws IllegalArgumentException if provider is null or doesn't exist * @throws IllegalArgumentException if intent is null * @throws SecurityException if no suitable permission is present for the provider */ public void requestSingleUpdate(Criteria criteria, PendingIntent intent) { if (criteria == null) { throw new IllegalArgumentException("criteria==null"); } if (intent == null) { throw new IllegalArgumentException("intent==null"); } _requestLocationUpdates(null, criteria, 0L, 0.0f, true, intent); } /** * Removes any current registration for location updates of the current activity * with the given LocationListener. Following this call, updates will no longer * occur for this listener. * * @param listener {#link LocationListener} object that no longer needs location updates * @throws IllegalArgumentException if listener is null */ public void removeUpdates(LocationListener listener) { if (listener == null) { throw new IllegalArgumentException("listener==null"); } if (false) { Log.d(TAG, "removeUpdates: listener = " + listener); } try { ListenerTransport transport = mListeners.remove(listener); if (transport != null) { mService.removeUpdates(transport); } } catch (RemoteException ex) { Log.e(TAG, "removeUpdates: DeadObjectException", ex); } } /** * Removes any current registration for location updates of the current activity * with the given PendingIntent. Following this call, updates will no longer * occur for this intent. * * @param intent {#link PendingIntent} object that no longer needs location updates * @throws IllegalArgumentException if intent is null */ public void removeUpdates(PendingIntent intent) { if (intent == null) { throw new IllegalArgumentException("intent==null"); } if (false) { Log.d(TAG, "removeUpdates: intent = " + intent); } try { mService.removeUpdatesPI(intent); } catch (RemoteException ex) { Log.e(TAG, "removeUpdates: RemoteException", ex); } } /** * Sets a proximity alert for the location given by the position * (latitude, longitude) and the given radius. When the device * detects that it has entered or exited the area surrounding the * location, the given PendingIntent will be used to create an Intent * to be fired. * *
The fired Intent will have a boolean extra added with key * {@link #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. * *
In case the screen goes to sleep, checks for proximity alerts * happen only once every 4 minutes. This conserves battery life by * ensuring that the device isn't perpetually awake. * *
Internally, this method uses both {@link #NETWORK_PROVIDER} * and {@link #GPS_PROVIDER}. * * @param latitude the latitude of the central point of the * alert region * @param longitude the longitude of the central point of the * alert region * @param radius the radius of the central point of the * alert region, in meters * @param expiration time for this proximity alert, in milliseconds, * or -1 to indicate no expiration * @param intent a PendingIntent that will be used to generate an Intent to * fire when entry to or exit from the alert region is detected * * @throws SecurityException if no permission exists for the required * providers. */ public void addProximityAlert(double latitude, double longitude, float radius, long expiration, PendingIntent intent) { if (false) { Log.d(TAG, "addProximityAlert: latitude = " + latitude + ", longitude = " + longitude + ", radius = " + radius + ", expiration = " + expiration + ", intent = " + intent); } try { mService.addProximityAlert(latitude, longitude, radius, expiration, intent); } catch (RemoteException ex) { Log.e(TAG, "addProximityAlert: RemoteException", ex); } } /** * Removes the proximity alert with the given PendingIntent. * * @param intent the PendingIntent that no longer needs to be notified of * proximity alerts */ public void removeProximityAlert(PendingIntent intent) { if (false) { Log.d(TAG, "removeProximityAlert: intent = " + intent); } try { mService.removeProximityAlert(intent); } catch (RemoteException ex) { Log.e(TAG, "removeProximityAlert: RemoteException", ex); } } /** * Returns the current enabled/disabled status of the given provider. If the * user has enabled this provider in the Settings menu, true is returned * otherwise false is returned * * @param provider the name of the provider * @return true if the provider is enabled * * @throws SecurityException if no suitable permission is present for the provider. * @throws IllegalArgumentException if provider is null */ public boolean isProviderEnabled(String provider) { if (provider == null) { throw new IllegalArgumentException("provider==null"); } try { return mService.isProviderEnabled(provider); } catch (RemoteException ex) { Log.e(TAG, "isProviderEnabled: RemoteException", ex); return false; } } /** * Returns a Location indicating the data from the last known * location fix obtained from the given provider. This can be done * without starting the provider. Note that this location could * be out-of-date, for example if the device was turned off and * moved to another location. * *
If the provider is currently disabled, null is returned.
*
* @param provider the name of the provider
* @return the last known location for the provider, or null
*
* @throws SecurityException if no suitable permission is present for the provider.
* @throws IllegalArgumentException if provider is null or doesn't exist
*/
public Location getLastKnownLocation(String provider) {
if (provider == null) {
throw new IllegalArgumentException("provider==null");
}
try {
return mService.getLastKnownLocation(provider);
} catch (RemoteException ex) {
Log.e(TAG, "getLastKnowLocation: RemoteException", ex);
return null;
}
}
// Mock provider support
/**
* Creates a mock location provider and adds it to the set of active providers.
*
* @param name the provider name
* @param requiresNetwork
* @param requiresSatellite
* @param requiresCell
* @param hasMonetaryCost
* @param supportsAltitude
* @param supportsSpeed
* @param supportsBearing
* @param powerRequirement
* @param accuracy
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION} system setting is not enabled
* @throws IllegalArgumentException if a provider with the given name already exists
*/
public void addTestProvider(String name, boolean requiresNetwork, boolean requiresSatellite,
boolean requiresCell, boolean hasMonetaryCost, boolean supportsAltitude,
boolean supportsSpeed, boolean supportsBearing, int powerRequirement, int accuracy) {
try {
mService.addTestProvider(name, requiresNetwork, requiresSatellite, requiresCell,
hasMonetaryCost, supportsAltitude, supportsSpeed, supportsBearing, powerRequirement,
accuracy);
} catch (RemoteException ex) {
Log.e(TAG, "addTestProvider: RemoteException", ex);
}
}
/**
* Removes the mock location provider with the given name.
*
* @param provider the provider name
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
*/
public void removeTestProvider(String provider) {
try {
mService.removeTestProvider(provider);
} catch (RemoteException ex) {
Log.e(TAG, "removeTestProvider: RemoteException", ex);
}
}
/**
* Sets a mock location for the given provider. This location will be used in place
* of any actual location from the provider.
*
* @param provider the provider name
* @param loc the mock location
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
*/
public void setTestProviderLocation(String provider, Location loc) {
try {
mService.setTestProviderLocation(provider, loc);
} catch (RemoteException ex) {
Log.e(TAG, "setTestProviderLocation: RemoteException", ex);
}
}
/**
* Removes any mock location associated with the given provider.
*
* @param provider the provider name
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
*/
public void clearTestProviderLocation(String provider) {
try {
mService.clearTestProviderLocation(provider);
} catch (RemoteException ex) {
Log.e(TAG, "clearTestProviderLocation: RemoteException", ex);
}
}
/**
* Sets a mock enabled value for the given provider. This value will be used in place
* of any actual value from the provider.
*
* @param provider the provider name
* @param enabled the mock enabled value
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
*/
public void setTestProviderEnabled(String provider, boolean enabled) {
try {
mService.setTestProviderEnabled(provider, enabled);
} catch (RemoteException ex) {
Log.e(TAG, "setTestProviderEnabled: RemoteException", ex);
}
}
/**
* Removes any mock enabled value associated with the given provider.
*
* @param provider the provider name
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
*/
public void clearTestProviderEnabled(String provider) {
try {
mService.clearTestProviderEnabled(provider);
} catch (RemoteException ex) {
Log.e(TAG, "clearTestProviderEnabled: RemoteException", ex);
}
}
/**
* Sets mock status values for the given provider. These values will be used in place
* of any actual values from the provider.
*
* @param provider the provider name
* @param status the mock status
* @param extras a Bundle containing mock extras
* @param updateTime the mock update time
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
*/
public void setTestProviderStatus(String provider, int status, Bundle extras, long updateTime) {
try {
mService.setTestProviderStatus(provider, status, extras, updateTime);
} catch (RemoteException ex) {
Log.e(TAG, "setTestProviderStatus: RemoteException", ex);
}
}
/**
* Removes any mock status values associated with the given provider.
*
* @param provider the provider name
*
* @throws SecurityException if the ACCESS_MOCK_LOCATION permission is not present
* or the {@link android.provider.Settings.Secure#ALLOW_MOCK_LOCATION
* Settings.Secure.ALLOW_MOCK_LOCATION}} system setting is not enabled
* @throws IllegalArgumentException if no provider with the given name exists
*/
public void clearTestProviderStatus(String provider) {
try {
mService.clearTestProviderStatus(provider);
} catch (RemoteException ex) {
Log.e(TAG, "clearTestProviderStatus: RemoteException", ex);
}
}
// GPS-specific support
// This class is used to send GPS status events to the client's main thread.
private class GpsStatusListenerTransport extends IGpsStatusListener.Stub {
private final GpsStatus.Listener mListener;
private final GpsStatus.NmeaListener mNmeaListener;
// This must not equal any of the GpsStatus event IDs
private static final int NMEA_RECEIVED = 1000;
private class Nmea {
long mTimestamp;
String mNmea;
Nmea(long timestamp, String nmea) {
mTimestamp = timestamp;
mNmea = nmea;
}
}
private ArrayList