Core navigation engine. More...

Inheritance diagram for gem::NavigationService:

Collaboration diagram for gem::NavigationService:

Public Member Functions
	NavigationService (const NavigationService &)=delete
	NavigationService (NavigationService &&)=default
	Default move constructor noexcept is deduced.
NavigationService &	operator= (const NavigationService &)=delete
NavigationService &	operator= (NavigationService &&navService)=default
	Default move assignment noexcept is deduced.
int	startNavigation (const LandmarkList &waypoints, const RoutePreferences &routePreferences, NavigationListener navigationListener, ProgressListener progressListener, sense::DataSourcePtr positionSource=sense::DataSourcePtr()) noexcept
	Start a new navigation.
int	startNavigation (const Route &route, NavigationListener navigationListener, ProgressListener progressListener, sense::DataSourcePtr positionSource=sense::DataSourcePtr()) noexcept
	Start a new navigation.
int	startSimulation (const LandmarkList &waypoints, const RoutePreferences &routePreferences, NavigationListener navigationListener, ProgressListener progressListener, float speedMultiplier=1.f) noexcept
	Start a new simulation.
int	startSimulation (const Route &route, NavigationListener navigationListener, ProgressListener progressListener, float speedMultiplier=1.f) noexcept
	Start a new simulation.
bool	isNavigationActive (NavigationListener navigationListener=NavigationListener()) const noexcept
	Check if there is an active navigation in progress.
bool	isSimulationActive (NavigationListener navigationListener=NavigationListener()) const noexcept
	Check if there is an active simulation in progress.
bool	isTripActive (NavigationListener navigationListener=NavigationListener()) const noexcept
	Check if there is an active trip ( navigation or simulation ) in progress.
int	skipNextIntermediateDestination (NavigationListener navigationListener=NavigationListener()) const noexcept
	Skip next intermediate destination on the navigation route.
Route	getNavigationRoute (NavigationListener navigationListener=NavigationListener()) const noexcept
	Get the current route used for navigation.
void	cancelNavigation (NavigationListener navigationListener=NavigationListener()) noexcept
	Cancel the active navigation.
NavigationService &	setNavigationRoadBlock (int length, int startDistance=-1, NavigationListener navigationListener=NavigationListener()) noexcept
	Set a roadblock on the current route having the length specified in meters starting from the current GPS position.
void	updateNavigationSound (NavigationListener navigationListener=NavigationListener()) noexcept
	Request to the navigation service to send the updated sound to the navigation listener.
TimeDistance	getBetterRouteTimeDistanceToFork (NavigationListener navigationListener=NavigationListener()) const noexcept
	Get better route time-distance until it forks the navigation route.
NavigationInstructionRef	getNavigationInstruction (NavigationListener navigationListener=NavigationListener()) const noexcept
	Get the current navigation instruction.
sense::DataSourcePtr	getDataSource (NavigationListener navigationListener) const noexcept
	Get access to navigation data source.
float	getSimulationMinSpeedMultiplier () const noexcept
	Get the minimum simulation speed multiplier.
float	getSimulationMaxSpeedMultiplier () const noexcept
	Get the maximum simulation speed multiplier.
ParameterList	getIntermediateWaypointDropParameters () const noexcept
	Get intermediate waypoint drop recommended parameters.
ParameterList	getNavigationParameters () const noexcept
	Get navigation parameters.
TransferStatisticsRef	getTransferStatistics () const noexcept
	Get data transfer statistics for this service.

Detailed Description

Core navigation engine.

Implements share-read / write Api object over INavigationService.

This behaves like a singleton, i.e. all instances are shared behind the same API interface.

Computes, manages, and updates active navigation sessions, including route following, rerouting, and turn-by-turn guidance.

Member Function Documentation

◆ cancelNavigation()

void gem::NavigationService::cancelNavigation ( NavigationListener navigationListener = NavigationListener() )

inlinenoexcept

Cancel the active navigation.

