TomTomNavigation
public protocol TomTomNavigation : AnyObject
The TomTomNavigation
protocol defines the functionality of the navigation.
Important
The current implementation of this API isn’t thread-safe and it’s recommended to make API calls always on the same thread.
Important
This is a Public Preview API. It may be changed or removed at any time.
-
Provides access to current registered engines and allows updating them.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var navigationEngineRegistry: NavigationEngineRegistry { get set }
-
The
VehicleProvider
used by theTomTomNavigation
for providing vehicle updates to the navigation.Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var vehicleProvider: VehicleProvider { get }
-
Provides a
CLLocation
for map matching.Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var mapMatchedLocationProvider: LocationProvider { get }
-
Provides a
CLLocation
for raw GPS position.Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var locationProvider: LocationProvider { get set }
-
Controls how the route deviations are handled.
When set to
TomTomSDKNavigationEngines/DeviationReplanningMode/automatic
the navigation replans the route automatically. When set toTomTomSDKNavigationEngines/DeviationReplanningMode/none
the navigation does not replan the route.The default value is
TomTomSDKNavigationEngines/DeviationReplanningMode/automatic
.Declaration
Swift
var deviationReplanningMode: DeviationReplanningMode { get set }
-
The unit system to be used within
TomTomNavigation
.Once set, it is propagated to other components (e.g.
GuidanceEngine
) and used for the generation of guidance announcements.If the
UnitSystemType
instance is dynamic thenunitSystem
is resolved based on the country attribute of the current location:- for “USA” and “PRI” it resolves to
SpecificUnitSystem/imperialFeet
. - for “GBR” it resolves to
SpecificUnitSystem/imperialYards
. - for other countries it resolves to
SpecificUnitSystem/metric
.
The default value is
UnitSystemType.default
.Declaration
Swift
var unitSystem: UnitSystemType { get set }
- for “USA” and “PRI” it resolves to
-
The preferred language to be used within
TomTomNavigation
in guidance instructions and announcement language.The initial value is
Locale.current
. If the initial language is not supported,en-US
will be used instead. Supported languages can be acquired fromGuidanceEngine.availableLanguages
.Setting the preferred language updates the route. You can check the updated route language using
language
. If the specified language is not supported,en-US
will be used instead.To observe language changes, add:
Declaration
Swift
var preferredLanguage: Locale { get set }
-
The current language used within
TomTomNavigation
in guidance instructions and announcement language. The initial value isLocale.current
. To changelanguage
, seepreferredLanguage
.Declaration
Swift
var language: Locale { get }
-
A publishable variable that can be used to receive the same events that the delegate presents
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var eventPublisher: AnyPublisher<NavigationEvent, Never> { get }
-
The current
NavigationState
withinTomTomNavigation
.The initial value is set to
NavigationState.idle
.To change
navigationState
, seestart()
,start(navigationOptions:)
,stop()
,TomTomNavigation/resume(navigationResumeSnapshot:)
andselectActiveRoute(routeId:)
.To observe changes to
navigationState
seeNavigationStateChangeObserver
.Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var navigationState: NavigationState { get }
-
Starts navigation without
Route
anddidChangeNavigationState(navigationState:)
is notified with the state set tofreeDriving
.Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func start() throws
-
Starts navigation with a navigation plan.
The following listeners are notified:
didChangeNavigationState(navigationState:)
is notified with the state set toactiveGuidance
.didAddRoute(route:options:reason:)
with theRoute
,RoutePlanniningOptions
andnavigationStarted
.didChangeActiveRoute(route:)
withRoute
.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func start(navigationOptions: NavigationOptions) throws
Parameters
navigationOptions
NavigationOptions
to be used during the navigation session. -
Updates the route plan during ongoing navigation.
The following listeners are notified:
NavigationRouteUpdateObserver/didUpdateRoute(route:options:reason:)
with the updatedRoute
,RoutePlanniningOptions
andRouteUpdatedReason/manuallyUpdated
if current route does not contain the providedrouteId
, the method does not update the route.didChangeActiveRoute(route:)
with theRoute
if active route has changed.didRemoveRoute(route:reason:)
with all other routes except the activeRoute
andmanual
.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func setActiveRoutePlan(_ routePlan: RoutePlan)
Parameters
routePlan
The
RoutePlan
to be set as active. -
Selects the
Route
with providedrouteID
as active.The navigation switches to navigate along the desired route and the following listeners are notified:
didChangeActiveRoute(route:)
withRoute
selected byrouteID
.didRemoveRoute(route:reason:)
with the previously activeRoute
andmanual
If theRoute
corresponding to the givenrouteId
is not available, changing does not occur.
Declaration
Swift
func selectActiveRoute(routeId: UUID)
Parameters
routeId
UUID
id of route that should be selected. -
Marks a departure from the given waypoint independently from
ArrivalDetectionEngine/hasArrivedAtWaypoint
.The specified
waypoint
is marked as having been departed from andNavigationWaypointArrivalObserver
are notified about this viaNavigationDestinationArrivalObserver/didArriveAtWaypoint(waypoint:on:)
. Notification viaNavigationDestinationArrivalObserver/didArriveAtWaypoint(waypoint:on:)
completes arrival detection for that particularwaypoint
. Navigation switches to arrival detection for the nextwaypoint
, if one is present.Prerequisites for this action:
- A
didArriveAtWaypoint(waypoint:on:)
notification was previously issued for thiswaypoint
. No
didDepartFromWaypoint(waypoint:on:)
notification was previously issued for thiswaypoint
.
Throws
nextWaypointError
if calling requirements are not met.Declaration
Swift
func departFromWaypoint(waypoint: RouteStop) throws
Parameters
waypoint
The waypoint to depart from.
- A
-
Stops the current navigation session if it is running and clears data related to it.
didChangeNavigationState(navigationState:)
is notified with the state set toidle
.Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func stop()
-
Adds a
NavigationStateChangeObserver
toTomTomNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func addNavigationStateChangeObserver(_ observer: NavigationStateChangeObserver)
Parameters
observer
A class that can handle navigation state changes.
-
Removes the
NavigationStateChangeObserver
fromTomTomNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func removeNavigationStateChangeObserver(_ observer: NavigationStateChangeObserver)
Parameters
observer
A class that can handle navigation state changes.
-
Adds a
LocationMapMatchingObserver
toTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func addLocationMapMatchingObserver(_ observer: LocationMapMatchingObserver)
Parameters
observer
A class that can handle navigation map matching events.
-
Removes the
LocationMapMatchingObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func removeLocationMapMatchingObserver(_ observer: LocationMapMatchingObserver)
Parameters
observer
A class that can handle navigation map matching events.
-
Adds a
NavigationProgressObserver
toTomTomNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func addProgressObserver(_ observer: NavigationProgressObserver)
Parameters
observer
A class that can handle navigation start events.
-
Removes the
NavigationProgressObserver
fromTomTomNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func removeProgressObserver(_ observer: NavigationProgressObserver)
Parameters
observer
A class that can handle navigation progress events.
-
Adds a
NavigationRouteAddObserver
toNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func addRouteAddObserver(_ observer: NavigationRouteAddObserver)
Parameters
observer
A class that can handle navigation route added events.
-
Removes the
NavigationRouteAddObserver
fromNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func removeRouteAddObserver(_ observer: NavigationRouteAddObserver)
Parameters
observer
A class that can handle navigation route added events.
-
Adds a
NavigationRouteRemoveObserver
toNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func addRouteRemoveObserver(_ observer: NavigationRouteRemoveObserver)
Parameters
observer
A class that can handle navigation route removed events.
-
Removes the
NavigationRouteRemoveObserver
fromNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func removeRouteRemoveObserver(_ observer: NavigationRouteRemoveObserver)
Parameters
observer
A class that can handle navigation route removed events.
-
Adds a
NavigationRouteUpdateObserver
toTomTomNavigation
.The call is expected on the main queue. The system keeps a weak reference to the observer.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func addRouteUpdateObserver(_ observer: NavigationRouteUpdateObserver)
Parameters
observer
A class that can handle navigation route updated events.
-
Removes the
NavigationRouteUpdateObserver
fromTomTomNavigation
.There is no need to remove the observer. If the observer is not removed, the system cleans up when the next event is posted. The call is expected on the main queue. Do not call this method from the deinitializer of the observer, unless you are certain that the observer will be destroyed on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func removeRouteUpdateObserver(_ observer: NavigationRouteUpdateObserver)
Parameters
observer
A class that can handle navigation route updated events.
-
Adds a
GuidanceUpdateObserver
that notifies of newTomTomSDKNavigationEngines.Guidance
instances.This is notified whenever there is a change in location and the
TomTomSDKNavigationEngines.GuidanceEngine
successfully generates a newTomTomSDKNavigationEngines.Guidance
.Precondition
The call is expected on the main queue.Declaration
Swift
func addGuidanceUpdateObserver(_ observer: GuidanceUpdateObserver)
Parameters
observer
The
GuidanceUpdateObserver
to be added. -
Removes a previously added
GuidanceUpdateObserver
. This method allows you to stop receiving updates about guidance changes.Precondition
The call is expected on the main queue.Declaration
Swift
func removeGuidanceUpdateObserver(_ observer: GuidanceUpdateObserver)
Parameters
observer
The
GuidanceUpdateObserver
to be removed. -
Adds a
LaneGuidanceUpdateObserver
to observe and handle newTomTomSDKNavigationEngines.LaneGuidance
instances.This is notified whenever there is a change in location and the
TomTomSDKNavigationEngines.GuidanceEngine
successfully generates a new lane guidance.Precondition
The call is expected on the main queue.Declaration
Swift
func addLaneGuidanceUpdateObserver(_ observer: LaneGuidanceUpdateObserver)
Parameters
observer
The
LaneGuidanceUpdateObserver
to be added. -
Removes a previously added
LaneGuidanceUpdateObserver
.This method allows you to stop receiving updates about lane guidance changes.
Precondition
The call is expected on the main queue.Declaration
Swift
func removeLaneGuidanceUpdateObserver(_ observer: LaneGuidanceUpdateObserver)
Parameters
observer
The
LaneGuidanceUpdateObserver
to be removed. -
Adds a
NavigationActiveRouteChangeObserver
toNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func addActiveRouteChangeObserver(_ observer: NavigationActiveRouteChangeObserver)
Parameters
observer
A class that can handle navigation active route changed events.
-
Removes the
NavigationActiveRouteChangeObserver
fromNavigation
.The call is expected on the main queue.
Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
func removeActiveRouteChangeObserver(_ observer: NavigationActiveRouteChangeObserver)
Parameters
observer
A class that can handle navigation active route changed events.
-
Adds a
NavigationGuidanceObserver
toNavigation
.The call is expected on the main queue.
Declaration
Swift
@available(*, deprecated, message: "This API is deprecated and will be removed with the next major release.\nPlease use TomTomNavigation.addGuidanceUpdateObserver(_:﹚ and TomTomNavigation.addLaneGuidanceUpdateObserver(_:﹚ instead.") func addGuidanceObserver(_ observer: NavigationGuidanceObserver)
Parameters
observer
A class that can handle navigation guidance events.
-
Removes the
NavigationGuidanceObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
@available(*, deprecated, message: "This API is deprecated and will be removed with the next major release.\nPlease use TomTomNavigation.removeGuidanceUpdateObserver(_:﹚ and TomTomNavigation.removeLaneGuidanceUpdateObserver(_:﹚ instead.") func removeGuidanceObserver(_ observer: NavigationGuidanceObserver)
Parameters
observer
A class that can handle navigation guidance events.
-
Adds a
NavigationLocationContextObserver
toTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func addLocationContextObserver(_ observer: NavigationLocationContextObserver)
Parameters
observer
A class that can handle navigation location context events.
-
Removes the
NavigationLocationContextObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func removeLocationContextObserver(_ observer: NavigationLocationContextObserver)
Parameters
observer
A class that can handle navigation location context events.
-
Adds a
NavigationDestinationArrivalObserver
toTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func addDestinationArrivalObserver(_ observer: NavigationDestinationArrivalObserver)
Parameters
observer
A class that can handle navigation destination arrival events.
-
Removes the
NavigationDestinationArrivalObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func removeDestinationArrivalObserver(_ observer: NavigationDestinationArrivalObserver)
Parameters
observer
A class that can handle navigation destination arrival events.
-
Adds a
NavigationWaypointArrivalObserver
toTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func addWaypointArrivalObserver(_ observer: NavigationWaypointArrivalObserver)
Parameters
observer
A class that can handle navigation waypoint arrival events.
-
Removes the
NavigationWaypointArrivalObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func removeWaypointArrivalObserver(_ observer: NavigationWaypointArrivalObserver)
Parameters
observer
A class that can handle navigation waypoint arrival events.
-
Adds a
NavigationHorizonObserver
toTomTomNavigation
.The call is expected on the main queue.
Throws
HorizonError.observerAlreadyRegistered
if thisNavigationHorizonObserver
object is already added for horizon updates.HorizonError.optionsAlreadyRegistered
if theseHorizonOptions
are already being observed.Declaration
Swift
func addHorizonObserver(_ observer: NavigationHorizonObserver, options: HorizonOptions) throws
Parameters
observer
A class that can handle navigation horizon events. To add a new observer with the same options, the previous one must be removed first. To add different options with the same observer, the previous one must be removed first.
options
The options that define the extent of the paths on the horizon and which map attributes to collect.
-
Removes the
NavigationHorizonObserver
fromTomTomNavigation
.This method should be called on the deinitialization of the observer. The call is expected on the main queue.
Declaration
Swift
func removeHorizonObserver(_ observer: NavigationHorizonObserver) throws
Parameters
observer
A class that can handle navigation trip events.
-
Adds a
TomTomSDKNavigation/NavigationRouteTrackingStateUpdateObserver
toTomTomNavigation
.The call is expected on the main queue. The system keeps a weak reference to the observer.
Declaration
Swift
func addRouteTrackingStateUpdateObserver(_ observer: NavigationRouteTrackingStateUpdateObserver)
Parameters
observer
A class that can handle navigation follow the route events.
-
Removes the
TomTomSDKNavigation/NavigationRouteTrackingStateUpdateObserver
fromTomTomNavigation
.The call is expected on the main queue.
Declaration
Swift
func removeRouteTrackingStateUpdateObserver(_ observer: NavigationRouteTrackingStateUpdateObserver)
Parameters
observer
A class that can handle navigation follow the route events.
-
Adds a
NavigationLanguageChangeObserver
toTomTomNavigation
.The call is expected on the main queue. The system keeps a weak reference to the observer.
Declaration
Swift
func addLanguageChangeObserver(_ observer: NavigationLanguageChangeObserver)
Parameters
observer
A class that can handle navigation language change events.
-
Removes the
NavigationLanguageChangeObserver
fromTomTomNavigation
.There is no need to remove the observer. If the observer is not removed, the system cleans up when the next event is posted. The call is expected on the main queue. Do not call this method from the deinitializer of the observer, unless you are certain that the observer will be destroyed on the main queue.
Declaration
Swift
func removeLanguageChangeObserver(_ observer: NavigationLanguageChangeObserver)
Parameters
observer
A class that can report on changes to the navigation language.
-
The current
BetterProposalAcceptanceMode
.Declaration
Swift
var betterProposalAcceptanceMode: BetterProposalAcceptanceMode { get set }
-
The current
TomTomSDKNavigationEngines/NavigationSnapshot
.The snapshot is
nil
if the navigation is not yet started or has already been stopped.Complexity
The property demonstrates O(n).Important
This is a Public Preview API. It may be changed or removed at any time.Declaration
Swift
var navigationSnapshot: NavigationSnapshot? { get }
Return Value
The current
NavigationSnapshot
if navigation is not stopped.