Package es.situm.sdk.location

Interface LocationManager

public interface LocationManager

This class provides Situm Indoor and / or Outdoor positioning. In essence, this class allows you to:

• Start the positioning by calling the method requestLocationUpdates(LocationRequest, LocationListener) with:

  - A LocationRequest with the positioning configuration parameters: Building vs Global, whether or not to use WiFi or BLE, etc.

  - A LocationListener to receive generated geolocations and other information (status and errors).

• Stop the positioning by calling the method LocationManager.removeUpdates().

Before using any of this class methods, you must call SitumSdk.init(Context). Also, before you use this class, the user will need to grant the following runtime permissions:

• ACCESS_COARSE_LOCATION. Required if you use Situm SDK in Building Mode (positioning restricted to Indoor Positions within a predefined building). Building Mode can be configured using the LocationRequest.setBuildingIdentifier() method.
• ACCESS_FINE_LOCATION. Required if you use Situm SDK in Global Mode (positioning anywhere, Indoors or Outdoors, with automatic building detection). Global Mode is the default mode when building the LocationRequest.

See Also:

LocationRequest, Location, LocationListener

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	LocationManager.Code	The error codes that the LocationManager can generate (all errors will be communicated through the LocationListener.onError(Error) callback).
static interface	LocationManager.PropertyKey

Method Summary

Modifier and Type	Method	Description
boolean	isRunning()	Returns true if LocationManager.requestLocationUpdates() was called and positioning is running
void	removeUpdates(LocationListener locationListener)	Stops positioning, removing all location updates for the given LocationListener.
void	requestLocationUpdates(LocationRequest locationRequest, LocationListener locationListener)	Starts positioning with the configuration specified by the LocationRequest; computed geolocations, status codes and errors will be received through the LocationListener callbacks.
void	updateLocationParameters(LocationParametersUpdate locationParametersUpdate, LocationParametersUpdateListener locationParametersUpdateListener)	Updates positioning parameters on the fly (without stopping and re-starting positioning).

Method Detail

requestLocationUpdates

void requestLocationUpdates(@NonNull
                            LocationRequest locationRequest,
                            @NonNull
                            LocationListener locationListener)

Starts positioning with the configuration specified by the LocationRequest; computed geolocations, status codes and errors will be received through the LocationListener callbacks.

You may call this method more than once, with the following effect:

• If you provide a new LocationRequest instance, positioning will be re-started with the new positioning options specified by this new instance.
• If you provide a new LocationListener, the former LocationListener will be replaced, therefore geolocations will be communicated to the new one.
• If neither LocationRequest nor LocationListener change, nothing will happen.

You may stop positioning at any time by calling the LocationManager.removeUpdates() method.

Since: 2.50.1 - When positioning in Global Mode, in case of encountering any error (e.g. network failure, corrupt data in a building, etc.), positioning will stop and inform of the error. In previous versions, Situm SDK would retry endlessly (except in case of network errors).

Parameters:

locationRequest - the location request with the positioning configuration parameters: Building vs Global, whether or not to use WiFi or BLE, etc.

locationListener - the listener to notify the generated geolocations, and other information (status and errors).

removeUpdates

void removeUpdates(@NonNull
                   LocationListener locationListener)

Stops positioning, removing all location updates for the given LocationListener.

Parameters:

locationListener - the listener to remove

updateLocationParameters

void updateLocationParameters(@NonNull
                              LocationParametersUpdate locationParametersUpdate,
                              @NonNull
                              LocationParametersUpdateListener locationParametersUpdateListener)

Updates positioning parameters on the fly (without stopping and re-starting positioning).

When the LocationManager is running (LocationManager.isRunning() is true), this method provides a convenient way to change the positioning parameters without re-starting positioning (that is, without calling LocationManager.removeUpdates() and LocationManager.requestLocationUpdates() again).

This method has no effect if the LocationManager is not running (LocationManager.isRunning() is false).

Parameters:

locationParametersUpdate - object containing parameters to be modified. See LocationParametersUpdate for a detailed description.

locationParametersUpdateListener - listener that will be notified with the states that the update process goes through. The process of updating parameters is an asynchronous operation that involves a series of states that will be communicatied via the LocationParametersUpdateListener. All these methods will be called on the main thread.

Version: 0.0.1 Since: Starting from version of the SDK 2.41.0

isRunning

boolean isRunning()

Returns true if LocationManager.requestLocationUpdates() was called and positioning is running

Returns:

true if positioning is running, false otherwise