This method cancels the active navigation. If a route calculation is in progress then the registered progress listener will be signaled first with ProgressListener::notifyComplete( error::KCancel ) and then the NavigationListener::navigationError( error::KCancel ).

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

◆ getBetterRouteTimeDistanceToFork()

TimeDistance gem::NavigationService::getBetterRouteTimeDistanceToFork ( NavigationListener navigationListener = NavigationListener() ) const

inlinenoexcept

Get better route time-distance until it forks the navigation route.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

Returns: TimeDistance object containing the time and distance to the next fork

◆ getDataSource()

sense::DataSourcePtr gem::NavigationService::getDataSource ( NavigationListener navigationListener ) const

inlinenoexcept

Get access to navigation data source.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

Returns: Data source object

◆ getIntermediateWaypointDropParameters()

ParameterList gem::NavigationService::getIntermediateWaypointDropParameters ( ) const

inlinenoexcept

Get intermediate waypoint drop recommended parameters.

Possible parameters:

"waypoint_drop_radius" : large integer - radius in which the waypoint may be considered for a dropping attempt, in meters

"waypoint_drop_distance_threshold" : double - factor by which the last dropping attempt distance to waypoint should be multiplied in order to set the next dropping attempt distance,

i.e. next_drop_attempt_distance = next_drop_attempt_distance * "waypoint_drop_distance_threshold"

"waypoint_drop_min_distance_m" : large integer - minimum distance at which a waypoint may be target to a drop attempt

Returns: Parameter list

◆ getNavigationInstruction()

NavigationInstructionRef gem::NavigationService::getNavigationInstruction ( NavigationListener navigationListener = NavigationListener() ) const

inlinenoexcept

Get the current navigation instruction.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

Returns: Navigation instruction object

◆ getNavigationParameters()

ParameterList gem::NavigationService::getNavigationParameters ( ) const

inlinenoexcept

Get navigation parameters.

Possible parameters:

"tts_announce_min_traffic_delay" : large integer - the minimum traffic delay in seconds for which there should be a TTS announce

Returns: Parameter list

◆ getNavigationRoute()

Route gem::NavigationService::getNavigationRoute ( NavigationListener navigationListener = NavigationListener() ) const

inlinenoexcept

Get the current route used for navigation.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

Returns: Target route for the navigation session

◆ getSimulationMaxSpeedMultiplier()

float gem::NavigationService::getSimulationMaxSpeedMultiplier ( ) const

inlinenoexcept

Get the maximum simulation speed multiplier.

Returns: The maximum simulation speed multiplier

◆ getSimulationMinSpeedMultiplier()

float gem::NavigationService::getSimulationMinSpeedMultiplier ( ) const

inlinenoexcept

Get the minimum simulation speed multiplier.

Returns: The minimum simulation speed multiplier

◆ getTransferStatistics()

TransferStatisticsRef gem::NavigationService::getTransferStatistics ( ) const

inlinenoexcept

Get data transfer statistics for this service.

Returns: Transfer statistics object

◆ isNavigationActive()

bool gem::NavigationService::isNavigationActive ( NavigationListener navigationListener = NavigationListener() ) const

inlinenoexcept

Check if there is an active navigation in progress.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

Returns: True if there is an active navigation in progress, false otherwise

◆ isSimulationActive()

bool gem::NavigationService::isSimulationActive ( NavigationListener navigationListener = NavigationListener() ) const

inlinenoexcept

Check if there is an active simulation in progress.

Parameters

[in] navigationListener Navigation listener used to identify the simulation instance

Returns: True if there is an active simulation in progress, false otherwise

◆ isTripActive()

bool gem::NavigationService::isTripActive ( NavigationListener navigationListener = NavigationListener() ) const

inlinenoexcept

Check if there is an active trip ( navigation or simulation ) in progress.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

Returns: True if there is an active trip in progress, false otherwise

◆ operator=()

NavigationService & gem::NavigationService::operator= ( NavigationService && navService )

default

Default move assignment noexcept is deduced.

Returns: A reference to this object

Parameters

[in] navService The object to be moved

◆ setNavigationRoadBlock()

