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:

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< AGSRouteTrackerDelegate >	delegate
BOOL	reroutingEnabled
BOOL	skipCoincidentStops
AGSTrackingStatus *	trackingStatus
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

parameters	An AGSReroutingParameters allow customizing background rerouting.
completion	The 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

routeTask	An AGSRouteTask capable of solving routes on the same network used by the original route.
routeParameters	An AGSRouteParameters object that defines parameters for the rerouting AGSRouteTask.
strategy	A rerouting strategy that determines how new routes are created (to the next waypoint by default).
visitFirstStopOnStart	Whether the first stop must be visited when rerouted (NO by default).
completion	The 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

routeResult	An AGSRouteResult generated from route task solve.
routeIndex	The 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

routeResult	An AGSRouteResult generated from route task solve.
routeIndex	The integer value for which route to use in the array of AGSRouteResult::routes. The array is zero-based.
skipCoincidentStops	Determines 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

routeResult	An AGSRouteResult generated from route task solve.
routeIndex	The 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

routeResult	An AGSRouteResult generated from route task solve.
routeIndex	The integer value for which route to use in the array of AGSRouteResult::routes. The array is zero-based.
skipCoincidentStops	Determines 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

completion

The #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