com.tomtom.navapp

Interface TripManager

public interface TripManager

NavApp TripManager interface, contains interfaces relating to a Trip, for example; planning a trip, canceling a trip, information about trip progress, etc. Currently, only functionality relating to the active trip is supported.

Since:

1

Method Summary

Modifier and Type	Method and Description
void	cancelTrip(Trip trip, Trip.PlanListener planListener) Cancel the currently active Trip.
void	clearAlternativeSpeedLimit(Trip.AlternativeSpeedLimitListener listener) Removes the alternative speed limit The passed in listener is only active until the result of the call has been returned.
void	getActiveTrip(Trip.Listener listener) Get the currently active Trip.
void	getDestination(Trip trip, Routeable.Listener listener) Get the current destination.
void	getWaypointEta(Trip trip, Routeable waypoint, Trip.EtaListener listener) Get the ETA for a waypoint (including the destination) on the specified trip.
void	getWaypoints(Trip trip, Trip.WaypointsListListener listener) Get the list of waypoints on the specified trip.
void	planTrip(Routeable destination, java.util.List<Routeable> waypoints, org.json.JSONObject criteria, Trip.PlanListener planListener) Plan a trip from the current location to a destination with a set of waypoints and a specified criteria.
void	planTrip(Routeable destination, java.util.List<Routeable> waypoints, Trip.PlanListener planListener) Plan a trip from the current location to a destination with a set of waypoints.
void	planTrip(Routeable destination, Trip.PlanListener planListener) Plan a trip from the current location to a destination.
void	planTrip(Track track, org.json.JSONObject criteria, Trip.PlanListener planListener) Plan a trip from the current location to a Track.
void	registerTripListener(Trip.Listener listener) Register a Trip.Listener, to receive information about the state of the active trip.
void	registerTripProgressListener(Trip.ProgressListener progressListener) Register a Trip.ProgressListener to receive updates about ETA and distance remaining, while progressing along the Trip.
void	registerWaypointsArrivalListener(Trip.InfoListener listener) Register a listener for receiving notification about waypoints arrival.
void	registerWaypointsEtaChangeListener(Trip trip, Trip.InfoListener listener) Register a listener for receiving notification about waypoints ETA changes.
void	removeWaypoint(Trip trip, Routeable waypoint, Trip.WaypointRemovedListener listener) Removes the given waypoint from the specified trip.
void	setAlternativeSpeedLimit(int speedLimitInMetersPerHour, java.lang.String imageUri, Trip.SpeedShieldShape shieldShape, Trip.SpeedShieldLuminance shieldLuminance, Trip.AlternativeSpeedLimitListener listener) Sets the alternative speed limit The passed in listener is only active until the result of the call has been returned.
void	unregisterTripListener(Trip.Listener listener) Unregister a previously registered Trip.Listener.
void	unregisterTripProgressListener(Trip.ProgressListener progressListener) Unregister a previously registered Trip.ProgressListener.
void	unregisterWaypointsArrivalListener(Trip.InfoListener listener) Unregister the listener for notification about waypoints arrival.
void	unregisterWaypointsEtaChangeListener(Trip.InfoListener listener) Unregister the listener for notification about waypoints ETA changes.

Method Detail

getActiveTrip

void getActiveTrip(Trip.Listener listener)

Get the currently active Trip. If the callback returns null it means that there is no active trip planned on the device. The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Parameters:

listener - The Trip.Listener to receive information about the active trip.

Throws:

java.lang.IllegalArgumentException - If the listener is null.

Since:

1

registerTripListener

void registerTripListener(Trip.Listener listener)

Register a Trip.Listener, to receive information about the state of the active trip.

Parameters:

listener - The Trip.Listener to receive information about the active trip.

Throws:

java.lang.IllegalArgumentException - If the listener is null.

Since:

1

unregisterTripListener

void unregisterTripListener(Trip.Listener listener)

Unregister a previously registered Trip.Listener.

Parameters:

listener - The Trip.Listener to unregister.

Throws:

java.lang.IllegalArgumentException - if the listener is null or previously not registered.

Since:

1

planTrip

void planTrip(Routeable destination,
              Trip.PlanListener planListener)

Plan a trip from the current location to a destination. In supported devices, this call will switch the focus to the NavApp when the trip-planning is started. The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Parameters:

