iOS NavKit API User Guide

LNKNavigation Class

LNKNavigation class is is the main class of NavKit and acts as the controller of navigation. It creates and controls the life cycle of a navigation session and other major navigation related operations, such as pause/stop, set active route, play announcement, and so on.

The following table describes the major functions and commonly used methods in the LNKNavigation class.

Table 1. LNKNavigation Class Methods
Method	Description
`+ (LNKNavigation*) getNavigation`	Starts the Navigation session.
`- (void) updatePosition : (const LTKLocation*) location`	Updates the Navigation session with the location. The first position update triggers a route generation.
`- (void) pauseSession`	Pauses the current Navigation session.
`- (void) resumeSession`	Resumes the current Navigation session.
`- (void) stopSession`	Stops the current Navigation session.
`- (void) setActiveRoute : (NSUInteger) index`	Selects/activates the route for the current Navigation session.
`- (void) announce`	Triggers the announcement for the current step with in the current session. It has overloaded parameters for the specific maneuver along with the route.
`- (void) announce : (NSInteger) maneuverIndex`	This method with the addition of (NSInteger) maneuverIndex triggers the announcement for specified maneuver.
`- (void) announce : (NSInteger) maneuverIndex` `route : (LNKRouteInformation*) route`	Triggers the announcement for specified maneuver of specified route.
`- (void) recalculate`	Recalculates the current route session.
`- (void) doDetour`	Calculates a detour route from the current position.
`- (void) cancelDetour`	Cancels the detour request.
`- (void) recalculateWithWayPoint:(NSArray*) wayPoint`	Recalculates the current route session with waypoints.
`- (void) addSessionDelegate : (id<LNKSessionDelegate>) delegate`	Adds session delegate to receive notifications, when the route information is updated. See Navigation Delegates below.
`- (void) addNavigationUpdateDelegate : (id<LNKNavigationUpdateDelegate>) delegate`	Adds navigation update delegate to receive notifications on changes in the position with respect to the entire route as well as the current maneuver. See Navigation Delegates below.
`- void) addAnnouncementDelegate : (id<LNKAnnouncementDelegate>) delegate`	Adds announcement delegate to receive notifications when an announcement needs to be played. See Navigation Delegates below.
`- (void) addTrafficDelegate : (id<LNKTrafficDelegate>) delegate`	Adds traffic delegate to receive notifications when the traffic information is updated. See Navigation Delegates below.

Navigation Delegates

The four sets of Navigation Delegates in the iOS NavKit are described in the following table.

Table 2. Navigation Delegates
Delegate	Description
LNKSessionDelegate	Notifies the subscriber about route states like new route received, route generation progress, end of route and so on.
LNKNavigationUpdateDelegate	Notifies the subscriber about user position updates on the route like maneuver remaining distance, trip remaining distance, current road name, and so on with respect to the entire route, as well as the current maneuver.
LNKAnnouncementDelegate	Notifies the subscriber about announcements which should be played based on the current user position.
LNKTrafficDelegate	Notifies the subscriber about traffic alerts and traffic changes during navigation.

The delegate(s) should be registered to navigation session in order to receive notifications. The following sections give more details of the important delegates.

LNKSessionDelegate

The LNKSessionDelegate is the basic delegate for a Navigation session and provides navigation session related notifications like route updates, errors and so on. The following code snippet registers the LNKSessionDelegate.

[navigation addSessionDelegate:self];

This table describes important methods provided in LNKSessionDelegate.

