HERE Android SDK Developer's Guide

PositioningManager

The class PositioningManager is a member of com.here.android.mpa.common .

Class Summary

public final class PositioningManager

extends java.lang.Object

Represents a manager for information received from positioning devices, such as updates to the current position and the average speed.

[For complete information, see the section Class Details]

Nested Class Summary

Table 1. Nested Classes in PositioningManager
Nested Classes

public static final enumeration PositioningManager.LocationMethod

Represents values describing the location method.

public static final enumeration PositioningManager.LocationStatus

Represents values describing the location status of a particular location method.

public static final enumeration PositioningManager.LogType

Defines the available log types for GPX logging.

public static abstract interface PositioningManager.OnPositionChangedListener

Represents an interface for position update listeners.

Method Summary

Table 2. Methods in PositioningManager
Methods

public void addListener (java.lang.ref.WeakReference <OnPositionChangedListener> listener)

Adds a PositioningManager.OnPositionChangedListener to the PositioningManager .

public double getAverageSpeed ()

Gets the average speed of travel, in meters per second.

public LocationDataSource getDataSource ()

Get the current location data source used to provide position updates

public static PositioningManager getInstance ()

Get access to the PositioningManager Singleton

public GeoPosition getLastKnownPosition ()

Returns the last known (cached) position from the best available provider.

public LocationMethod getLocationMethod ()

Gets the method type used to determine positioning.

public LocationStatus getLocationStatus (LocationMethod method)

Gets the status for a specified LocationMethod .

public java.util.EnumSet <LogType> getLogType ()

Returns the current GPX logging configuration.

public GeoPosition getPosition ()

Gets the GeoPosition for the current PositioningManager.LocationMethod if available.

public RoadElement getRoadElement ()

Get the RoadElement of the current position.

public boolean hasValidPosition ()

Determines whether the current position for the current active PositioningManager.LocationMethod is valid.

public boolean hasValidPosition (LocationMethod method)

Determines whether the current position for the specified LocationMethod is valid.

public boolean isActive ()

Determines whether the PositioningManager is active and whether position updates are being received.

public void removeListener (OnPositionChangedListener listener)

Removes a PositioningManager.OnPositionChangedListener from the PositioningManager .

public boolean setDataSource (LocationDataSource source)

Set the location data source from which to receive position updates.

public void setLogType (java.util.EnumSet <LogType> logType)

Configures position update logging.

public boolean start (LocationMethod method)

Starts receiving position updates from the current location data source.

public void stop ()

Stops receiving position updates from the positioning device.

Class Details

Represents a manager for information received from positioning devices, such as updates to the current position and the average speed.

If the user of the application revokes the ACCESS_FINE_LOCATION permission at runtime while PositioningManager is active, the application will stop receiving location updates and methods of PositioningManager will stop functioning properly until the ACCESS_FINE_LOCATION permission is restored.

Method Details

public void addListener (java.lang.ref.WeakReference <OnPositionChangedListener> listener)

Adds a PositioningManager.OnPositionChangedListener to the PositioningManager .

Parameters:

  • listener

    A WeakReference of the OnPositionChangedListener to add.

See also:

removeListener(OnPositionChangedListener)

public double getAverageSpeed ()

Gets the average speed of travel, in meters per second.

Returns:

The average speed

public LocationDataSource getDataSource ()

Get the current location data source used to provide position updates

Returns:

LocationDataSource passed to setDataSource or null if the current location data source is the HERE SDK default.

public static PositioningManager getInstance ()

Get access to the PositioningManager Singleton

Returns:

PositioningManager instance

public GeoPosition getLastKnownPosition ()

Returns the last known (cached) position from the best available provider. This is useful if there is no valid device position available (i.e. hasValidPosition() returns false). If hasValidPosition() returns true, please use the getPosition() API.

There is no guarantee regarding the freshness of the returned position. If no cached position is available, an invalid GeoPosition is returned (can be checked by way of isValid()).

Returns:

Last known position from the best available provider. Or an invalid GeoPosition if not available.

See also:

getPosition()

public LocationMethod getLocationMethod ()

Gets the method type used to determine positioning.

Returns:

The LocationMethod