destination - The Routeable destination to plan to.

planListener - Trip.PlanListener to receive information about the result of the trip planning.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

1

planTrip

void planTrip(Routeable destination,
              java.util.List<Routeable> waypoints,
              org.json.JSONObject criteria,
              Trip.PlanListener planListener)

Plan a trip from the current location to a destination with a set of waypoints and a specified criteria. In supported devices, this call will switch the focus to the NavApp when the trip-planning is started. The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Format of the JSON criteria (all values are stored as String objects, unless stated otherwise)

  {
    waypoints_order : "<The order of waypoints in the planned trip>",
  }
 

Possible values for waypoints order:

• specified — The planned trip will keep the specified order of waypoints.
• shortest — The planned trip will sort the waypoints trying to optimize the path.

If the specified criteria are not valid (e.g. malformed, null or unavailable), the error callback of the listener is called with PlanResult.INVALID_CRITERIA error code.

Parameters:

destination - The Routeable destination to plan to.

waypoints - A List of waypoints to plan the trip along.

criteria - A JSON object specifying the criteria to be used for planning the trip (see above).

planListener - Trip.PlanListener to receive information about the result of the trip planning.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

2

planTrip

void planTrip(Routeable destination,
              java.util.List<Routeable> waypoints,
              Trip.PlanListener planListener)

Plan a trip from the current location to a destination with a set of waypoints. In supported devices, this call will switch the focus to the NavApp when the trip-planning is started. The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Parameters:

destination - The Routeable destination to plan to.

waypoints - A List of waypoints to plan the trip along.

planListener - Trip.PlanListener to receive information about the result of the trip planning.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

2

planTrip

void planTrip(Track track,
              org.json.JSONObject criteria,
              Trip.PlanListener planListener)

Plan a trip from the current location to a Track. In supported devices, this call will switch the focus to the NavApp when the trip-planning is started. The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Format of the JSON criteria (all values are stored as String objects, unless stated otherwise)

  {
    planning_state : "<The state of the planning after calling this API>",
  }
 

Possible values for planning_state:

• preview — The track will be shown in preview mode, and the user will need to press "Drive" for driving there.
• activate_to_start — The track will be shown and a trip to its start point will be planned.
• activate_to_nearest — The track will be shown and a trip to the nearest point along the track will be planned.

If the specified criteria are not valid (e.g. malformed, null or unavailable), the error callback of the listener is called with PlanResult.INVALID_CRITERIA error code.

Parameters:

track - The Track describing the route to be planned.

planListener - Trip.PlanListener to receive information about the result of the trip planning.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

5

cancelTrip

void cancelTrip(Trip trip,
                Trip.PlanListener planListener)

Cancel the currently active Trip. The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Parameters:

trip - The Trip to cancel.

planListener - Trip.PlanListener this returns TRIP_CANCELLED when he trip has been cancelled (or one of the error-codes in case that is not possible).

Since:

1

registerTripProgressListener

void registerTripProgressListener(Trip.ProgressListener progressListener)

Register a Trip.ProgressListener to receive updates about ETA and distance remaining, while progressing along the Trip.

Parameters:

progressListener - The Trip.ProgressListener to received updates.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

1

unregisterTripProgressListener

void unregisterTripProgressListener(Trip.ProgressListener progressListener)

Unregister a previously registered Trip.ProgressListener.

Parameters:

progressListener - The Trip.ProgressListener to unregister.

Throws:

java.lang.IllegalArgumentException - if the listener is null or previously not registered.

Since:

1

getWaypoints

void getWaypoints(Trip trip,
                  Trip.WaypointsListListener listener)

Get the list of waypoints on the specified trip. If no waypoints are present, an empty list is returned.

Parameters:

trip - The Trip.

listener - The Trip.WaypointsListListener to return the result.

Since:

2

removeWaypoint

void removeWaypoint(Trip trip,
                    Routeable waypoint,
                    Trip.WaypointRemovedListener listener)

Removes the given waypoint from the specified trip. Once the request is processed the result is returned via callback listener. In case the given trip differs from the current, active one, error on the listener will be reported. If the waypoint isn't on the trip then error on the listener will be reported too.

Parameters:

trip - The Trip on which the waypoint should be skipped.

waypoint - The Routeable being a waypoint to be removed from the trip.

listener - The Trip.WaypointRemovedListener to return the result.

