com.indooratlas.android.sdk

Class IALocationManager

java.lang.Object

com.indooratlas.android.sdk.IALocationManager

public abstract class IALocationManager
extends Object

This class provides access to IndoorAtlas location services. This classes methods must be called from the application main thread only.

Any conditions that prevent manager from running are logged with android.util.Log using log tag IASDK.

Basic usage:

     protected void onCreate(Bundle bundle) {
         super.onCreate(bundle)
         mLocationManager = IALocationManager.create(context);
     }

     protected void onDestroy() {
         mLocationManager.destroy();
         super.onDestroy();
     }

     protected void onResume() {
         super.onResume();
         mLocationManager.requestLocationUpdates(IALocationRequest.create(), this);
     }

     protected void onPause() {
         mLocationManager.removeLocationUpdates(this);
         super.onPause();
     }

     public void onLocationChanged(IALocation location) {
         // do something interesting with the new update
     }

     public void onStatusChanged(String provider, int status, Bundle extras) {
         // do something with new status
     }

 

Monitor geofences:

     protected void onCreate(Bundle bundle) {
         super.onCreate(bundle)
         mLocationManager = IALocationManager.create(context);
         mLocationManager.requestLocationUpdates(IALocationRequest.create(), this);
         
         // Create a edges with unique clockwise (lat, lon) points
         List edges = Arrays.asList(new double[][]{{59.8, 20.3}, {64.3, 20.7},
                                                   {63.7, 32.1}, {59.2, 29.8}});
         // Create the geofence for 10 seconds in floor number 1
         IAGeofence geofence = new IAGeofence.Builder()
                                  .withEdges(edges)
                                  .withFloor(1)
                                  .withId("This is a geofence for testing")
                                  .withExpirationDuration(10000)
                                  .withTransitionType(IAGeofence.GEOFENCE_TRANSITION_ENTER |
                                                      IAGeofence.GEOFENCE_TRANSITION_EXIT)


         mLocationManager.addGeofences(new IAGeofenceRequest.Builder()
                                  .withGeofence(geofence)
                                  .withInitialTrigger(IAGeofenceRequest.INITIAL_TRIGGER_ENTER)
                                  .build(), this);

     }

     public void onGeofencesTriggered(IAGeofenceEvent geofenceEvent) {
         // Do something with the triggered geofences in geofenceEvent
     }

 

Field Summary

Fields

Modifier and Type	Field and Description
static int	CALIBRATION_EXCELLENT Calibration is not required
static int	CALIBRATION_GOOD Calibration is acceptable, but recommended
static int	CALIBRATION_POOR Calibration is required
static String	EXTRA_API_KEY Extra attribute key to configure IndoorAtlas API key at run time.
static String	EXTRA_API_SECRET Extra attribute key to configure IndoorAtlas API secret at run time.
static String	EXTRA_GEOFENCE_EVENT Extra attribute key used when geofence events are delivered in an Intent after requesting geofence events with #requestGeofenceUpdates(PendingIntent).
static String	EXTRA_LOCATION Extra attribute key used when location updates are delivered in an Intent after requesting location updates with requestLocationUpdates(IALocationRequest, PendingIntent).
static String	EXTRA_PROXY_ADDRESS Extra attribute key to configure SDK to use proxy address for communication.
static String	EXTRA_PROXY_DISABLED Extra attribute key to disable SDK to use proxy port for communication.
static String	EXTRA_PROXY_PORT Extra attribute key to configure SDK to use proxy port for communication.
static int	STATUS_AVAILABLE Location service running normally.
static int	STATUS_CALIBRATION_CHANGED Calibration Quality Indicator Bundle extras: quality (Integer) CALIBRATION_POOR CALIBRATION_GOOD CALIBRATION_EXCELLENT
static int	STATUS_LIMITED Location service is running but with limited accuracy and functionality.
static int	STATUS_OUT_OF_SERVICE Location service is not available and the condition is not expected to resolve itself soon.
static int	STATUS_TEMPORARILY_UNAVAILABLE Location service temporarily unavailable.

Constructor Summary

Constructors

Constructor and Description
IALocationManager()

