Navigation Class Reference

This class enables Route calculations and Route Guidance
More...

Inheritance diagram for Navigation:

Public Member Functions
void	addTaskListener (TaskListener listener)
Task< Void >	calculateRoute ()
Task< Void >	calculateRoutes (final int numRoutes)
String	copyCurrentRoute ()
boolean	equals (Object o)
native FollowMeRoute	getInjectedFollowMeRoute ()
native Itinerary	getItinerary ()
String	getNextCrosswayGeometry (final NavGeometryFormat format)
Iterable< Polygon >	getRouteExtents (final boolean fromCurrentRoute, final boolean currentRouteFromCurrentPosition, final double lengthInMeters)
Navigation	getRouteNumber (final int routeNumber)
int	getRouteStatistic (final NavRouteStatistic statisticitem, final int firstStop, final int lastStop)
native ApiError	injectFollowMeRoute (FollowMeRoute fmr)
	Navigation ()
void	removeAllTaskListeners ()
void	removeTaskListener (TaskListener listener)
native ApiError	setItinerary (Itinerary itn)
Task< Void >	setRoute (final String fileName)
ApiError	setSimulationPosOnRoute (final double posOnRoute)
ApiError	startNavigation ()
ApiError	startSimulatedNavigation ()

Static Public Member Functions
static void	addNavigationListener (NavigationListener listener)
static ApiError	blockRouteBySelection (final Selection selHandle)
static Navigation	getActiveNavigation ()
static native ComputationSite	getAllowedComputationSite ()
static native ComputationSite	getAvailableComputationSites ()
static Iterable< Polygon >	getCurrentRoute ()
static native boolean	getLezEnabled ()
static native LezGermanVignetteType	getLezGermanVignette ()
static native boolean	getRouteAvoidFerry ()
static native boolean	getRouteAvoidHighway ()
static native boolean	getRouteAvoidToll ()
static native int	getRouteRecklessRadiusMeters ()
static native boolean	getRouteUseOffboardTraffic ()
static native RoutingContext	getRoutingContext ()
static native RoutingType	getRoutingType ()
static native boolean	isLezDataAvailable ()
static void	removeAllNavigationListeners ()
static void	removeNavigationListener (NavigationListener listener)
static int	removeRouteBlockingSelection ()
static ApiError	setAllowedComputationSite (final ComputationSite computationSite)
static ApiError	setLezEnabled (final boolean lezEnabled)
static ApiError	setLezGermanVignette (final LezGermanVignetteType lezVignette)
static ApiError	setRouteAvoidFerry (final boolean avoid)
static ApiError	setRouteAvoidHighway (final boolean avoid)
static ApiError	setRouteAvoidToll (final boolean avoid)
static native ApiError	setRouteRecklessRadiusMeters (int recklessRadiusMeters)
static ApiError	setRouteUseOffboardTraffic (final boolean use)
static ApiError	setRoutingContext (final RoutingContext routingContext)
static ApiError	setRoutingType (final RoutingType routingType)
static ApiError	stopNavigation ()
static ApiError	stopSimulatedNavigation ()

Detailed Description

The Navigation class allow route calculation based on Itineraries. These Routes can be

• displayed on the map by using Mapviewer.showRoute().
• used for a navigation (route guidance) with audio instructions, automatic rerouting and feedback on the progress like Estimated Time of Arrival, distance to destination, lane info, speed warnings and more.
  After navigation has been started (Navigation.startNavigation()), the used route is displayed automatically in the map.
  
  

The route calculation is an asynchronous process. A call to Navigation.calculateRoute() will return a Task object. The Navigation instance provides a set of listeners which can be registered and which provide information on the progress ( TaskListener.taskProgress() ) and finished state ( TaskListener.taskFinished() )

A task for a routing process can be created in different scenarios:

• By the Navigation.calculateRoute() method, a task will be returned that indicates the routing progress and finished events when the route is calculated.
• By the NavigationListener.rerouting() callback which indicates a rerouting for the navigation instance.

