ArcGIS Runtime SDK for iOS: AGSRouteTracker Class Reference
ArcGIS Runtime SDK for iOS  100.12
AGSRouteTracker Class Reference

Description

Uses a location to provide status and progress updates as a route is traversed (by a moving vehicle, for example).

AGSRouteTracker can give the time or distance to the next maneuver, notify if the location is off-route, and regenerate a new route if necessary. Basic workflow:

  1. Create a new AGSRouteTracker instance.
  2. Enable rerouting with enableReroutingWithParameters:completion: (AGSRouteTracker) (if supported by the underlying route service).
  3. Use trackLocation:completion: (AGSRouteTracker) to track the location of the device.
  4. Implement the delegate method routeTracker:didUpdateTrackingStatus: (AGSRouteTrackerDelegate-p) to get the AGSTrackingStatus as the location changes.
  5. Implement the delegate method routeTracker:didGenerateNewVoiceGuidance: (AGSRouteTrackerDelegate-p) to get the AGSVoiceGuidance whenever new instructions are available.
  6. If there are multiple stops, call switchToNextDestinationWithCompletion: (AGSRouteTracker) each time AGSDestinationStatusReached status is returned. Before calling switchToNextDestinationWithCompletion: (AGSRouteTracker) make sure that AGSTrackingStatus::remainingDestinationCount > 1, a value of 1 means the last destination is being approached.
    Since
    100.6
Inheritance diagram for AGSRouteTracker:
AGSObject

Instance Methods

(void) - cancelRerouting
 
(void) - disableRerouting
 
(id< AGSCancelable >) - enableReroutingWithParameters:completion:
 
(id< AGSCancelable >) - enableReroutingWithRouteTask:routeParameters:strategy:visitFirstStopOnStart:completion:
 
(nullable AGSVoiceGuidance *) - generateVoiceGuidance
 
(nullable instancetype) - initWithRouteResult:routeIndex:
 
(nullable instancetype) - initWithRouteResult:routeIndex:skipCoincidentStops:
 
(id< AGSCancelable >) - switchToNextDestinationWithCompletion:
 
(id< AGSCancelable >) - trackLocation:completion:
 

Class Methods

(nullable instancetype) + routeTrackerWithRouteResult:routeIndex:
 
(nullable instancetype) + routeTrackerWithRouteResult:routeIndex:skipCoincidentStops:
 

Properties

id< AGSRouteTrackerDelegatedelegate
 
BOOL reroutingEnabled
 
BOOL skipCoincidentStops
 
AGSTrackingStatustrackingStatus
 
AGSUnitSystem voiceGuidanceUnitSystem
 

Method Documentation

◆ cancelRerouting

- (void) cancelRerouting

Cancels a running reroute operation. If rerouting is in progress, this method will interrupt the background route task operation.

Since
100.6

◆ disableRerouting

- (void) disableRerouting

Disables automatic rerouting. When disabled, the tracker will not automatically recalculate a route when the tracking status is off-route.

See also
- enableReroutingWithParameters:completion:
Since
100.6

◆ enableReroutingWithParameters:completion:

- (id<AGSCancelable>) enableReroutingWithParameters: (AGSReroutingParameters *)  parameters
completion: (void(^)(NSError *__nullable error))  completion 

Enables automatic rerouting when the tracker detects an off-route status.

Re-routing only occurs when the current location is off-route, but on or near the transportation network edges. For example, if an off-route state is detected but the tracked location is in a parking lot, away from any transportation network edges, re-routing will not occur, and will occur only once a subsequent tracked location is on or near the transportation network edges.

Parameters
parametersAn AGSReroutingParameters allow customizing background rerouting.
completionThe error parameter is populated on failure.
Returns
An operation which can be canceled.
Since
100.11

◆ enableReroutingWithRouteTask:routeParameters:strategy:visitFirstStopOnStart:completion:

- (id<AGSCancelable>) enableReroutingWithRouteTask: (AGSRouteTask *)  routeTask
routeParameters: (AGSRouteParameters *)  routeParameters
strategy: (AGSReroutingStrategy strategy
visitFirstStopOnStart: (BOOL)  visitFirstStopOnStart
completion: (void(^)(NSError *__nullable error))  completion 

Enables automatic rerouting when the tracker detects an off-route status.

Rerouting is initiated automatically when the tracking status is off-route. In order to be considered off-route, the location must be on the transportation network as well as off the current route. If a tracked location is in a parking lot, for example, it is not considered off-route and rerouting will not occur. If the next location is on the network but not on the route, automatic rerouting will begin.

Parameters
routeTaskAn AGSRouteTask capable of solving routes on the same network used by the original route.
routeParametersAn AGSRouteParameters object that defines parameters for the rerouting AGSRouteTask.
strategyA rerouting strategy that determines how new routes are created (to the next waypoint by default).
visitFirstStopOnStartWhether the first stop must be visited when rerouted (NO by default).
completionThe error parameter is populated on failure.
Returns
An operation which can be canceled.
See also
AGSRouteTask, AGSRouteParameters, AGSReroutingStrategy
Since
100.6
Deprecated:
100.11.0. Use enableReroutingWithParameters:completion: instead.

Provided by category AGSRouteTracker(AGSDeprecated).

◆ generateVoiceGuidance

- (nullable AGSVoiceGuidance *) generateVoiceGuidance

Gets the current AGSVoiceGuidance object. The most recent voice guidance based on the last AGSLocation used by trackLocation:completion:. It can be used to repeat last/latest voice guidance.

Returns
Voice guidance.
See also
AGSTrackingStatus
Since
100.6

◆ initWithRouteResult:routeIndex:

- (nullable instancetype) initWithRouteResult: (AGSRouteResult *)  routeResult
routeIndex: (NSInteger)  routeIndex 

Creates a Route Tracker using a specific route from a route result. Will return nil if the AGSRoute is not found or if it lacks AGSRoute::stops and AGSRoute::directionManeuvers. This initializer will set the property AGSRouteTracker::skipCoincidentStops to YES. To set this property explicitly, use initWithRouteResult:routeIndex:skipCoincidentStops: instead.

Parameters
routeResultAn AGSRouteResult generated from route task solve.
routeIndexThe integer value for which route to use in the array of AGSRouteResult::routes. The array is zero-based.
See also
AGSRouteResult
Since
100.6
Deprecated:
100.9.0. Use initWithRouteResult:routeIndex:skipCoincidentStops: instead.

Provided by category AGSRouteTracker(AGSDeprecated).

◆ initWithRouteResult:routeIndex:skipCoincidentStops:

- (nullable instancetype) initWithRouteResult: (AGSRouteResult *)  routeResult
routeIndex: (NSInteger)  routeIndex
skipCoincidentStops: (BOOL)  skipCoincidentStops 

Creates an AGSRouteTracker object using a specific route from a route result with an option to specify treating coincident stops as a single destination. Will return nil if the AGSRoute is not found or if it lacks AGSRoute::stops and AGSRoute::directionManeuvers.

Parameters
routeResultAn AGSRouteResult generated from route task solve.
routeIndexThe integer value for which route to use in the array of AGSRouteResult::routes. The array is zero-based.
skipCoincidentStopsDetermines if coincident stops (multiple stops in a row at the same location) should be treated as a single destination.
See also
AGSRouteResult
Since
100.9

◆ routeTrackerWithRouteResult:routeIndex:

+ (nullable instancetype) routeTrackerWithRouteResult: (AGSRouteResult *)  routeResult
routeIndex: (NSInteger)  routeIndex 

Creates a Route Tracker using a specific route from a route result. Will return nil if the AGSRoute is not found or if it lacks AGSRoute::stops and AGSRoute::directionManeuvers. This initializer will set the property AGSRouteTracker::skipCoincidentStops to YES. To set this property explicitly, use initWithRouteResult:routeIndex:skipCoincidentStops: instead.

Parameters
routeResultAn AGSRouteResult generated from route task solve.
routeIndexThe integer value for which route to use in the array of AGSRouteResult::routes. The array is zero-based.
See also
AGSRouteResult
Since
100.6
Deprecated:
100.9.0. Use routeTrackerWithRouteResult:routeIndex:skipCoincidentStops: instead.

Provided by category AGSRouteTracker(AGSDeprecated).

◆ routeTrackerWithRouteResult:routeIndex:skipCoincidentStops:

+ (nullable instancetype) routeTrackerWithRouteResult: (AGSRouteResult *)  routeResult
routeIndex: (NSInteger)  routeIndex
skipCoincidentStops: (BOOL)  skipCoincidentStops 

Creates a route tracker using a specific route from a route result with an option to specify treating coincident stops as a single destination. Will return nil if the AGSRoute is not found or if it lacks AGSRoute::stops and AGSRoute::directionManeuvers.

Parameters
routeResultAn AGSRouteResult generated from route task solve.
routeIndexThe integer value for which route to use in the array of AGSRouteResult::routes. The array is zero-based.
skipCoincidentStopsDetermines if coincident stops (multiple stops in a row at the same location) should be treated as a single destination.
Returns
A new route tracker.
See also
AGSRouteResult
Since
100.9

◆ switchToNextDestinationWithCompletion:

- (id<AGSCancelable>) switchToNextDestinationWithCompletion: (nullable void(^)(NSError *__nullable error))  completion

Starts tracking progress to the next destination in the AGSRoute. Use switchToNextDestinationWithCompletion: when the tracker reports an AGSDestinationStatusReached status. Before calling switchToNextDestinationWithCompletion: make sure that AGSTrackingStatus::remainingDestinationCount is greater than 1 (a value of 1 means navigation is proceeding to last destination). This method can also be called after AGSDestinationStatusApproaching is raised in cases where the location cannot get near enough to the destination point for AGSDestinationStatusReached to be raised (such as the center of a park or shopping center, for example). The delegate is called when the AGSTrackingStatus is updated accordingly. trackLocation:completion: needs to be called at least once before calling this method otherwise an error will occur. trackLocation:completion: is needed for getting AGSTrackingStatus and for handling visitFirstStopOnStart.

Parameters
completionThe #error parameter is populated on failure.
Returns
An operation which can be canceled.
Since
100.6

Property Documentation

◆ delegate

- (id<AGSRouteTrackerDelegate>) delegate
readwritenonatomicweak

The delegate that receives callbacks for the AGSRouteTracker.

See also
AGSRouteTrackerDelegate
Since
100.6

◆ reroutingEnabled

- (BOOL) reroutingEnabled
readnonatomicassign

Reports if routes are automatically regenerated when tracking status is off-route. YES if rerouting is enabled, otherwise NO.

See also
- enableReroutingWithParameters:completion:, - disableRerouting
Since
100.6

◆ skipCoincidentStops

- (BOOL) skipCoincidentStops
readnonatomicassign

Indicates whether multiple stops in a row at the same location should be treated as one stop.

When YES, if there are multiple stops, in a row, at the same network location the new voice guidance event will fire a single time and calling switchToNextDestinationWithCompletion: will skip over the other coincident stops, setting the state to the next relevant direction maneuver. If the value is NO, each stop will be treated as a unique destination. The default value for this property is YES. If your route does not have coincident stops the value of this property will have no effect.

Since
100.9

◆ trackingStatus

- (AGSTrackingStatus*) trackingStatus
readnonatomicstrong

Status for the current location on the route.

See also
AGSTrackingStatus
Since
100.6

◆ voiceGuidanceUnitSystem

- (AGSUnitSystem) voiceGuidanceUnitSystem
readwritenonatomicassign

The unit system used in voice guidance commands. Default value is AGSUnitSystemMetric. Supported values are AGSUnitSystemMetric and AGSUnitSystemImperial.

Since
100.6