Since:

9

getWaypointEta

void getWaypointEta(Trip trip,
                    Routeable waypoint,
                    Trip.EtaListener listener)

Get the ETA for a waypoint (including the destination) on the specified trip.

Parameters:

trip - The Trip.

waypoint - The requested waypoint to check the ETA see Routeable.

listener - The Trip.EtaListener to return the result.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

2

getDestination

void getDestination(Trip trip,
                    Routeable.Listener listener)

Get the current destination. If the callback returns null it means that there is no active trip planned on the device. The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Parameters:

trip - The Trip to get the destination for.

listener - The Routeable.Listener to receive the current destination.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

1

setAlternativeSpeedLimit

void setAlternativeSpeedLimit(int speedLimitInMetersPerHour,
                              java.lang.String imageUri,
                              Trip.SpeedShieldShape shieldShape,
                              Trip.SpeedShieldLuminance shieldLuminance,
                              Trip.AlternativeSpeedLimitListener listener)

Sets the alternative speed limit The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Parameters:

speedLimitInMetersPerHour - Speed limit value to be set in MetersPerHour (Max value being 300000 Meters per hour).

imageUri - A string URI that can be resolved to a Drawable icon to be set for alternative speed limit shield. For example: "res:packagename:drawable/sample"

shieldShape - Shape for alternative speed limit shield (see Trip.SpeedShieldShape for options).

shieldLuminance - Luminance value for alternative speed limit shield (see Trip.SpeedShieldLuminance for options).

listener - Trip.AlternativeSpeedLimitListener to receive the result of the operation.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

1

clearAlternativeSpeedLimit

void clearAlternativeSpeedLimit(Trip.AlternativeSpeedLimitListener listener)

Removes the alternative speed limit The passed in listener is only active until the result of the call has been returned. Once a result has been returned the listener won't receive any more callbacks (but can be re-used).

Parameters:

listener - Trip.AlternativeSpeedLimitListener to receive the result of the operation.

Throws:

java.lang.IllegalArgumentException - if the listener is null.

Since:

1

registerWaypointsArrivalListener

void registerWaypointsArrivalListener(Trip.InfoListener listener)

Register a listener for receiving notification about waypoints arrival. The listener will receive a list of RouteableInfo every time a waypoint (or a set of waypoints) are reached.

For every waypoint arrival an 'event' of type 'waypoint_arrival' will be received. Use getAttributeString("event") to retrieve the event.

Parameters:

listener - The Trip.InfoListener receiving the notifications.

Throws:

java.lang.IllegalArgumentException - If the listener is null.

Since:

3

unregisterWaypointsArrivalListener

void unregisterWaypointsArrivalListener(Trip.InfoListener listener)

Unregister the listener for notification about waypoints arrival.

Parameters:

listener - The Trip.InfoListener that needs to be removed.

Throws:

java.lang.IllegalArgumentException - If the listener is null.

Since:

3

registerWaypointsEtaChangeListener

void registerWaypointsEtaChangeListener(Trip trip,
                                        Trip.InfoListener listener)

Register a listener for receiving notification about waypoints ETA changes. The listener is called whenever there is a change in the ETA for at least one waypoint of the trip. All waypoints are returned in the callback, and for each one there is the correspondent ETA.

NOTE: Changes within a threshold of +/-30 seconds are not notified, in order to reduce the data exchange due to small fluctuations of the values.

For every RouteableInfo returned in the callback, use the following attributes to obtain the ETA information:

• getAttributeLong("eta") to retrieve the ETA in UTC (in seconds)
• getAttributeInt("offset") to retrieve the offset in seconds between the current position timezone and this waypoint's time zone

Note: an eta of -1 means that the waypoint has been passed already. Note: an offset of -1 means that the offset is currently not known (e.g. because we do not have a GPS fix yet).

Parameters:

trip - The Trip.

listener - The Trip.InfoListener to return the result.

Throws:

java.lang.IllegalArgumentException - If the listener is null.

Since:

4

unregisterWaypointsEtaChangeListener

void unregisterWaypointsEtaChangeListener(Trip.InfoListener listener)

Unregister the listener for notification about waypoints ETA changes.

Parameters:

listener - The Trip.InfoListener that needs to be removed.

Throws:

java.lang.IllegalArgumentException - If the listener is null.

Since:

4