Each navigation instance can have one callback for the task progress and finished events. Therefore tasks can be compared with the isIdentical method For example: The task initiated with Navigation.calculateRoute() can be stored and compared to the task received in the TaskListener.taskFinished() to differ initial routing results from rerouting results.

Constructor & Destructor Documentation

Navigation()

Navigation

(

)

Member Function Documentation

addNavigationListener()

static void addNavigationListener ( NavigationListener  listener )

static

addTaskListener()

void addTaskListener

(

TaskListener

listener

)

blockRouteBySelection()

static ApiError blockRouteBySelection ( final Selection  selHandle )

static

Blocks the route by all polylines, contained in the Selection.

Parameters

selHandle

- The Selection object

calculateRoute()

Task< Void > calculateRoute

(

)

Calculates a route based on the Itinerary

Precondition

Requires: previous call to Navigation.setItinerary() with a valid Itinerary.

Returns

a task that asynchronously calculates the route. By registering the task callbacks for a navigation instance, the state of the route calculation can be retrieved.
The task can return (BaseTask.getReturnValue()) the following Errorcodes

• ApiError.NOT_ENOUGH_STATIONS if Itinerary has < 2 waypoints
• ApiError.INVALID_OBJECT if navigation instance is not valid ( e.g. Api.uninitialize() has been called )
• ApiError.OK if route was successfully calculated
• ApiError.OPERATION_CANCELLED if the user aborts the route calculation task
• ApiError.NETWORK if an offboard route is calculated but no network connection is available
• ApiError.ROUTING if one of the destinations is not inside the installed Map data. This can also relate to a wrong projection (use internal projection Projection )

Additionally the route calculation can return error codes that indicate a warning. In this case a route is calculated but the user should be informed about an exceptional situation e.g. if the destination can not be reached with the configured vehicle.

 @arg @ref MTA_ERROR "ApiError.WARNING_ROUTE_OBST_FOUND" The route contains one or more obstacles

calculateRoutes()

Task< Void > calculateRoutes

(

final int

numRoutes

)

Calculates numRoutes routes based on the Itinerary

Returns

a task that asynchronously calculates the route. By registering the task callbacks for a navigation instance, the state of the route calculation can be retrieved.
The task can return (BaseTask.getReturnValue()) the following Errorcodes

• ApiError.NOT_ENOUGH_STATIONS if Itinerary has < 2 waypoints
• ApiError.INVALID_OBJECT if navigation instance is not valid ( e.g. Api.uninitialize() has been called )
• ApiError.OK if route was successfully calculated
• ApiError.OPERATION_CANCELLED if the user aborts the route calculation task
• ApiError.NETWORK if an offboard route is calculated but no network connection is available
• ApiError.ROUTING if one of the destinations is not inside the installed Map data. This can also relate to a wrong projection (use internal projection Projection )

Additionally the route calculation can return error codes that indicate a warning. In this case a route is calculated but the user should be informed about an exceptional situation e.g. if the destination can not be reached with the configured vehicle.

 @arg @ref MTA_ERROR "ApiError.WARNING_ROUTE_OBST_FOUND" The route contains one or more obstacles

copyCurrentRoute()

String copyCurrentRoute

(

)

Copy the route shape of the currently active navigation. This can be used as an argument for mta_nav_setRoute() to syncronized two Navigation instances.

Returns

full file path and name of the route shape currently used for navigation

Errorcode

• ApiError.OK if pathName points to a valid route file
• ApiError.NO_ROUTE if the current navigation has no route
• ApiError.ASYNC_OPERATION_STILL_RUNNING if a route calculation is currently in progress

equals()

boolean equals ( Object  o )

inherited

getActiveNavigation()

static Navigation getActiveNavigation ( )

static

Returns

The active navigation. If there is no active navigation, then the returned object is invalid. Call Api.getLastError() to check whether the returned object is valid.