Table 3. LNKSessionDelegate Methods
Method	Description
`- (void) offRoute`	Informs the client that the locations being received by the Navigation session are not considered on route to destination.
`- (void) onRoute`	Informs the client that the locations being received by the Navigation session are considered on route to destination.
`- (void) routeReceived : (LNKRouteRequestReason) reason routes : (NSArray*) routes`	Provides the list of possible routes for the current Navigation session. More than one route will be passed only if the appropriate multiple routes preference is enabled. The default route has zero index.
`- (void) routeRequested : (LNKRouteRequestReason) reason`	Informs the client that new route is requested with a reason. When requesting navigation, it generates a callback.
`- (void) routeProgress : (NSUInteger) progress`	Provides the route generation progress.
`- (void) routeError : (LNKNavigateRouteError) error`	Indicates that an error occured and that the Navigation session is no longer valid.
`- (void) routeFinished`	Informs the client that the current Navigation session has ended. The client will not receive any route updates.On reaching the destination, a callback is generated.
`- (void) arrivingToDestination : (LNKDestinationStreetSide) streetSide`	Informs the client that the current navigation is arriving to destination.

LNKNavigationUpdateDelegate

LNKNavigationUpdateDelegate provides navigation update related notifications like current road name and the remaining trip distance. It is triggered only after activating a route for navigation. The following code snippet registers the LNKNavigationUpdateDelegate.

[navigation addNavigationUpdateDelegate:self]

This table describes the important methods in LNKNavigationUpdateDelegate.

Table 4. LNKNavigationUpdateDelegate Methods
Method	Description
`- (void) currentRoadName : (NSString)primaryName secondaryName : (NSString)secondaryName`	Provides the current road name updates.
`- (void) maneuverExitNumber : (NSString*)exitNumber`	Provides the current maneuver exit number updates.
`- (void) maneuverImageId : (NSString*)imageId`	Provides maneuver image ID.
`- (void) maneuverPoint : (const LTKCoordinate)point`	Provides turn point coordinates.
`- (void) maneuverRemainingDelay : (NSInteger)delay`	Provides the remaining maneuver delay in seconds.
`- (void) maneuverRemainingDistance : (double)distance`	Provides the remaining distance to next maneuver in meters.
`- (void) maneuverRemainingTime : (NSInteger)time`	Provides the remaining maneuver time in seconds.
`- (void) laneInformation : (const LNKLaneInformation*)laneInfo`	Receives lane guidance enabled/disabled notifications.
`- (void) maneuverType : (NSString*)type`	Provides the current maneuver type updates.
`- (void) nextRoadName : (NSString)primaryName secondaryName : (NSString)secondaryName`	Provides the next road name updates.
`- (void) positionUpdated : (const` `LTKCoordinate)coordinates` `speed : (double)speed` `heading : (double)heading`	Notifies that the position on the route has been changed.
`- (void) stackTurnImageTTF : (NSString*)stackImageTTF`	Provides stack turn image text in TTF format.
`- (void) tripRemainingDelay : (NSInteger)delay`	Provides the remaining trip delay updates. Using this method, the current remaining delay of navigation can be known.
`- (void) tripRemainingDistance : (double)distance`	Provides the remaining trip distance updates. Using this method, the current remaining distance of navigation can be obtained.
`- (void) tripRemainTime : (NSInteger)time`	Provides the remaining trip time updates. Using this method, the current remaining navigation time can be obtained.
`- (void) updateManeuverList : (const LNKManeuverList*)maneuvers`	Notifies when maneuver list gets updated. Using this method, the remaining maneuver list can be obtained.
`- (void) roadSign : (const LNKRoadSign*)signInfo`	Receives road sign enabled/disabled notifications.
`- (void) speedLimit : (const LNKSpeedLimitInformation*)` `speedLimitInfo`	Receives speed limit enabled/disabled notifications.
`- (void) tripTrafficColor : (char)color`	Receives traffic color.

LNKAnnouncementDelegate

This delegate provides the navigation announcement notifications. The following code snippet registers the LNKAnnouncementDelegate.

[navigation addAnnouncementDelegate:self];

The following is the commonly used method in LNKAnnouncementDelegate.

(void) announce : (LNKAnnouncement*) announcement - Informs the client that an announcement needs to be played and provides the announcement related information output stream to get audio data to be played as audio text for TTS support.

LNKTrafficDelegate

