| java.lang.Object | |
| ↳ | com.neomades.location.LocationManager |
Class Overview
This class provides access to the system location services.
These services allow applications to obtain periodic updates of the device's geographical location.
Cross Platform Considerations
- In
Androidprior to API Level 9, the location request methods are not supported (they do nothing).
Summary
| Public Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| static LocationManager |
getDefault()
Obtains the default LocationManager.
| ||||||||||
| Location |
getLastKnownLocation()
Retrieves the last saved location.
| ||||||||||
| Vector |
getProximityRegions()
Returns a vector containing all the registered regions for updates.
| ||||||||||
| boolean |
isLocationEnabledByUser()
Returns if the location is enabled on the device.
| ||||||||||
| boolean |
isSupported()
Returns if the ability to get the location is supported on the executing
device.
| ||||||||||
| void |
registerProximityRegion(ProximityRegion region)
Registers a ProximityRegion in this LocationManager.
| ||||||||||
| void |
requestAlwaysAuthorization()
Requests permission to use location services whenever the app is running.
| ||||||||||
| void |
requestMyLocation(long timeout, Criteria criteria, LocationListener locationListener)
Registers for a single location update using a Criteria.
| ||||||||||
| void |
requestMyLocation(long timeout, LocationListener locationListener)
Registers for a single location update using the default Criteria.
| ||||||||||
| void |
requestMyLocation(Criteria criteria, LocationListener locationListener)
Registers for a single location update using a Criteria.
| ||||||||||
| void |
requestMyLocation(LocationListener locationListener)
Registers for a single location update using the default Criteria.
| ||||||||||
| void |
requestMyLocationChanges(Criteria criteria, LocationListener locationListener)
Registers for location updates using a Criteria.
| ||||||||||
| void |
requestMyLocationChanges(LocationListener locationListener)
Registers for location updates using a default Criteria.
| ||||||||||
| void |
requestWhenInUseAuthorization()
When the current authorization status is
NotDetermined, this method runs
asynchronously and prompts the user to grant permission to the app to use
location services. | ||||||||||
| void |
setAuthorizationStatusListener(AuthorizationStatusListener listener)
Sets an authorization status callback.
| ||||||||||
| void |
stop(LocationListener listener)
Removes all location updates for the specified LocationListener.
| ||||||||||
| void |
stop()
Removes all location updates.
| ||||||||||
| void |
unregisterAllProximityRegions()
Unregisters all the ProximityRegion from this LocationManager.
| ||||||||||
| void |
unregisterProximityRegion(ProximityRegion region)
Unregisters a ProximityRegion from this LocationManager.
| ||||||||||
|
[Expand]
Inherited Methods | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
| |||||||||||
Public Methods
public static LocationManager getDefault ()
Obtains the default LocationManager.
The same instance will be returned every time.
Returns
- the default LocationManager
public Location getLastKnownLocation ()
Retrieves the last saved location.
Returns
- a Location object that can't be null, but can return a wrong location
public Vector getProximityRegions ()
Returns a vector containing all the registered regions for updates.
Returns
- a vector containing all the registered regions for updates.
public boolean isLocationEnabledByUser ()
Returns if the location is enabled on the device.
Cross platform considerations
On Android and iOS platforms,
the user can choose in the Settings if he wants to enable or disable access
to his location.
Returns
- true if location access is enabled by the user
public boolean isSupported ()
Returns if the ability to get the location is supported on the executing device.
Returns
- true if the location feature is supported
public void registerProximityRegion (ProximityRegion region)
Registers a ProximityRegion in this LocationManager.
The LocationManager will be notified (through its listener) if the terminal enters or exits thisProximityRegion.
Parameters
| region | the ProximityRegion to register |
|---|
Throws
| NullPointerException | if the region is null |
|---|---|
| IllegalArgumentException | if the region is already registered |
| RuntimeException | if monitoring services are disabled |
public void requestAlwaysAuthorization ()
Requests permission to use location services whenever the app is running.
When the current authorization status is
NotDetermined, this method runs
asynchronously and prompts the user to grant permission to the app to use
location services.
The user prompt contains the text from the
locationAlwaysPermissionUsage info that can be specified in
'res/string/info.xml' (and localized equivalents). This info must be provided
if this method is called, else the application will exit.
onAuthorizationStatusChanged method. If the current authorization status is
anything other than NotDetermined,
this method does nothing and does not call the
onAuthorizationStatusChanged method.
Important
Requesting "Always" authorization is discouraged because of the
potential negative impacts to user privacy. You should request this level of
authorization only when doing so offers a genuine benefit to the user.
You must call this method or the requestWhenInUseAuthorization method prior to using location services. When
the user grants "Always" authorization to your app, your app can
start any of the available location services while your app is running in the
foreground or background. In addition, services that allow your app to be
launched in the background continue to do so.
Cross platform considerations
Supported only for iOS (will do nothing for other platforms).
public void requestMyLocation (long timeout, Criteria criteria, LocationListener locationListener)
Registers for a single location update using a Criteria. The system will
use the best provider (GPS, Network...) according to the criteria. If the
timeout is reached before a location has been found, the request will be
cancelled and the
onLocationFailed(LocationErrorStatus) callback
will be triggered with a TIMEOUT.
Setting a timeout value of 0s is equivalent to call
requestMyLocation(Criteria, LocationListener).
Parameters
| timeout | a period of time after which the request will be cancelled if a location is not found (in ms) |
|---|---|
| criteria | contains parameters for the location manager to choose the appropriate provider |
| locationListener | a LocationListener whose onLocationChanged(Location) method will be called (not on the UI-thread) when the location update is available |
Throws
| IllegalArgumentException | if the timeout is negative or the location listener is null |
|---|
public void requestMyLocation (long timeout, LocationListener locationListener)
Registers for a single location update using the default Criteria. The
system will use its default available provider (GPS, Network...). If the
timeout is reached before a location has been found, the request will be
cancelled and the
onLocationFailed(LocationErrorStatus) callback
will be triggered with a TIMEOUT.
Setting a timeout value of 0s is equivalent to call
requestMyLocation(LocationListener).
Parameters
| timeout | a period of time after which the request will be cancelled if a location is not found (in ms) |
|---|---|
| locationListener | a LocationListener whose onLocationChanged(Location) method will be called (not on the UI-thread) when the location update is available |
Throws
| IllegalArgumentException | if the timeout is negative or the location listener is null |
|---|
public void requestMyLocation (Criteria criteria, LocationListener locationListener)
Registers for a single location update using a Criteria. The system will use the best provider (GPS, Network...) according to the criteria.
Parameters
| criteria | contains parameters for the location manager to choose the appropriate provider |
|---|---|
| locationListener | a LocationListener whose onLocationChanged(Location) method will be called (not on the UI-thread) when the location update is available |
Throws
| IllegalArgumentException | if the location listener is null |
|---|
public void requestMyLocation (LocationListener locationListener)
Registers for a single location update using the default Criteria. The system will use its default available provider (GPS, Network...).
Parameters
| locationListener | a LocationListener whose onLocationChanged(Location) method will be called (not on the UI-thread) when the location update is available |
|---|
Throws
| IllegalArgumentException | if the location listener is null |
|---|
public void requestMyLocationChanges (Criteria criteria, LocationListener locationListener)
Registers for location updates using a Criteria.
Cross platform considerations
Not supported for Android prior to API Level 9 (nothing will be done).
Parameters
| criteria | contains parameters for the location manager to choose the appropriate provider |
|---|---|
| locationListener | a LocationListener whose onLocationChanged(Location) method will be called (not on the UI-thread) for each location update |
public void requestMyLocationChanges (LocationListener locationListener)
Registers for location updates using a default Criteria.
Cross platform considerations
Not supported for Android prior to API Level 9 (nothing will be done).
Parameters
| locationListener | a LocationListener whose onLocationChanged(Location) method will be called (not on the UI-thread) for each location update |
|---|
public void requestWhenInUseAuthorization ()
When the current authorization status is
NotDetermined, this method runs
asynchronously and prompts the user to grant permission to the app to use
location services.
The user prompt contains the text from the
locationWhenInUsePermissionUsage info that can be specified in
'res/string/info.xml' (and localized equivalents). This info must be provided
if this method is called, else the application will exit.
After the status is determined, the location manager delivers the results to
the listener's
onAuthorizationStatusChanged method. If the current authorization status is
anything other than NotDetermined,
this method does nothing and does not call the
onAuthorizationStatusChanged method.
You must call this method or the requestAlwaysAuthorization() method
prior to using location services. If the user grants
"when-in-use" authorization to your app, your app can start most
(but not all) location services while it is in the foreground. (Apps cannot
use any services that automatically relaunch the app, such as region
monitoring or the significant location change service.) When started in the
foreground, services continue to run in the background if your app has
enabled background location updates. Attempts to start location services
while your app is running in the background will fail. The system displays a
location-services indicator in the status bar when your app moves to the
background with active location services.
Cross platform considerations
Supported only for iOS (will do nothing for other platforms).
public void setAuthorizationStatusListener (AuthorizationStatusListener listener)
Sets an authorization status callback.
Parameters
| listener | a callback or null. |
|---|
See Also
public void stop (LocationListener listener)
Removes all location updates for the specified LocationListener. Following this call, updates will no longer occur for this listener.
Parameters
| listener | object that no longer needs location updates |
|---|
public void stop ()
Removes all location updates. Following this call, updates will no longer occur.
public void unregisterAllProximityRegions ()
Unregisters all the ProximityRegion from this LocationManager.
public void unregisterProximityRegion (ProximityRegion region)
Unregisters a ProximityRegion from this LocationManager. To unregister a region you don't have an instance to anymore, recreate an instance of ProximityRegion with the exact same center coordinates and radius the region had been registered with.
Parameters
| region | the ProximityRegion to unregister |
|---|
Throws
| NullPointerException | if the region is null |
|---|---|
| IllegalArgumentException | if the region is not registered |