getAllowedComputationSite()

static native ComputationSite getAllowedComputationSite ( )

static

Returns

Retrieves the routing sites, which are currently allowed.

getAvailableComputationSites()

static native ComputationSite getAvailableComputationSites ( )

static

Returns

the routing sites, which are possible with this configuration.

getCurrentRoute()

static Iterable< Polygon > getCurrentRoute ( )

static

Returns

an iterator of the segments of the currently used route.

Precondition

Requires: previous successful call to Navigation.startNavigation() or Navigation.startSimulatedNavigation().

Returns

Errorcode

• ApiError.OK if successful
• ApiError.NO_ROUTE if there is no active RouteGuidance.

getInjectedFollowMeRoute()

native FollowMeRoute getInjectedFollowMeRoute

(

)

Returns the FollowMeRoute, that is injected by Navigation.injectFollowMeRoute() If no FollowMeRoute was injected, ApiError.OBJ_NOT_FOUND is returned.

getItinerary()

native Itinerary getItinerary

(

)

Returns

the itinerary of the current navigation.

getLezEnabled()

static native boolean getLezEnabled ( )

static

Returns

true if routing for Low emission zones is active

getLezGermanVignette()

static native LezGermanVignetteType getLezGermanVignette ( )

static

Get german vignette type (Umweltzonenplakettentyp) for low emission zones routing.

Returns

LezGermanVignetteType

getNextCrosswayGeometry()

String getNextCrosswayGeometry

(

final NavGeometryFormat

format

)

Returns the geometry of the next crossway of interest of an active guidance.

Parameters

format

- The format of the result (see NavGeometryFormat)

Returns

The result string

getRouteAvoidFerry()

static native boolean getRouteAvoidFerry ( )

static

Returns

true if avoiding Ferries

getRouteAvoidHighway()

static native boolean getRouteAvoidHighway ( )

static

Returns

true if avoiding highways

getRouteAvoidToll()

static native boolean getRouteAvoidToll ( )

static

Returns

true if avoiding toll roads

getRouteExtents()

Iterable< Polygon > getRouteExtents	(	final boolean	fromCurrentRoute,
		final boolean	currentRouteFromCurrentPosition,
		final double	lengthInMeters
	)

Parameters

fromCurrentRoute-	true to calculate the extend only for the current interstation, false to calculate over all interstations
currentRouteFromCurrentPosition	- true to calculate the extend from the current position, false to calculate for the whole route
lengthInMeters	- maximum route length in meters that the extend will cover

Returns

A polygon for every interstation defining the routes extent.

Precondition

Requires: previous successful call to Navigation.calculateRoute().

getRouteNumber()

Navigation getRouteNumber

(

final int

routeNumber

)

Returns a new navigation object with the given route (routeNumber) selected.

Parameters

rootNavHandle	- The navigation handle on which multiple routes have been calculated
rootNumber	- The route number to select (beginning with 0)

Returns

Errorcode

• ApiError.OK if successful

getRouteRecklessRadiusMeters()

static native int getRouteRecklessRadiusMeters ( )

static

Get the emergency routing (reckless driving) radius in meters.

Returns

reckless radius in meters (0 when deactivated)

Errorcode

• ApiError.OK on success

getRouteStatistic()

int getRouteStatistic	(	final NavRouteStatistic	statisticitem,
		final int	firstStop,
		final int	lastStop
	)

Calculates a statistic of a selected type (e.g. fuel consumption or route length) for a specific start Waypoint to a specific end Waypoint in the Itinerary.

Parameters

statisticitem	- Defines which statistic item shall be calculated like driving time or route length (see NavRouteStatistic)
firstStop	- Index of the first Waypoint in the Itinerary that shall be included in the statistic calculations.
lastStop	- Index of the last Waypoint in the Itinerary that shall be included in the statistic calculations

Returns

• if > 0 a summarized statistic value for the selected statisticitem and the given range of stops
• if < 0 an errorcode of ApiError

