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.

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.

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.

  1. Browse to the path iOSSDK/SampleApp/NavKitSampleApp/project.

  2. Double-click the NavKitSampleApp.xcodeproj highlighted in the following figure.

Import Navigation Project
Figure 1. Importing the Project

Building and Running the NavKitSampleApp

The following steps describe building and running the NavKitSampleApp.

  1. Open the path to credentials.plist as shown in the following figure.

  2. Replace “YOUR API KEY” with the API key assigned to you by Comtech. The API key must be set before building the project.

SetAPINavigation
Figure 2. Setting API Key
  1. Run the NavKitSampleApp to explore various navigation features. The following figures show the main screen which has various route options.

MainScreen_Navigation
Figure 3. NavKitSampleApp Main Screen
Navigation Session
Figure 4. NavKitSampleApp Main Screen Continuation
  1. 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.

Run 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 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.

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.

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.

  1. Browse to the path iOSSDK/SampleApp/NavKitSampleApp/project.

  2. Double-click the NavKitSampleApp.xcodeproj highlighted in the following figure.

Import Navigation Project
Figure 1. Importing the Project

Building and Running the NavKitSampleApp

The following steps describe building and running the NavKitSampleApp.

  1. Open the path to credentials.plist as shown in the following figure.

  2. Replace “YOUR API KEY” with the API key assigned to you by Comtech. The API key must be set before building the project.

SetAPINavigation
Figure 2. Setting API Key
  1. Run the NavKitSampleApp to explore various navigation features. The following figures show the main screen which has various route options.

MainScreen_Navigation
Figure 3. NavKitSampleApp Main Screen
Navigation Session
Figure 4. NavKitSampleApp Main Screen Continuation
  1. 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.

Run Navigation Session
Figure 5. Running Navigation Session
Note

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