Method Summary

Modifier and Type	Method and Description
abstract void	addGeofences(IAGeofenceRequest request, IAGeofenceListener listener)
abstract void	addGeofences(IAGeofenceRequest request, IAGeofenceListener listener, android.os.Looper looper) Register for geofence event updates using listener.
abstract void	addGeofences(IAGeofenceRequest request, android.app.PendingIntent pendingIntent) Request geofence events that are delivered to an application component specified by a PendingIntent.
static IALocationManager	create(android.content.Context context) Recommended constructor.
static IALocationManager	create(android.content.Context context, android.os.Bundle extras) Creates a new instance of IALocationManager.
abstract void	destroy() Release all resources allocated by this class.
abstract IAExtraInfo	getExtraInfo() Returns additional information not vital for the functionality of the SDK.
static String	getVersion() Deprecated. Use getExtraInfo() to obtain SDK version information.
abstract boolean	registerOrientationListener(IAOrientationRequest request, IAOrientationListener listener) Add a listener for device heading and orientation.
abstract boolean	registerRegionListener(IARegion.Listener listener) Add a listener for region events.
abstract void	removeGeofences(List<String> geofenceRequestIds) Remove geofences from monitoring.
abstract boolean	removeGeofenceUpdates(IAGeofenceListener listener) Removes all updates for the specific listener.
abstract void	removeGeofenceUpdates(android.app.PendingIntent pendingIntent) Removes all updates for the specific pendingIntent.
abstract boolean	removeLocationUpdates(IALocationListener listener) Removes all updates for the specific listener.
abstract void	removeLocationUpdates(android.app.PendingIntent pendingIntent) Removes all updates for the specific pendingIntent.
abstract boolean	requestLocationUpdates(IALocationRequest request, IALocationListener listener)
abstract boolean	requestLocationUpdates(IALocationRequest request, IALocationListener listener, android.os.Looper looper) Register for location updates using request and listener.
abstract void	requestLocationUpdates(IALocationRequest request, android.app.PendingIntent pendingIntent) Request location and status updates updates that are delivered to an application component specified by a PendingIntent.
abstract void	setLocation(IALocation location) Indicate current location to positioning service.
abstract boolean	unregisterOrientationListener(IAOrientationListener listener) Remove orientation listener.
abstract boolean	unregisterRegionListener(IARegion.Listener listener) Remove region listener.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

STATUS_OUT_OF_SERVICE

public static final int STATUS_OUT_OF_SERVICE

Location service is not available and the condition is not expected to resolve itself soon.

See Also:

Constant Field Values

STATUS_TEMPORARILY_UNAVAILABLE

public static final int STATUS_TEMPORARILY_UNAVAILABLE

Location service temporarily unavailable. This could be due to no network connectivity.

See Also:

Constant Field Values

STATUS_AVAILABLE

public static final int STATUS_AVAILABLE

Location service running normally.

See Also:

Constant Field Values

STATUS_LIMITED

public static final int STATUS_LIMITED

Location service is running but with limited accuracy and functionality. This may be e.g. if Wifi information is not available due to user has disabled wifi scanning or permission is not granted (Android 6.0).

If running on Android 6.0, make sure you have checked that at least Manifest.permission.ACCESS_COARSE_LOCATION has been granted.

See Also:

Constant Field Values

STATUS_CALIBRATION_CHANGED

public static final int STATUS_CALIBRATION_CHANGED

Calibration Quality Indicator
Bundle extras: quality (Integer)

CALIBRATION_POOR

CALIBRATION_GOOD

CALIBRATION_EXCELLENT

See Also:

Constant Field Values

EXTRA_API_KEY

public static final String EXTRA_API_KEY

Extra attribute key to configure IndoorAtlas API key at run time. This is an optional way of configuring API credentials. If no key and secret is defined, SDK will try to read this information from meta-data attributes in AndroidManifest.xml. See documentation's Getting Started section for more info.

See Also:

create(Context, Bundle), Constant Field Values

EXTRA_API_SECRET

public static final String EXTRA_API_SECRET