LNKTrafficDelegate provides the notifications related to traffic updates like upcoming traffic events and congestions.

This table describes the important methods in LNKTrafficDelegate.

Table 5. LNKTrafficDelegate Methods
Method	Description
`- (void) trafficChanged : (LNKTrafficInformation*) trafficInformation`	This method is called when traffic information is updated.
`- (void) trafficAlerted : (LNKTrafficEvent*) trafficEvent`	This method is called when a traffic event is detected within a specified distance.
`- (void) disableTrafficAlerted`	Disables the traffic alert.

LNKRouteInformation Class

The LNKRouteInformation class provides details of the received route after route calculation. This is received through routeReceived method in LNKSessionDelegate, as shown in the following code snippet.

- (void) routeReceived : (LNKRouteRequestReason) reason
routes : (NSArray*) routes
{
// List of routes as RouteInformation array
LNKRouteInformation* route = routes[0];
}

This table describes important properties supported in LNKRouteInformation class.

Table 6. LNKRouteInformation Properties
Property	Description
`@property (nonatomic, readonly) NSString* routeID`	Passes the route ID as a byte array.
`@property (nonatomic, readonly) double distance`	Provides the total route distance in meters.
`@property (nonatomic, readonly) NSUInteger time`	Provides the total route time in seconds.
`@property (nonatomic, readonly) LTKPlace* origin`	Gets route origin place.
`@property (nonatomic, readonly) LTKPlace* destination`	Gets route destination place.
`@property (nonatomic, readonly) NSArray* routeTrafficSegment`	Gets the traffic segment. If there is no traffic, the property remains empty.
`@property (nonatomic, readonly) NSInteger trafficEventCount`	Gets the count of traffic events in the route.
`@property (nonatomic, readonly) char trafficColor`	Gets the traffic color of the route.

This table describes the important methods in LNKRouteInformation class.

Table 7. LNKRouteInformation Methods
Method	Description
`- (LNKTrafficEvent*) getTrafficEvent : (NSUInteger) index`	Returns the traffic event const pointer with index.
`- (LNKManeuverList*) getUpcomingManeuverList: (double) tripRemainingDistance`	Returns the collapsing maneuver list for display.
`- (LNKRouteProperty) getProperty : (NSUInteger) index`	Returns the route property with index.

LNKManeuverList Class

The LNKManeuverList class returns a list of navigation maneuvers. It is received through getUpcomingManeuverList method in LNKRouteInformation.

Using getManeuver method in LNKRouteInformation, individual maneuvers in the list are retrieved as shown in the following code snippet.

/*! Represents a list of navigation maneuvers.*/

@interface LNKManeuverList : NSObject

/*! Returns the number of maneuvers available in the route.
 */
- (LNKManeuver*) getManeuver : (NSUInteger) index;

The following property returns the number of maneuvers available in the route.

@property (nonatomic, readonly) NSUInteger maneuverNumber.

LNKManeuver Class

The LNKManeuver class contains the information of an individual navigation maneuver.

This table describes the commonly used properties supported in LMKManeuver class.

Table 8. LNKManeuver Properties
Property	Description
`@property (nonatomic, readonly) NSInteger maneuverID`	Gets unique ID identifying the maneuver.
`@property (nonatomic, readonly) double time`	Returns the maneuver actual time.
`@property (nonatomic, readonly) NSString* primaryStreet`	Returns primary street.
`@property (nonatomic, readonly) LTKCoordinate point`	Gets point coordinates.
`@property (nonatomic, readonly) BOOL isDestination`	Gets information on whether this maneuver is destination or not.
`@param isMetric`	Indicates that metric system is used and gets the formatted maneuver text.

This table describes commonly used methods supported in LMKManeuver class.