public LocationStatus getLocationStatus (LocationMethod method)

Gets the status for a specified LocationMethod .

Parameters:

  • method

    A LocationMethod used to determine the location status

Returns:

The status of the specified LocationMethod

public java.util.EnumSet <LogType> getLogType ()

Returns the current GPX logging configuration.

Defaults to an empty EnumSet (no logging).

Returns:

The set of all enabled log types.

See also:

{@code LogType}

public GeoPosition getPosition ()

Gets the GeoPosition for the current PositioningManager.LocationMethod if available.

Availability of a position can be checked by way of the hasValidPosition() method, if that method returns false, the best available cached position can be obtained using the getLastKnownPosition() API.

The position returned is determined by the following criteria:

  • If Navigation is active, the MatchedGeoPosition is returned, else
  • If a valid position fix is available for the active PositioningManager.LocationMethod than it is returned. else,
  • An invalid GeoPosition is returned (this can be checked by way of isValid()

Returns:

The current GeoPosition

See also:

getLastKnownPosition()

public RoadElement getRoadElement ()

Get the RoadElement of the current position.

Returns:

A RoadElement object representing the road element at the current position.

public boolean hasValidPosition ()

Determines whether the current position for the current active PositioningManager.LocationMethod is valid.

Returns:

True if the position is valid, false otherwise

See also:

hasValidPosition(LocationMethod)

public boolean hasValidPosition (LocationMethod method)

Determines whether the current position for the specified LocationMethod is valid.

Parameters:

  • method

    A LocationMethod to check for a valid position

Returns:

True if the position is valid, false otherwise

See also:

hasValidPosition()

public boolean isActive ()

Determines whether the PositioningManager is active and whether position updates are being received.

Returns:

True if the PositioningManager is actively receiving position updates, false otherwise

public void removeListener (OnPositionChangedListener listener)

Removes a PositioningManager.OnPositionChangedListener from the PositioningManager .

Parameters:

  • listener

    A OnPositionChangedListener to remove

See also:

addListener(WeakReference<OnPositionChangedListener>)

public boolean setDataSource (LocationDataSource source)

Set the location data source from which to receive position updates.

Note: The default HERE SDK data source supports the GPS and network location methods.

Parameters:

  • source

    LocationDataSource used to provide position updates. Specify null to use the default location data source provided by the HERE SDK.

Returns:

True if the data source was set successfully, false otherwise. One reason for returning false is that positioning is currently active and the new location source could not be started with the current location method.

public void setLogType (java.util.EnumSet <LogType> logType)

Configures position update logging.

LogType.DATA_SOURCE will log "input positions" from the current LocationDataSource if the data source supports GPX logging. HERE SDK default data sources that use Android Location Manager will log to a GPX file ending with the suffix "_lm". This GPX file is suitable for playback via PositionSimulator.

LogType.RAW and LogType.MATCHED will log the results of processing the input position from the current data source. The content of these logs represents historical values that getPosition() would return. GPX logs produced for these logging types are for analysis only and are not suitable for playback via PositionSimulator.

GPX logs will be written to a "gpx" sub directory of the Appication's data directory (for example, "/sdcard/Android/data/com.companyName.appName/files/gpx/". Logs will be prefixed with a timestamp representing the time logging was enabled and suffix indicating the log type.

To ensure log files are flushed to disk make sure logging is disabled prior to application exit. Logging is disabled by setting the log type to EnumSet.noneOf(LogType.class).

Defaults to an empty EnumSet (no logging).

IMPORTANT: Logging should NOT be permanently enabled in production builds submitted to the Google Play Store.

Parameters:

See also:

{@code LogType}

public boolean start (LocationMethod method)

Starts receiving position updates from the current location data source.

When using LocationDataSourceDevice (the default) or LocationDataSourceHERE, this method will return false and the PositioningManager will not be started if the application does not have the {@code ACCESS_FINE_LOCATION) permission at the time of this call.

Parameters:

  • method

    LocationMethod used to provide position updates

Returns:

True if current location data source was started OK, false otherwise (this may indicate the application does not have the ACCESS_FINE_LOCATION permission at the time of this call).

public void stop ()

Stops receiving position updates from the positioning device.