Extra attribute key to configure IndoorAtlas API secret at run time. This is an optional way of configuring API credentials. If not key and secret is defined, SDK will try to read this information from meta-data attributes in AndroidManifest.xml. See documentation's Getting Started section for more info.

See Also:

create(Context, Bundle), Constant Field Values

EXTRA_PROXY_ADDRESS

public static final String EXTRA_PROXY_ADDRESS

Extra attribute key to configure SDK to use proxy address for communication. This is an optional way of configuring proxy. If proxy address is not defined, SDK will try to read this information from meta-data attributes in AndroidManifest.xml and if that is not defined proxy information is read from System properties.

See Also:

Constant Field Values

EXTRA_PROXY_PORT

public static final String EXTRA_PROXY_PORT

Extra attribute key to configure SDK to use proxy port for communication. This is an optional way of configuring proxy. If proxy port is not defined, SDK will try to read this information from meta-data attributes in AndroidManifest.xml and if that is not defined proxy information is read from System properties.

See Also:

Constant Field Values

EXTRA_PROXY_DISABLED

public static final String EXTRA_PROXY_DISABLED

Extra attribute key to disable SDK to use proxy port for communication. This is an optional way of configuring proxy. If information is not defined, SDK will try to read this from meta-data attributes in AndroidManifest.xml. By default using proxy is allowed.

See Also:

Constant Field Values

EXTRA_LOCATION

public static final String EXTRA_LOCATION

Extra attribute key used when location updates are delivered in an Intent after requesting location updates with requestLocationUpdates(IALocationRequest, PendingIntent). The IALocation is stored as a byte array. Please use IALocation.from(Intent) to obtain the IALocation from the extras.

See Also:

Constant Field Values

EXTRA_GEOFENCE_EVENT

public static final String EXTRA_GEOFENCE_EVENT

Extra attribute key used when geofence events are delivered in an Intent after requesting geofence events with #requestGeofenceUpdates(PendingIntent). The IAGeofenceEvent is stored as a byte array. Please use IAGeofenceEvent.from(Intent) to obtain the IAGeofenceEvent from the extras.

See Also:

Constant Field Values

CALIBRATION_POOR

public static final int CALIBRATION_POOR

Calibration is required

See Also:

Constant Field Values

CALIBRATION_GOOD

public static final int CALIBRATION_GOOD

Calibration is acceptable, but recommended

See Also:

Constant Field Values

CALIBRATION_EXCELLENT

public static final int CALIBRATION_EXCELLENT

Calibration is not required

See Also:

Constant Field Values

Constructor Detail

IALocationManager

public IALocationManager()

Method Detail

create

public static IALocationManager create(android.content.Context context)

Recommended constructor. Creates a new instance of IALocationManager.

Parameters:

context -

create

public static IALocationManager create(android.content.Context context,
                                       android.os.Bundle extras)

Creates a new instance of IALocationManager.

Parameters:

context -

extras - extra arguments to service. See EXTRA_ constant fields for this class.

destroy

public abstract void destroy()

Release all resources allocated by this class. Remember to pair a call to create(Context) with a corresponding call to this method. Calling any method after calling destroy will throw a IllegalStateException.

requestLocationUpdates

public abstract boolean requestLocationUpdates(IALocationRequest request,
                                               IALocationListener listener,
                                               android.os.Looper looper)

Register for location updates using request and listener.

Parameters:

request - contains parameters for location manager to choose how updates are delivered to listener

listener - a IALocationListener that's IALocationListener.onLocationChanged(IALocation) will be invoked on each update. Invocations are made in main thread.

looper - a looper who's callback mechanism will be used to deliver callbacks or null to use main thread.

Returns:

true if listener was successfully registered (or already registered), false if registering failed.

Throws:

IllegalArgumentException - if request is null

IllegalArgumentException - if listener is null

IllegalStateException - if called after destroy() has been called

requestLocationUpdates

public abstract boolean requestLocationUpdates(IALocationRequest request,
                                               IALocationListener listener)

See Also:

requestLocationUpdates(IALocationRequest, IALocationListener)

requestLocationUpdates

public abstract void requestLocationUpdates(IALocationRequest request,
                                            android.app.PendingIntent pendingIntent)

