Package com.iizix.geo

Interface ILocationService

public interface ILocationService
Service responsible for accessing the geolocation of a user or a specific device.

This service can be retrieved from the IClientSessionGyro and will then operate on that particular client session.

If the service is retrieved from the IAppSessionGyro all operations will target all connected and initialized client sessions.

When background location updates are started, it may very well be so that a client has a previously started background location request followed by the user closing the app. Depending on settings, the background updates may still be in place. If an app starts and do not wish to use background location updates, it is recommended to call the stopBackgroundLocation() method.

Author:
Christopher Mindus

  • Method Details

    • isClientSessionService

      boolean isClientSessionService()
      Returns if the service applies to a single client session or if it's affecting all connected and initialized client sessions.
      Returns:
      false If service is bound to the application session, true if bound to a single client session.

    • getCurrentLocation

      GeoLocation getCurrentLocation()
      Gets the current location. When iiziApp is started on the client side, a location is generally requested. If successful, this is the location returned by this method, unless a location has been requested using requestLocation(ILocationListener). If so, that location is returned, i.e. a newer location.
      Returns:
      The location, or null for none. The location returned may contain an error message indicating that location retrieval failed or that the user has disabled the feature.

    • isBackgroundModeSupported

      boolean isBackgroundModeSupported()
      Returns if background location mode is supported.
      Returns:
      true if OK (on at least one device), false if not possible on the device.

    • isBackgroundLocationEnabled

      boolean isBackgroundLocationEnabled()
      Returns if background location is currently turned on or if the user has turned it off. This setting can change when the user changes the background location state.

      Background location can still be started even if the enabled state is false, it will just start later on.

      Returns:
      true if enabled (on at least one device), false if disabled.

    • showAppSettings

      boolean showAppSettings()
      Shows the app settings to allow change of app location permissions by the user on Android 6 or better, iOS 8.0 or better when the background location settings plugin is present.

      For iiziRun Developer with iOS, the background location plugin is not present due to Apple Store restrictions on how the app should behave and need according to them. This means that the function may not do anything at all.

      If the method isBackgroundModeSupported() returns true and the client device is Android 6 or better or iOS 8.0 or better, this method will work.

      Returns:
      true for success, false for failure.

    • configureBackgroundLocation

      int configureBackgroundLocation(BackgroundLocationConfiguration config)
      Sets the configuration for the location background service.
      Parameters:
      config - The configuration instance.
      Returns:
      The number of client connections configured.
      Throws:
      NullPointerException - If config is null.

    • isBackgroundLocationConfigured

      boolean isBackgroundLocationConfigured()
      Returns if the configuration of background location has been configured or not.
      Returns:
      true if already configured, false otherwise.

    • startBackgroundLocation

      int startBackgroundLocation()
      Start the location background service on the device(s) (if supported).
      Returns:
      The number of affected client sessions, might be zero.
      Throws:
      IllegalStateException - If the configuration has not been set.

    • stopBackgroundLocation

      int stopBackgroundLocation()
      Stop the location background service on the device(s) (if supported).
      Returns:
      The number of affected client sessions, might be zero.

    • getLatestLocation

      DeviceLocation getLatestLocation()
      Get the latest known location found in user location history.
      Returns:
      The device location found, null for none.

    • requestLocation

      int requestLocation(ILocationListener callback)
      Requests a new location. If this method is called for the application session, the callback may be invoked for every connected client session when a location from the device is received.
      Parameters:
      callback - The callback that is called when location has been received. Note that the location may contain an error code and an error message for failures.
      Returns:
      The number of affected client sessions, might be zero. This value does not mean that the callback will be called that number of times as a device may not be able to retrieve a location at all.
      Throws:
      NullPointerException - If the callback is null.

    • addLocationChangeListener

      boolean addLocationChangeListener(ILocationListener listener)
      Starts listening to changes in the location.
      Parameters:
      listener - The listener to add.
      Returns:
      true if successfully added, false indicating the listener already has been added previously.

    • removeLocationChangeListener

      boolean removeLocationChangeListener(ILocationListener listener)
      Stops listening to changes of locations.
      Parameters:
      listener - The listener to remove.
      Returns:
      true if successfully removed, false indicating the listener was not added previously.

    • addBackgroundModeListener

      boolean addBackgroundModeListener(IBackgroundLocationModeListener listener)
      Starts listening to changed in the background location mode. The background mode can be changed by a user at any time, affecting the background location support.
      Parameters:
      listener - The listener to add.
      Returns:
      true if successfully added, false indicating the listener already has been added previously.

    • removeBackgroundModeListener

      boolean removeBackgroundModeListener(IBackgroundLocationModeListener listener)
      Stops listening to changes in the background location mode.
      Parameters:
      listener - The listener to remove.
      Returns:
      true if successfully removed, false indicating the listener was not added previously.