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:

    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

    • 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.

        Removes all the LocationListeners 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 nor LocationListener change, nothing will happen.

        You may stop positioning at any time by calling the removeUpdates(LocationListener) or 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).

      • requestLocationUpdates

        void requestLocationUpdates​(@NonNull
                            LocationRequest locationRequest)
        Starts positioning with the configuration specified by the LocationRequest. Notifies location, status codes and errors to any LocationListener provided with addLocationListener(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)

      • removeAllLocationListeners

        void removeAllLocationListeners()
        If any, removes all the LocationListeners previously subscribed.

      • removeUpdates

        void removeUpdates()
        Stops positioning. Previously added LocationListeners 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 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

      • setGeofenceListener

        void setGeofenceListener​(GeofenceListener geofenceListener)
        Set the GeofenceListener 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 - The GeofenceListener or null to stop receiving notifications. The latter will also halt geofence processing, avoiding the extra computational cost.

      • getLocationRequest

        @Nullable
LocationRequest getLocationRequest()
        Get the LocationRequest used in the current positioning session. This is useful when using remote configuration Configuration#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