Request location and status updates updates that are delivered to an application component specified by a PendingIntent. The location and status updates are in the extras of the Intent. Use IALocation.from(Intent) to obtain the location update.

Please see the Android documentation how to configure the PendingIntent.

Requesting location updates with this method leaves the IndoorAtlas location service running in the background until removeLocationUpdates(PendingIntent) is called with a matching PendingIntent. Alternatively it can be killed manually by the user or the entire process killed by Android to save resources.

Parameters:

request - contains parameters for location manager to choose how updates are delivered to listener

pendingIntent - specifies what component is notified with location updates

Throws:

IllegalArgumentException - if request is null

IllegalArgumentException - if pendingIntent is null

IllegalStateException - if called after destroy() has been called

See Also:

EXTRA_LOCATION

removeLocationUpdates

public abstract boolean removeLocationUpdates(IALocationListener listener)

Removes all updates for the specific listener. After call to this method, updates will no longer be delivered to the listener.

Parameters:

listener - a listener object that will no longer need location updates

Returns:

true if listener was registered and is now removed, otherwise false.

Throws:

IllegalArgumentException - if listener is null.

IllegalStateException - if called after destroy() has been called

removeLocationUpdates

public abstract void removeLocationUpdates(android.app.PendingIntent pendingIntent)

Removes all updates for the specific pendingIntent. After call to this method, updates will no longer be delivered to the application component.

Parameters:

pendingIntent - a PendingIntent that will no longer need location updates false.

Throws:

IllegalArgumentException - if pendingIntent is null.

IllegalStateException - if called after destroy() has been called

setLocation

public abstract void setLocation(IALocation location)

Indicate current location to positioning service. This method can be used to set either the explicit location (latitude, longitude, accuracy, floor level) or the explicit region id.

Explicit location is used as a hint in the system. This means that the inputted location is used only to determine the initial position. Example use cases:

1.) Set user location to WGS84 coordinates 60.01 latitude and 24.123 longitude with approximate accuracy of 5 meters and floor level 3.

     IALocationManager.setLocation(IALocation.Builder()
                                   .withLatitude(60.01)
                                   .withLongitude(24.123)
                                   .withAccuracy(5.0)
                                   .withFloorLevel(3)
                                   .build());
 

Value of accuracy determines how strongly the horizontal position information is used. For example, if there is no good knowledge about horizontal position, but floor level is known, set accuracy to some large value (e.g. 75 meters).

2.) Set user location to WGS84 coordinates 60.01 latitude and 24.123 longitude with approximate accuracy of 5 meters and no information about floor level. In this case, IA floor detection is used to infer the floor level.

     IALocationManager.setLocation(IALocation.Builder()
                                   .withLatitude(60.01)
                                   .withLongitude(24.123)
                                   .withAccuracy(5.0)
                                   .build());
 

Using explicit region id means that the positioning will be either

1.) Restricted to the specific floor level of the indicated floor plan

     IALocationManager.setLocation(IALocation.Builder()
                                   .withRegion(
                                      IARegion.floorPlan("floorPlanId"))
                                   .build());
 

2.) Restricted to the specific venue

     IALocationManager.setLocation(IALocation.Builder()
                                   .withRegion(
                                      IARegion.venue("locationId"))
                                   .build());
 

Using explicit location or region id inputs is generally not recommended, and should only be used in difficult signal environments where getting first fix is not possible otherwise.

Parameters:

location - location indicating current position

Throws:

IllegalArgumentException - is location is null

IllegalStateException - if called after destroy() has been called

registerRegionListener

public abstract boolean registerRegionListener(IARegion.Listener listener)

Add a listener for region events.

Parameters:

listener - a IARegion.Listener object to register

Returns:

true if listener was successfully registered, false if already registered.

Throws:

IllegalArgumentException - if listener is null

IllegalStateException - if called after destroy() has been called

unregisterRegionListener

public abstract boolean unregisterRegionListener(IARegion.Listener listener)

Remove region listener.

Parameters:

listener - a IARegion.Listener object to be removed

Returns:

true if listener was successfully unregistered, false if was not found.

