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
removeUpdates(LocationListener)
orremoveUpdates()
.
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
. - Android devices running API 31 and greater will require the runtime permissions BLUETOOTH_SCAN and BLUETOOTH_CONNECT if your app wants to use BLE to determine the position using nearby devices.
- See Also:
LocationRequest
,Location
,LocationListener
- Start the positioning by calling the method
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
LocationManager.Code
The error codes that theLocationManager
can generate (all errors will be communicated through theLocationListener.onError(Error)
callback).static interface
LocationManager.PropertyKey
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addExternalArData(ExternalArData externalArData)
Computes the given AR data.void
addExternalLocation(ExternalLocation externalLocation)
Adds an external Location for the SDK to process and return as a Location object through theLocationListener
inrequestLocationUpdates(LocationRequest, LocationListener)
void
addLocationListener(LocationListener locationListener)
Adds aLocationListener
that will receive location updates, status codes and errors.LocationRequest
getLocationRequest()
Get theLocationRequest
used in the current positioning session.boolean
isRunning()
Returns true ifLocationManager.requestLocationUpdates()
was called and positioning is runningvoid
removeAllLocationListeners()
If any, removes all theLocationListener
s previously subscribed.void
removeLocationListener(LocationListener locationListener)
Removes theLocationListener
callback.void
removeUpdates()
Stops positioning.void
removeUpdates(LocationListener locationListener)
Shortcut forremoveUpdates()
andremoveLocationListener(LocationListener)
.void
requestLocationUpdates(LocationRequest locationRequest)
Starts positioning with the configuration specified by theLocationRequest
.void
requestLocationUpdates(LocationRequest locationRequest, LocationListener locationListener)
Starts positioning with the configuration specified by theLocationRequest
; computed geolocations, status codes and errors will be received through theLocationListener
callbacks.boolean
sendGroundTruth(float x, float y, int floorId)
DEBUG ONLY DO NOT USE This method is for internal use, if you call it nothing will happenvoid
setGeofenceListener(GeofenceListener geofenceListener)
Set theGeofenceListener
that will be called when the user enters or exits geofences.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 theLocationRequest
; computed geolocations, status codes and errors will be received through theLocationListener
callbacks.Removes all the
LocationListener
s previously provided.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
, any other LocationListener already subscribed will be removed, therefore geolocations will be communicated only to the new one. - If neither
LocationRequest
norLocationListener
change, nothing will happen.
You may stop positioning at any time by calling the
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).removeUpdates(LocationListener)
orremoveUpdates()
method.- 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).
- If you provide a new
-
requestLocationUpdates
void requestLocationUpdates(@NonNull LocationRequest locationRequest)
Starts positioning with the configuration specified by theLocationRequest
. Notifies location, status codes and errors to anyLocationListener
provided withaddLocationListener(LocationListener)
. Locations, status codes and errors produced before a listener is provided will not be notified again.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 the
LocationRequest
does not change, nothing will happen.
You may stop positioning at any time by calling
removeUpdates()
method.- Parameters:
locationRequest
- the location request with the positioning configuration parameters: Building vs Global, whether or not to use WiFi or BLE, etc.- See Also:
removeUpdates()
,addLocationListener(LocationListener)
- If you provide a new
-
addLocationListener
void addLocationListener(@NonNull LocationListener locationListener)
Adds aLocationListener
that will receive location updates, status codes and errors. CallremoveLocationListener(LocationListener)
to stop receiving updates.- Parameters:
locationListener
- the listener to notify the generated geolocations and other information (status and errors).- See Also:
removeLocationListener(LocationListener)
-
removeLocationListener
void removeLocationListener(@NonNull LocationListener locationListener)
Removes theLocationListener
callback. This call does not stop the positioning. Any other subscribedLocationListener
will receive location updates, status codes and errors.- Parameters:
locationListener
- the listener to be removed.- See Also:
addLocationListener(LocationListener)
-
removeAllLocationListeners
void removeAllLocationListeners()
If any, removes all theLocationListener
s previously subscribed.
-
removeUpdates
void removeUpdates(@NonNull LocationListener locationListener)
Shortcut forremoveUpdates()
andremoveLocationListener(LocationListener)
. Stops positioning and removes the givenLocationListener
from receiving callbacks. Other previously addedLocationListener
s will receive location updates in subsequent positioning sessions.To stop receiving callbacks in a listener without stopping the positioning use
removeLocationListener(LocationListener)
.On the other hand, to stop positioning without removing listeners use
removeUpdates()
.- Parameters:
locationListener
- the LocationListener to stop receiving callbacks.- See Also:
removeLocationListener(LocationListener)
,removeUpdates()
-
removeUpdates
void removeUpdates()
Stops positioning. Previously addedLocationListener
s will persist but won't receive location updates because the positioning is stopped.
-
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 callingLocationManager.removeUpdates()
andLocationManager.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. SeeLocationParametersUpdate
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 theLocationParametersUpdateListener
. 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 ifLocationManager.requestLocationUpdates()
was called and positioning is running- Returns:
- true if positioning is running, false otherwise
-
addExternalLocation
void addExternalLocation(@NonNull ExternalLocation externalLocation)
Adds an external Location for the SDK to process and return as a Location object through theLocationListener
inrequestLocationUpdates(LocationRequest, LocationListener)
-
addExternalArData
void addExternalArData(@NonNull ExternalArData externalArData)
Computes the given AR data. This method is intended for internal use.- Parameters:
externalArData
- The external AR data.
-
setGeofenceListener
void setGeofenceListener(GeofenceListener geofenceListener)
Set theGeofenceListener
that will be called when the user enters or exits geofences. Note: Setting this listener adds an additional computational cost depending on the number of geofences defined in the current building.- Parameters:
geofenceListener
- TheGeofenceListener
or null to stop receiving notifications. The latter will also halt geofence processing, avoiding the extra computational cost.
-
getLocationRequest
@Nullable LocationRequest getLocationRequest()
Get theLocationRequest
used in the current positioning session. This is useful when using remote configurationConfiguration#setUseRemoteConfig(boolean)
as the values of the location request can be:- Exactly those configured in the dashboard.
- The merge of remote and local parameters, if indicated when the positioning was started.
- Returns:
- the actual
LocationRequest
used in the current positioning session
-
sendGroundTruth
boolean sendGroundTruth(float x, float y, int floorId)
DEBUG ONLY DO NOT USE This method is for internal use, if you call it nothing will happen
-
-