NavigationService & gem::NavigationService::setNavigationRoadBlock	(	int	length,
		int	startDistance = -1,
		NavigationListener	navigationListener = NavigationListener() )

inlinenoexcept

Set a roadblock on the current route having the length specified in meters starting from the current GPS position.

Parameters

[in]	length	The length specified in meters
[in]	startDistance	The distance from start where the roadblock begins, defaults to -1 meaning the current navigation position
[in]	navigationListener	Navigation listener used to identify the navigation session

Returns: KNoError Success

◆ skipNextIntermediateDestination()

int gem::NavigationService::skipNextIntermediateDestination ( NavigationListener navigationListener = NavigationListener() ) const

inlinenoexcept

Skip next intermediate destination on the navigation route.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

If there are no more intermediate waypoints on the route, error::KNotFound is returned

The route will be recalculated and an INavigationListener::onRouteUpdated notification will be thrown

Returns: KNoError Success

◆ startNavigation() [1/2]

int gem::NavigationService::startNavigation	(	const LandmarkList &	waypoints,
		const RoutePreferences &	routePreferences,
		NavigationListener	navigationListener,
		ProgressListener	progressListener,
		sense::DataSourcePtr	positionSource = sense::DataSourcePtr() )

inlinenoexcept

Start a new navigation.

Parameters

[in]	waypoints	List of waypoints for the navigation.
[in]	routePreferences	Route calculation preferences.
[in]	navigationListener	Listener for navigation-specific events.
[in]	progressListener	Listener to be used for signaling route calculation progress events. This will be used only when the route is calculated or recalculated.
[in]	positionSource	Source of position. Optional.

Returns: KNoError if navigation was successfully started; error::KMissingCapability if the SDK delivery was configured without navigation capabilities; error::KNotSupported if the provided routing preferences contains an unsupported configuration; error::KInvalidInput if the calculation input contains invalid data, e.g. waypoints.size() < 1; error::KNoMemory if the couldn't allocate the necessary memory for the operation; error::KInUse if a navigation / simulation session is already started; error::KRequired if the PositionService cannot provide a last valid position for using it as the first waypoint in route calculation

The last available position from the PositionService will be used as first waypoint in the navigation route calculation

For possible error codes returned in IProgressListener::notifyComplete see RoutingService::calculate()

Possible error codes returned in INavigationListener::onNavigationError

Returns: error::KCancel if the navigation was canceled by the user; error::KInvalidated if the offline map data updated during the navigation

◆ startNavigation() [2/2]

int gem::NavigationService::startNavigation	(	const Route &	route,
		NavigationListener	navigationListener,
		ProgressListener	progressListener,
		sense::DataSourcePtr	positionSource = sense::DataSourcePtr() )

inlinenoexcept

Start a new navigation.

Parameters

[in]	route	Route to use for the navigation.
[in]	navigationListener	Listener for navigation-specific events.
[in]	progressListener	Listener to be used for signaling route calculation progress events. This will be used only when the route is recalculated. This will be used only when the route is calculated or recalculated.
[in]	positionSource	Source of position. Optional.

Returns: KNoError if simulation was successfully started; error::KMissingCapability if the SDK delivery was configured without navigation capabilities; error::KNotSupported if the provided routing preferences contains an unsupported configuration; error::KInvalidInput if the input contains invalid data, e.g. route is invalid; error::KNoMemory if the couldn't allocate the necessary memory for the operation; error::KInUse if a navigation / simulation session is already started

For possible error codes returned in IProgressListener::notifyComplete see RoutingService::calculate(), triggered when navigation route is recalculated

Possible error codes returned in INavigationListener::onNavigationError

Returns: error::KCancel if the navigation was canceled by the user; error::KInvalidated if the offline map data updated during the navigation

◆ startSimulation() [1/2]

int gem::NavigationService::startSimulation	(	const LandmarkList &	waypoints,
		const RoutePreferences &	routePreferences,
		NavigationListener	navigationListener,
		ProgressListener	progressListener,
		float	speedMultiplier = 1.f )