getRouteUseOffboardTraffic()

static native boolean getRouteUseOffboardTraffic ( )

static

See Navigation.setRouteUseOffboardTraffic() for a detailed description.

Returns

true if the offboard routing will take the current traffic for the route calculation into account.

getRoutingContext()

static native RoutingContext getRoutingContext ( )

static

Retrieves the (offboard) routing context for navigation

Returns

Routing context. See RoutingContext

getRoutingType()

static native RoutingType getRoutingType ( )

static

Returns

Retrieves the routing objective for navigation (fastest, shortest...)

injectFollowMeRoute()

native ApiError injectFollowMeRoute

(

FollowMeRoute

fmr

)

Instead of setting an itinerary, you may inject a FollowMeRoute as a "destination". If you start a Navigation with an injected FollowMeRoute, some things change:

• The route calculation uses the starting point of the FollowMeRoute as the destination.
• The distance to the destination and the remaining driving time is the sum of the ordinary route and the FollowMeRoute.
• If you show this Navigation o a map, the FollowMeRoute is shown too. It is still possible to calculate alternative routes an you still get route updates, if you use online routing.

  Parameters

  fmr	- the FollowMeRoute, that should be injected.

  Returns

  Errorcode

  • ApiError.OK if successful
  • ApiError.OPERATION_INVALID else.

isLezDataAvailable()

static native boolean isLezDataAvailable ( )

static

Returns

true if Low emission zone data is available in the dataset

removeAllNavigationListeners()

static void removeAllNavigationListeners ( )

static

removeAllTaskListeners()

void removeAllTaskListeners

(

)

removeNavigationListener()

static void removeNavigationListener ( NavigationListener  listener )

static

removeRouteBlockingSelection()

static int removeRouteBlockingSelection ( )

static

Releases the blocking performed by Navigation.blockRouteBySelection().

Returns

Errorcode

• ApiError.OK if successful

removeTaskListener()

void removeTaskListener

(

TaskListener

listener

)

setAllowedComputationSite()

static ApiError setAllowedComputationSite ( final ComputationSite  computationSite )

static

Sets the allowed routing sites.

Parameters

computationSite

See ComputationSite

Returns

Errorcode

• ApiError.OK if successful

setItinerary()

native ApiError setItinerary

(

Itinerary

itn

)

Parameters

itn	- the itinerary for the navigation. It is not possible to change the itinerary of the running navigation. Call mta_nav_stopNavigation before.

Returns

Errorcode

• ApiError.OK if successful
• ApiError.OPERATION_INVALID if you try to change the itinerary of the running navigation.

setLezEnabled()

static ApiError setLezEnabled ( final boolean  lezEnabled )

static

Parameters

lezEnabled

- true to enable low emission zones routing

Returns

Errorcode

• ApiError.OK on success

setLezGermanVignette()

static ApiError setLezGermanVignette ( final LezGermanVignetteType  lezVignette )

static

Parameters

lezVignette

type of the german Vignette (Umweltzonenplakettentyp) that will be respected by routing

Returns

Errorcode

• ApiError.OK on success

setRoute()

Task< Void > setRoute

(

final String

fileName

)

Use this function instead of Navigation.calculateRoute(), if you have already an advised route from a iwRouting server. This function opens the route (with the path, provided by the fileName parameter), creates an itinerary with the first an the last point of the route file and does some internal wiring to handle this route as an ordinary calculated route. Beware, that there will only survive the destination, if a rerouting occours.

Returns

a task, containing the result, equal to the task, returned by Navigation.calculateRoute(). By registering the task callbacks for a navigation instance, the state of the route calculation can be retrieved.
The task can return (BaseTask.getReturnValue()) the following Errorcodes

• ApiError.OK if route was successfully calculated
• ApiError.OBJ_NOT_FOUND if the route file cannot be opened
• ApiError.INVALID_OBJECT if the route file does not contain some mandatory columns
• ApiError.INTERNAL if start and destination cannot be detected.
• ApiError.WRONG_PATH if the route file cannot be copied to the api its internal working folder