Throws:

IllegalArgumentException - if listener is null

IllegalStateException - if called after destroy() has been called

registerOrientationListener

@Beta
public abstract boolean registerOrientationListener(IAOrientationRequest request,
                                                          IAOrientationListener listener)

Add a listener for device heading and orientation. Heading and orientation updates are not given unless positioning is started with requestLocationUpdates(IALocationRequest, IALocationListener). The sensitivity of updates is configured using IAOrientationRequest. It is possible to receive more frequent updates than specified in the request if there are multiple listeners. The returned orientation represents the current best estimate and can exhibit sudden jumps. The orientation should be be filtered if used in e.g. virtual reality applications.

Parameters:

request - Request indicating sensitivity

listener - a IAOrientationListener object to register

Returns:

true if listener was successfully registered, false if already registered.

Throws:

IllegalArgumentException - if listener is null

IllegalStateException - if called after destroy() has been called

unregisterOrientationListener

@Beta
public abstract boolean unregisterOrientationListener(IAOrientationListener listener)

Remove orientation listener.

Parameters:

listener - a IAOrientationListener object to be removed

Returns:

true if listener was successfully unregistered, false if was not found.

Throws:

IllegalArgumentException - if listener is null

IllegalStateException - if called after destroy() has been called

getExtraInfo

public abstract IAExtraInfo getExtraInfo()

Returns additional information not vital for the functionality of the SDK.

Returns:

Extraneous information.

Throws:

IllegalStateException - if called after destroy() has been called

getVersion

@Deprecated
public static String getVersion()

Deprecated. Use getExtraInfo() to obtain SDK version information.

Returns SDK version information.

removeGeofences

@Beta
public abstract void removeGeofences(List<String> geofenceRequestIds)

Remove geofences from monitoring.

Parameters:

geofenceRequestIds - List of geofence ID's we no longer wish to monitor.

Throws:

IllegalStateException - if called after destroy() has been called

addGeofences

@Beta
public abstract void addGeofences(IAGeofenceRequest request,
                                        IAGeofenceListener listener,
                                        android.os.Looper looper)

Register for geofence event updates using listener.

Parameters:

listener - a IAGeofenceListener that's IAGeofenceListener.onGeofencesTriggered(IAGeofenceEvent) will be invoked on each update. Invocations are made in main thread.

Throws:

IllegalArgumentException - if listener is null

IllegalStateException - if called after destroy() has been called

addGeofences

@Beta
public abstract void addGeofences(IAGeofenceRequest request,
                                        IAGeofenceListener listener)

See Also:

addGeofences(IAGeofenceRequest, IAGeofenceListener, Looper)

removeGeofenceUpdates

@Beta
public abstract boolean removeGeofenceUpdates(IAGeofenceListener listener)

Removes all updates for the specific listener. After call to this method, updates will no longer be delivered to the listener.

Parameters:

listener - a listener object that will no longer need location updates

Returns:

true if listener was registered and is now removed, otherwise false.

Throws:

IllegalArgumentException - if listener is null.

IllegalStateException - if called after destroy() has been called

addGeofences

@Beta
public abstract void addGeofences(IAGeofenceRequest request,
                                        android.app.PendingIntent pendingIntent)

Request geofence events that are delivered to an application component specified by a PendingIntent. The location and status updates are in the extras of the Intent. Use IALocation.from(Intent) to obtain the location update.

Please see the Android documentation how to configure the PendingIntent.

Parameters:

pendingIntent - specifies what component is notified with geofence events

Throws:

IllegalArgumentException - if pendingIntent is null

IllegalStateException - if called after destroy() has been called

See Also:

EXTRA_GEOFENCE_EVENT

removeGeofenceUpdates

@Beta
public abstract void removeGeofenceUpdates(android.app.PendingIntent pendingIntent)

Removes all updates for the specific pendingIntent. After call to this method, geofence events will no longer be delivered to the application component.

Parameters:

pendingIntent - a PendingIntent that will no longer need geofence events.

Throws:

IllegalArgumentException - if pendingIntent is null.

IllegalStateException - if called after destroy() has been called