inlinenoexcept

Start a new simulation.

Parameters

[in]	waypoints	List of waypoints for the simulation.
[in]	routePreferences	Route calculation preferences.
[in]	navigationListener	Listener for simulation-specific events.
[in]	progressListener	Listener to be used for signaling route calculation progress events. This will be used only when the route is initially calculated.
[in]	speedMultiplier	The route simulation speed multiplier. Accepted values are in the interval [getSimulationMinSpeedMultiplier, getSimulationMaxSpeedMultiplier]. If set to 1.f the simulation speed is the speed limit of the traveled links

Returns: KNoError if simulation was successfully started; error::KMissingCapability if the SDK delivery was configured without simulation capabilities; error::KNotSupported if the provided routing preferences contains an unsupported configuration; error::KInvalidInput if the calculation input contains invalid data, e.g. waypoints.size() < 1; error::KNoMemory if the couldn't allocate the necessary memory for the operation; error::KInUse if a navigation / simulation session is already started; error::KRequired if the PositionService cannot provide a last valid position for using it as the first waypoint in route calculation

The last available position from the PositionService will be used as first waypoint in the navigation route calculation

For possible error codes returned in IProgressListener::notifyComplete see RoutingService::calculate()

Possible error codes returned in INavigationListener::onNavigationError

Returns: error::KCancel if the navigation was canceled by the user; error::KInvalidated if the offline map data updated during the navigation

◆ startSimulation() [2/2]

int gem::NavigationService::startSimulation	(	const Route &	route,
		NavigationListener	navigationListener,
		ProgressListener	progressListener,
		float	speedMultiplier = 1.f )

inlinenoexcept

Start a new simulation.

Parameters

[in]	route	Route to use for the simulation.
[in]	navigationListener	Listener for simulation-specific events.
[in]	progressListener	Listener to be used for signaling route calculation progress events.
[in]	speedMultiplier	The route simulation speed multiplier. Accepted values are in the interval [getSimulationMinSpeedMultiplier, getSimulationMaxSpeedMultiplier] If set to 1.f the simulation speed is the speed limit of the traveled links

Returns: KNoError if simulation was successfully started; error::KMissingCapability if the SDK delivery was configured without navigation capabilities; error::KNotSupported if the provided routing preferences contains an unsupported configuration; error::KInvalidInput if the input contains invalid data, e.g. route is invalid; error::KNoMemory if the couldn't allocate the necessary memory for the operation; error::KInUse if a navigation / simulation session is already started

For possible error codes returned in IProgressListener::notifyComplete see RoutingService::calculate(), triggered when navigation route is recalculated

Possible error codes returned in INavigationListener::onNavigationError

Returns: error::KCancel if the navigation was canceled by the user; error::KInvalidated if the offline map data updated during the navigation

◆ updateNavigationSound()

void gem::NavigationService::updateNavigationSound ( NavigationListener navigationListener = NavigationListener() )

inlinenoexcept

Request to the navigation service to send the updated sound to the navigation listener.

The navigation service will call the NavigationListener::navigationSound() callback with the updated sound.

Parameters

[in] navigationListener Navigation listener used to identify the navigation session

Public Member Functions

Detailed Description

Member Function Documentation

◆ cancelNavigation()

◆ getBetterRouteTimeDistanceToFork()

◆ getDataSource()

◆ getIntermediateWaypointDropParameters()

◆ getNavigationInstruction()

◆ getNavigationParameters()

◆ getNavigationRoute()

◆ getSimulationMaxSpeedMultiplier()

◆ getSimulationMinSpeedMultiplier()

◆ getTransferStatistics()

◆ isNavigationActive()

◆ isSimulationActive()

◆ isTripActive()

◆ operator=()

◆ setNavigationRoadBlock()

◆ skipNextIntermediateDestination()

◆ startNavigation() [1/2]

◆ startNavigation() [2/2]

◆ startSimulation() [1/2]

◆ startSimulation() [2/2]

◆ updateNavigationSound()