setRouteAvoidFerry()

static ApiError setRouteAvoidFerry ( final boolean  avoid )

static

Parameters

avoid

if true the routing will avoid Ferries. If set while a navigation is running a re-routing will be started.

Returns

Errorcode

• ApiError.OK on success

setRouteAvoidHighway()

static ApiError setRouteAvoidHighway ( final boolean  avoid )

static

Parameters

avoid

if true the routing will avoid highways. If set while a navigation is running a re-routing will be started.

Returns

Errorcode

• ApiError.OK on success

setRouteAvoidToll()

static ApiError setRouteAvoidToll ( final boolean  avoid )

static

Parameters

avoid

if true the routing will avoid Toll routes. If set while a navigation is running a re-routing will be started.

Returns

Errorcode

• ApiError.OK on success

setRouteRecklessRadiusMeters()

static native ApiError setRouteRecklessRadiusMeters ( int  recklessRadiusMeters )

static

Set the emergency routing (reckless driving) radius in meters. If set while a navigation is running a re-routing will be started.

When set to a value greater then 0, forbidden maneuvers and one-way streets that lie within the given radius around the destination are ignored, i.e. can be used for navigation. When set to 0 then emergency routing is deactivated. This functionality is intended for police or emergency services to reach the location of an emergency as fast as possible.

Parameters

recklessRadiusMeters

Returns

Errorcode

• ApiError.OK on success

setRouteUseOffboardTraffic()

static ApiError setRouteUseOffboardTraffic ( final boolean  use )

static

If you have a license for offboard route calculation, the SDK will get all routes from the infoware routing servers. These servers take by default the current traffic for the route calculation into account. With this setter, you may switch off the usage of the traffic information. Then, the routing server will only use statistical traffic information for every further route calculation, unless you switch it on again. Be aware, that this setting will be persisted in the settings.ini (section '[ROUTING]', key name 'UseOffboardTraffic') and therefore is still active after a new start of your application.

Parameters

use	if false, the offboard routing will not take the current traffic for the route calculation into account.

Returns

Errorcode

• ApiError.OK on success

setRoutingContext()

static ApiError setRoutingContext ( final RoutingContext  routingContext )

static

Sets the (offboard) routing context for navigation

Parameters

routingContext

See RoutingContext

Returns

Errorcode

• ApiError.OK if successful

setRoutingType()

static ApiError setRoutingType ( final RoutingType  routingType )

static

Sets the routing objective for navigation

Parameters

routingType

See RoutingType

Returns

Errorcode

• ApiError.OK if successful

setSimulationPosOnRoute()

ApiError setSimulationPosOnRoute

(

final double

posOnRoute

)

Sets the start position of the next OR current simulated navigation

Returns

Errorcode

• ApiError.OK if successful

startNavigation()

ApiError startNavigation

(

)

Non-blocking call
Starts the navigation (route guidance) process. If a navigation shall be started based on a GPS log see Gps.

Precondition

Requires: previous successful call to Navigation.calculateRoute().

Returns

Errorcode

• ApiError.OK if successful

startSimulatedNavigation()

ApiError startSimulatedNavigation

(

)

The navigation is started along the calculated route with a fake GPS signal along the calculated route.
This feature is meant to be used for development and debugging purpose.

Precondition

Requires: previous successful call to Navigation.calculateRoute().

Returns

Errorcode

• ApiError.OK if successful

stopNavigation()

static ApiError stopNavigation ( )

static

Stops the navigation (route guidance) process

Returns

Errorcode

• ApiError.OK if successful

stopSimulatedNavigation()

static ApiError stopSimulatedNavigation ( )

static

Stops the simulated navigation.

Returns

Errorcode

• ApiError.OK if successful

---

The documentation for this class was generated from the following file:

• Navigation.java