Table 9. LNKManeuver Methods
Method	Description
`- (LTKFormattedTextBlock*) getManeuverText : (BOOL) isMetric`	Returns formatted maneuver description.
`- (NSString*) getDescription : (BOOL) isMetric`	Indicates whether the maneuver description is metric or non-metric.
`- (const LTKCoordinate) getPolylinePoint : (NSUInteger) index`	Returns one point of polyline with index.
`- (NSUInteger) getPolylineCount`	Returns the count of polyline point.

Supported Maneuvers

The following table describes all the supported maneuvers in iOS NavKit SDK.

Table 10. Supported Maneuvers
Command	Description	Usage	LG Font	NG Font	Example
DT.L , DT.R	Destination	Destination	Y	N	Your destination is on the left/right
ER.L , ER.R	Take ramp	Highway	N	N	Take ramp on the left
EX.L , EX.R	Exit highway	Highway	Y	N	Take exit 13A on the left
KH.L , KH.R	Keep (highway version)	Highway	Y	N	In 1 ½ miles take I-405
KS.L , KS.R	Keep (normal road version)	Normal	Y	Y	Get ready to keep to the right at the fork and take Main street
MR.L , MR.R	Merge	Highway	Y	N	Merge {highway} on the left
SH.L , SH.R	Stay (highway version)	Highway	Y	Y	In 2 ½ miles continue on I-5
BE.L , BE.R	Cross bridge	Normal	Y	N	—
EC.L , EC.R	Enter country	Normal	Y	N	In 5 miles you will enter Canada
EN.L , EN.R	Enter highway	Normal	Y	Y	Get ready to take the ramp straight ahead to I-5
FE.	Enter ferry	Normal	Y	N	Get ready to take the Avalon ferry
FX.	Exit ferry	Normal	N	N	Exit the ferry
KP.L , KP.R	Keep (current version which will be deprecated)	Normal	Y	Y	Get ready to keep right onto Main street
NC.	Name change	Normal	Y	N	Not used in announcements
NR.L , NR.R	Enter private road	Normal	Y	Y	Enter private on the left
OR.	Origin (startup case)	Normal	Y	N	Not used in announcements
PE.	Continue by foot	Normal	Y	N	Get ready to find parking then continue by foot to Main street
RE.	Enter roundabout	Normal	Y	N	Get ready to take the 4th exit at the roundabout onto Main street
RT.	Continue straight through roundabout	Normal	Y	N	In 1 mile continue straight through the roundabout onto Main street
RX.N	Exit traffic circle, where N represents exit number	Normal	Y	N	Not used in announcements
ST.L , ST.R	Stay (normal version)	Normal	Y	Y	In 1 ¼ miles stay on Main street
TE.L , TE.R	Enter tunnel	Normal	N	N	—
TR.L , TR.R , TR.SL , TR.SR , TR.HL , TR.HR	Turn, slight turn, hard turn	Normal	Y	Y	Now turn right
UT.	U-turn	Normal	Y	N	Make the next legal U-turn
SC.S	Speed camera	Other	N	N	—
TC.S	Traffic congestion	Other	N	N	—
TL.S	Traffic incident	Other	N	N	—
EE.L , EE.R	Take escalator	Pedestrian	Y	N	Take escalator on the left
ES.L , ES.R	Take stairs	Pedestrian	Y	N	Take stairs on the left

LNKAnnouncement Class

LNKAnnouncement class provides audio data to be played. It is comprised of both audio files and audio text to be fed to the TTS engine.

This table describes the important properties supported in LNKAnnouncement class.

Table 11. LNKAnnouncement Properties
Property	Description
`@property (nonatomic, readonly) NSString* audioText`	Provides the audio text that can be used for playing the announcement using TTS engine.
`@property (nonatomic, readonly) LTKBinaryBuffer* audioData`	Provides the output stream for the announcement audio data to be played. Currently it is Advanced Audio Coding (aac) voice data.
`@property (nonatomic, readonly) NSString* audioMimeType`	Provides the mime type for the announcement being provided.

The following list has the important methods in LNKAnnouncement class.

- (void) onAnnouncementStart - This method is called to let the subscriber of LNKAnnouncementDelegate know that the announcement has been started.
- (void) onAnnouncementComplete - This method is called to let the subscriber of LNKAnnouncementDelegate know that this announcement has been played. It is also called before the app destroys the Navigation session.

Setting Active Route

Multiple routes are returned along with the primary route if alternative route has been enabled by setting multipleRoutesEnabled = TRUE, in the navigation Preference class, through the routeReceived method. After receiving these routes, you can activate a single route from the available routes.

The following code snippet activates the first route as the current navigation route from the available routes.

[lnkNavigation setActiveRoute:0]

Off-Route Processing

A Navigation session is considered “off route” when the location being received is not considered to be “on route” to the destination. In this situation, the offRoute delegate is sent to the client and NavKit starts route recalculation automatically. The method routeReceived is triggered once a new route is received.

/*! Informs the client that the locations being received by the navigation session are not considered on route to destination.
 */

- (void) offRoute
{
}

Error Codes

NavKit will display error codes if there is an occurrence of an error during navigation session initiation or progress.

In few scenarios where the routeReceived returns successful navigation but the route returned is null, the route errors can be retrieved from the routeError method as shown in the following code snippet.

/*! Indicates that an error happened and this navigation session is no longer valid.

 Need to recreate a new one to continue the navigation session.
 */
- (void) routeError : (LNKNavigateRouteError) error;

This table describes the navigation route errors.

Table 12. Navigate Route Errors
Route Error	Code	Description
`LRE_None`	3000	No error/No route.
`LRE_TimedOut`	3001	Route timed out error.
`LRE_BadDestination`	3002	Routing destination is not near a routable road.
`LRE_BadOrigin`	3003	Origin not near a routable road.
`LRE_CannotRoute`	3004	No route can be found between the origin and the destination.
`LRE_EmptyRoute`	3005	Empty route code.
`LRE_NetError`	3006	Network error.
`LRE_UnknownError`	3007	Unknown error.
`LRE_NoMatch`	3008	Route does not match.
`LRE_ServerError`	3009	Server error.
`LRE_NoDetour`	3010	No route detour.
`LRE_PedRouteTooLong`	3011	Pedestrian route too long error.
`LRE_OriginCountry` `Unsupported`	3013	Origin not in supported countries.
`LRE_DestinationCountry` `Unsupported`	3014	Destination not in supported countries.
`LRE_Unauthorized`	4299	Unauthorized.
`LRE_BicycleRoute` `TooLong`	23500	Bicycle route too long.
`LRE_RouteTooLong`	23501	Route too long.
`LRE_GPSTimeout`	23502	GPS time-out error.
`LRE_Cancelled`	23503	Route cancelled.
`LRE_Internal`	23504	Internal error.

NavKitSampleApp Demonstration

Comtech provides an example application NavKitSampleApp that demonstrates various features of the iOS NavKit SDK. The following sections describe how to build and run the NavKitSampleApp.

Importing the Project

The following steps are performed to import the NavKitSampleApp project.

Browse to the path iOSSDK/SampleApp/NavKitSampleApp/project.
Double-click the NavKitSampleApp.xcodeproj highlighted in the following figure.

Figure 1. Importing the Project

Building and Running the NavKitSampleApp

The following steps describe building and running the NavKitSampleApp.

Open the path to credentials.plist as shown in the following figure.
Replace “YOUR API KEY” with the API key assigned to you by Comtech. The API key must be set before building the project.

Figure 2. Setting API Key

Run the NavKitSampleApp to explore various navigation features. The following figures show the main screen which has various route options.

Figure 3. NavKitSampleApp Main Screen

Figure 4. NavKitSampleApp Main Screen Continuation

A Navigation session gets started with all the selected options on tapping Navigation in the main screen.

The following figure shows a running navigation session.

Figure 5. Running Navigation Session

Note	To know more about all the interfaces and methods, see the NavKit iOS API Reference Document.

iOS SDK