Skip to content

Hooks and Callbacks

Listeners Explained

A callback is a method that is called at a particular time in the code, often for logging purposes. An outside application can create listeners that detect when these methods are called, and act accordingly by defining the methods. A hook is the same as a callback, but also demands that a value be returned from the outside application when detected by the listener. This allows communication between CoPilot and the software that is integrating it.

How To Use: JAVA

  • Create a class that extends one of the CPIK listeners detailed in the next section.
class MyCopilotListener extends CoPilotListener {
}
  • For each hook or callback that you want to use, define the method exactly as shown in the next section, and insert the desired behaviour into the body. For hooks specifically, be sure to provide a return value.
class MyCopilotListener extends CoPilotListener {
  @Override
  public boolean shouldUseCustomContactList() {
    // This is a hook method. Return true if you want the Custom Contact List.
    // Your code here

    return true;
  }
  @Override
  public void onCPStartup() {
    // This is a callback method
    // Write your code here
  }
  @Override
  public void onCPShutdown() {
     // This is a callback method
     // Write your code here
  }
  // and so on
}
  • Lastly, call the registerListener() method on the CPIK listener class, and pass in a new instance of your listener as a parameter.
MyCopilotListener mListener = new MyCopilotListener();
CoPilotListener.registerListener(mListener);
  • At last after using callback. we can unregister it. To unregister the listener we have to pass the instance which was used to register it.
CoPilotListener.unregisterListener(mListener);

How To Use: Obj-C

Create an interface that inherits from our CoPilotDelegate

@interface AppDelegate : UIResponder <UIApplicationDelegate, CoPilotDelegate>

In copilot_delegate.h we list all of the possible callbacks that CoPilot will fire through the delegate. In order to receive them you simply have to override the function inside of the created interface using the exact same signature.

CopilotListener

Callbacks related to CoPilot Version

onCPStartup
Method Java: public void onCPStartup ()
Method Obj-C: -(void) onCPStartup
Type: Callback
Description: Called when CoPilot has finished initializing.
onCPShutdown()
Method Java: public void onCPShutdown ()
Method Obj-C: -(void) onCPShutdown
Type: Callback
Description: Called when CoPilot has finished shutting down.
onFavoriteAdded
Method Java: public void onFavoriteAdded(Favorite favoriteAdded)
Method Obj-C: -(void) onFavoriteAdded:(Favorite*) favorite
Type: Callback
Description: Called when a Favorite is added to CoPilot.
onFavoriteEdited
Method Java: public void onFavoriteEdited(Favorite favoriteBefore, Favorite favoriteAfter)
Method Obj-C: -(void) onFavoriteEdited:(Favorite) favoriteBefore withFavoriteAfter:(Favorite) favoriteAfter
Type: Callback
Description: Called when a Favorite is edited in CoPilot.
onFavoriteDeleted
Method Java: public void onFavoriteDeleted(List<​Favorite> favoriteList)
Method Obj-C: -(void) onFavoriteDeleted:(NSArray*) favorites
Type: Callback
Description: Called when a Favorite is deleted from CoPilot.
onMapPOIClicked Available in CoPilot 10.9.0.958 and Higher
Method Java: onMapPOIClicked(List results)
Method Obj-C: -(void) onMapPOIClicked:(NSArray*) results;
Type: Callback
Description: The onMapPOIClicked callback returns a list of POISearchResult that represents the points of interest (POIs) at the clicked location. It triggers when the customer registers for this with the CoPilotListener. If this returns multiple results, it is mirroring the clustering of POIs on the map and is what would have shown up in CoPilot in a tooltip.

Sample Code

@Override
public void onMapPOIClicked(List<POISearchResult> results) {
   super.onMapPOIClicked(results);
   if(mCopilotListenerMsgTable.get(COPILOT_onMapPOIClicked)) {
       if (results.size() == 1)
           MainActivity.makeToast("MapPOIClicked: " + results.get(0).getName());
       else
           MainActivity.makeToast("MapPOIClicked: Multiple POI selected (" + results.size() + ")");
   }
}
-(void) onMapPOIClicked:(NSArray*) results
{
      for (id result in results)
      {
             NSString* clickedPOIName = result.poiName;
      }
}
onMapSelectionCleared Available in CoPilot 10.9.0.958 and Higher
Method Java: onMapSelectionCleared()
Method Obj-C: -(void) onMapSelectionCleared
Type: Callback
Description: The onMapSelectionCleared callback triggers when the user has clicked on the map in one of two situations:
1. The user had previously clicked on the map to select a POI, or Road, or Stop and the user clicks on the map OFF of that, which would clear the selection.
2. The user has clicked on the map in a location where there is no selection (there is nothing under the map click).

Sample Code

@Override
public void onMapSelectionCleared() {
   super.onMapSelectionCleared();
   if(mCopilotListenerMsgTable.get(COPILOT_onMapSelectionCleared)) {
       if (results.size() == 1)
           MainActivity.makeToast("MapSelectionCleared);
   }
}
-(void) onMapPOIClicked:(NSArray*) results
{
      for (id result in results)
      {
             NSString* clickedPOIName = result.poiName;
      }
}
onMapStopClicked
Method Java: public void onMapStopClicked(StopClickedInfo clickInfo)
Method Obj-C: -(void) onMapStopClicked:(CoPilotStopClickedInfo*) clickInfo
Type: Callback
Description: Called when a user clicks on destination and waypoint flags on the map.
mapRegionUpgradeKeyHook
Method: public License mapRegionUpgradeKeyHook()
Platforms: Linux
Type: Hook
Description: User provides an upgrade key to activate a region. This is called on first start when a region upgrade key has not yet been applied.
selectCoPilotLanguage
Method: public Locale selectCopilotLanguage(List<​Locale> availableLocales)
Platforms: Linux
Type: Hook
Description: User selects a language. Called at CoPilot start when a language is not selected. The parameter provides a list of available languages.
shouldUseCustomContactList
Method: public boolean shouldUseCustomContactList()
Platforms: Linux
Type: Hook
Description: User tells CoPilot whether or not to use a custom contact list. If the user responds to this hook with a true value, CoPilot’s contact list will be defined by a later call to the CopilotListener. customContactListHook() hook.
customContactListHook
Method: public List<​Contact> customContactListHook()
Platforms: Linux
Type: Hook
Description: User provides CoPilot with the desired list of custom contacts. This is the Contact list that will show in the CoPilot “Contacts” menu.
shouldUseCPIKOverSpeedControl
Method: public boolean shouldUseCPIKOverSpeedControl()
Platforms: Linux
Type: Hook
Description: User tells CoPilot if it should allow manual control of speed warnings using CPIK. If the user responds with a false value, or does not implement this hook, CoPilot will control when to show the over speed limit indicator. If the user responds with true, they will need to manually control when the over speed indicator is shown. At each position update, the user will receive a showOverSpeedWarning() hook. The user must respond with true/false for whether or not to show the over speed indicator.
showOverSpeedWarning
Method: public boolean showOverSpeedWarning(int currentSpeed, int speedLimit)
Platforms: Linux
Type: Hook
Description: User tells CoPilot whether or not to show the over speed limit warning. The parameters provide the user with the current speed and current speed limit.
selectMapRegion
Method: public MapRegion selectMapRegion()
Platforms: Linux
Type: Hook
Description: User specifies which map region CoPilot should use.
onKeyDown
Method Java: public void onKeyDown (int keyCode, KeyEvent event, boolean bHandledByCopilot)
Platforms: Android only
Type: Callback
Description: Called when a key down event is received by CoPilot. The Boolean parameter bHandledByCopilot tells whether or not the event was handled by CoPilot. For additional documentation on this callback, see https://developer.android.com/reference/android/view/KeyEvent.Callback
onKeyLongPress
Method Java: public void onKeyLongPress (int keyCode, KeyEvent event, boolean bHandledByCopilot)
Platforms: Android only
Type: Callback
Description: Called when a key long press event is received by CoPilot. The Boolean parameter bHandledByCopilot tells whether or not the event was handled by CoPilot. For additional documentation on this callback, see https://developer.android.com/reference/android/view/KeyEvent.Callback
onKeyMultiple
Method Java: public void onKeyMultiple (int keyCode, int count, KeyEvent event, boolean bHandledByCopilot)
Platforms: Android only
Type: Callback
Description: Called when a multiple key event is received by CoPilot. The Boolean parameter bHandledByCopilot tells whether or not the event was handled by CoPilot. For additional documentation on this callback, see https://developer.android.com/reference/android/view/KeyEvent.Callback
onKeyUp
Method Java: public void onKeyUp (int keyCode, KeyEvent event, boolean bHandledByCopilot)
Platforms: Android only
Type: Callback
Description: Called when a key up event is received by CoPilot. The Boolean parameter bHandledByCopilot tells whether or not the event was handled by CoPilot. For additional documentation on this callback, see https://developer.android.com/reference/android/view/KeyEvent.Callback
keyPressed
Method Java: public void keyPressed (KeyEvent e)
Platforms: Linux only
Type: Callback
Description: Called when a keyPressed event is received by CoPilot. For additional documentation on this callback, see KeyListener
KeyReleased
Method Java: public void keyReleased (KeyEvent e)
Platforms: Linux only
Type: Callback
Description: Called when a keyReleased event is received by CoPilot. For additional documentation on this callback, see KeyListener
keyTyped
Method Java: public void keyTyped (KeyEvent e)
Platforms: Linux only
Type: Callback
Description: Called when a keyTyped event is received by CoPilot. For additional documentation on this callback, see KeyListener
onSingleSearchReady
Method Java: public void onSingleSearchReady ()
Platforms: Android
Type: Callback
Description: Called when single search has finished initializing.
onSingleSearchFinished
Method Java: public void onSingleSearchFinished(StopList stopList, SingleSearchError error)
Platforms: Android
Type: Callback
Description: Called when single search web service gives back the response.

POIListener

POI Listeners relate to the POI APIs within the CoPilot Version

onPOISearchResults
Method Java: public void onPOISearchResults(List poiSearchResult, boolean bSearchComplete)
Method Obj-C: -(void) onPOISearchResults:(NSArray*) poiSearchResults searchComplete:(bool) searchComplete;
Type: Callback
Description: Called as POI search results update. This callback will be called continuously as the POI search list grows. The parameter bSearchComplete will be false while the list is still growing, and true when the search is complete. When the callback with the bSearchComplete set to true is received, the search is completed and no more callbacks will be received.
onPOIAlert
Method Java: public void onPOIAlert(List poiAlertList)
Method Obj-C: -(void) onPOIAlert:(NSArray*) poiAlerts;
Type: Callback
Description: Called as POI updates are received.

RouteListener

RouteListener's relate to RouteMgr

onGPSFixChanged
Method Java: public void onGPSFixChanged(GPSStatus fix)
Method Obj-C: -(void) onGPSFixChanged:(enum CPGpsState) fix
Type: Callback
Description: This Callback is called whenever the GPS fix has been acquired, lost or changed.
onStopsAdded
Method Java: public void onStopsAdded(StopList stopList)
Method Obj-C: -(void) onStopsAdded:(NSArray*) newStops
Type: Callback
Description: Called when one or more stops have been added to the current trip. If a trip exists and then a new trip is planned, onStopsDeleted() is called, followed by onStopsAdded()
onStopsMoved
Method Java: public void onStopsMoved(StopList stopList)
Method Obj-C: -(void) onStopsMoved:(NSArray*) movedStops
Type: Callback
Description: This callback is called when the order of stops changes in the current trip.
onStopsReplaced
Method Java: public void onStopsReplaced(StopList stopList)
Method Obj-C: -(void) onStopsReplaced:(NSArray*) replacedStops
Type: Callback
Description: This callback is fired when one or more stops have been replaced in the current trip.
onStopsDeleted
Method Java: public void onStopsDeleted (StopList stopList)
Method Obj-C: -(void) onStopsDeleted:(NSArray*) deletedStops;
Type: Callback
Description: onStopsDeleted will be called if stops are successfully deleted. The callback also returns a list of stops that were deleted. For RouteMgr.deleteStop, the returned stop list should only have one element. But for RouteMgr.removeAllStops, the return stop list can have more than one elements.
onReadyToAddStops
Method Java: public void onReadyToAddStops()
Method Obj-C: -(void) onReadyToAddStops
Type: Callback
Description: This callback is only called at startup when CoPilot is ready to add stops. It will not be called each time you add a new stop to your trip. However, if there is an existing route already in CoPilot, this callback will be fired when you re-launch CoPilot.
onStartRouteCalculation
Method Java: public void onStartRouteCalculation()
Method Obj-C: -(void) onStartRouteCalculation
Type: Callback
Description: Called when a route has started to be calculated.
onCompleteRouteCalculation
Method Java: public void onCompleteRouteCalculation()
Method Obj-C: -(void) onCompleteRouteCalculation
Type: Callback
Description: Called when a route calculation was completed.
onOutOfRoute
Method Java: public void onOutOfRoute(Date timeDeviation, RouteSyncLocation pointOfDeviation)
Method Obj-C: -(void) onOutOfRoute:(NSDate*) timeOfDeviation withLocation:(RouteSyncLocation*) pointOfDeviation
Type: Callback
Description: Called when CoPilot detects that the device is out of route.
onRejoinRoute
Method Java: public void onRejoinRoute(Date timeOfRejoin, RouteSyncLocation pointOfRejoin, double outOfRouteDistanceTraveled)
Method Obj-C: -(void) onRejoinRoute:(NSDate*) timeOfRejoin withLocation:(RouteSyncLocation*) pointOfRejoin withDistance:(double) outOfRouteDistanceTraveled
Type: Callback
Description: Called when CoPilot detects that the device has rejoined the route. Contains data concerning the duration of time and distance for which the device was out of route.
onStartChangeVehicleType
Method Java: public void onStartChangeVehicleType(VehicleType)
Method Obj-C: -(void) onStartChangeVehicleType:(enum CPVehicleType) vehicleType
Type: Callback
Description: Called before the current vehicle type changes with the current vehicle type.
onFinishChangeVehicleType
Method Java: public void onFinishChangeVehicleType(VehicleType)
Method Obj-C: -(void) onFinishChangeVehicleType:(enum CPVehicleType)vehicleType
Type: Callback
Description: Called after the vehicle type changes with the new vehicle type.
onRouteSyncError
Method Java: public void onRouteSyncError(RouteSyncError)
Method Obj-C: -(void) onRouteSyncError:(enum CPRouteSyncError)error
Type: Callback
Description: Called when there was an error processing a RouteSync route. This callback will also fire if there were any errors processing a saved managed route when CPIK starts. On Java, these events can be captured by listeners that are registered before starting the CoPilot service.
onRouteSyncRouteIntegrated
Method Java: public void onRouteSyncRouteIntegrated(String routeName)
Method Obj-C: -(void) onRouteSyncRouteIntegrated:(NSString*)routeName
Type: Callback
Description: Called when a route sync route has been integrated. The routeName string contains the name of the route set in JSON.
onRouteCalculation
Method Java: public void onRouteCalculation(AlternateRouteInfo alternateRouteInfo)
Method Obj-C: -(void) onRouteCalculation : (AlternateRouteInfo) alternateRouteInfo
Type: Callback
Description: Called once CoPilot has calculated each of the base and alternate routes for a set trip. Traffic will be applied once routes have been calculated if traffic has been activated against the license.The callback will be produced for each of the individual outputs:
1. CoPilot found the base route
2. CoPilot found alternate route 1
3. CoPilot found alternate route 2
4. CoPilot found traffic on base route (This can be called any time after base route calculation)
5. CoPilot found traffic on alternate route 1
6. CoPilot found traffic on alternate route 2
onStartAlternateRouteCalculation
Only supported in CoPilot 9.6.8
Method Java: public void onStartAlternateRouteCalculation()
Method Obj-C: -(void) onStartAlternateRouteCalculation
Type: Callback
Description: Called when CoPilot starts the calculation of an alternate routes once the base route calculation has completed.
onCompleteAlternateCompleteRouteCalculation
Only supported in CoPilot 9.6.8
Method Java public void onCompleteAlternateRouteCalculation()
Method Obj-C: -(void) onCompleteAlternateRouteCalculation
Type: Callback
Description: Called when CoPilot has finished calculating all alternate routes. Once this has been received no further routes will be calculated and provided via onRouteCalculation.
onAlternateRouteSelected
Only supported in CoPilot 9.6.8
Method Java: public void onAlternateRouteSelected(int tripID)
Method Obj-C: -(void) onAlternateRouteSelected: (int) tripID
Type: Callback
Description: Called when the user selects a route via the alternate route screen. It will identify the route selected by the user in the integrated application and as a result the route which CoPilot should use.
onFailedRouteCalculation
Deprecated in CoPilot 10.14
Method Java: public void onFailedRouteCalculation(int iLegNum, Stop badStop)
Type: Callback
Description: Called when a route calculation is attempted but fails. The callback data includes the leg number identifier and Stop that causing the route calculation to fail.
onFailedRouteCalculation
Available in CoPilot 10.14 or Higher
Method Java: public void onFailedRouteCalculation(int iLegNum, Stop badStop, RouteEnums.RouteCalculationError errorCode)
Type: Callback
Description: Called when a route calculation is attempted but fails. The callback data includes the leg number identifier, the Stop the causing the route calculation to fail and an error message with the reason for the failure.

GuidanceListener

GuidanceListener's are callbacks from the APIs in GuidanceMgr

onArrivedAtStop
Method Java: public void onArrivedAtStop(boolean isDestination, boolean arrived, Stop stop) {}
Method Obj-C: -(void) onArrivedAtStop:(bool)bIsFinalStop arrived:(enum ArrivalStatus)eArrived withStop:(Stop*)stop;
Type: Callback
Description: Callback is provided when a user has registered a GuidanceListener with the onArrivedAtStop class. Uses the enum ArrivalStatus, to provide status details of the stop.

The approaching and arrival status messages are controlled by a set of configuration values that can be set within the product/user configuration file. [User Settings] "ApproachingStopDistHundredths", and "ArrivedStopDistHundredths" options both indicate the distance threshold, in hundredths of a mile, from your stop, where the user will see the prompt (popup, sound, or speech) to be shown. The defaults are:

  • [User Settings]
    "ApproachingStopDistHundredths"=5 // (~250 feet)
    "ArrivedStopDistHundredths"=-1 // (default is OFF)

  • If you would like the Arrived prompt, it is recommended to prompt at 1 or 2 hundredths of a mile (50 or 100 feet from the stop). "ArrivedStopDistHundredths"=1 or 2

  • [GPS] "SpeakApproachingDestinationInstr", "SpeakArrivedAtDestinationInstr", "PlayArrivedAtDestinationSound", "PlayApproachingDestinationSound" can be used to modify how CoPilot indicates “Approaching or Arrived” status (whether prompted with Text To Speech, sound, or no prompt). The onArrivedAtStop callback will fire regardless of these settings. If they are all accidentally set to on, the Speech announcement will prompt.

  • [User Settings] "ShowArrivalPopup" can be used to request CoPilot DOES NOT show the Arrival Popup. Showing or not showing the popup, does NOT have any affect on whether or not the status event is fired through CPIK.

onTruckWarningUpdate
Method Java: public void onTruckWarningUpdate(TruckWarning truckWarning)
Method Obj-C: -(void) onTruckWarningUpdate:(CoPilotTruckWarningInfo*)info
Type: Callback
Description: Called when there is a truck warning update.
onOverSpeedLimitEvent
Method Java: public void onOverSpeedLimitEvent(OverSpeedLimitWarning speedWarning)
Method Obj-C: -(void) onOverSpeedLimitEvent:(OverSpeedLimitWarning*)warning
Type: Callback
Description: Called when there is a warning for traveling over the speed limit.
onCrossedCountryBorder
Method Java: public void onCrossedCountryBorder(Country newCountry)
Method Obj-C: -(void) onCrossedCountryBorder:(Country*)country
Type: Callback
Description: Called when navigating into a new country.
onSafetyCamUpdate
Method Java: public void onSafetyCamUpdate(SafetyCamera info)
Method Obj-C: -(void) onSafetyCamUpdate:(SafetyCamera*)info
Type: Callback
Description: Called when new safety camera information is available.
onShowLaneAssist
Method Java: public void onShowLaneAssist(LaneAssistInfo info)
Method Obj-C: -(void) onShowLaneAssist:(LaneAssistInfo*)info
Type: Callback
Description: Called when lane assist information is available for the current road segment.
onHideLaneAssist
Method Java: public void onHideLaneAssist()
Method Obj-C: -(void) onHideLaneAssist
Type: Callback
Description: Called when lane assist information should no longer be displayed to the user.
onETAChanged
Method Java: public void onETAChanged(Date newETA)
Method Obj-C: -(void) onETAChanged:(NSDate*)newETA
Type: Callback
Description: Called when the ETA for the current trip has changed by a minute or more.
onEstimatedTravelTimeUpdated
Method Java: public void onEstimatedTravelTimeUpdated(int iHoursOfTravel, int iMinutesOfTravel)
Method Obj-C: -(void) onEstimatedTravelTimeUpdated:(int)iHoursOfTravel withMinutes:(int)iMinutesOfTravel
Type: Callback
Description: Called when the ETT for the current trip has changed by a minute or more.
onDistanceToDestinationUpdated
Method Java: public void onDistanceToDestinationUpdated(double dDistanceToDestination)
Method Obj-C: -(void) onDistanceToDestinationUpdated:(double)dDistanceToDestination
Type: Callback
Description: Called whenever CoPilot computes the distance to destination (could be approximately.
onPositionUpdate
Method Java: public void onPositionUpdate(PositionInfo position)
Method Obj-C: -(void) onPositionUpdate:(CPPositionInfo*)info
Type: Callback
Description: Called whenever there is additional position information
onTurnInstructionEvent
Method Java: public void onTurnInstructionEvent(TurnInstruction instruction)
Method Obj-C: -(void) onTurnInstructionEvent:(TurnInstruction*) guidanceInformation
Type: Callback
Description: Called when new guidance information is available.
onTrafficInfoProcessedForCurrentRoute
Method Java: public void onTrafficInfoProcessedForCurrentRoute()
Method Obj-C: -(void) onTrafficInfoProcessedForCurrentRoute
Type: Callback
Description: Called when traffic information received and processed from the traffic server for the current route. Customer application get the ETA as well traffic delay by using the RouteMgr.getRouteLegs().get(0).getETA() and RouteMgr.getRouteLegs().get(0).getTrafficDelay() respectively.
onTrafficInforProcessedForAlternateRoute
Method Java: public void onTrafficInforProcessedForAlternateRoute (int etaInMinutes)
Method Obj-C: -(void) onTrafficInforProcessedForAlternateRoute: (int) etaInMinutes
Type: Callback
Description: Called when traffic information received and processed for all alternative routes and when traffic alert dialog box showed to the user to provide options (Whether better alternate route is available or current route is still better) etaInMinutes in the Callback indicates the ETA of the alternative route. Zero minutes indicate that current route is better and no alternate route available. Non-zero value indicates that alternate route is better and etaInMinutes shows the ETA of the alternate route.
onSpeedLimitChanged
Method Java: public void onSpeedLimitChanged(int speedLimit, int truckSpeedLimit)
Type: Callback
Description: Called each time the current speed limit changes. The units will be mph if co-pilot is set to imperial units, or if the configuration "CPIK" / "AlwaysReturnInMiles" is set. The units will be km/h if CoPilot’s units are set to metric and the configuration "CPIK" / "AlwaysReturnInMiles" is not set. If speed limit data is not available for the current road, the value GuidanceListener.SPEED_LIMIT_NO_DATA will be returned. If the road does not have a speed limit (Example Autobahn in Germany or Stuart Highway in Australia), the value GuidanceListener.UNLIMITED_SPEED will be returned.
onItineraryUpdated
Method Java: public void onItineraryUpdated ()
Method Obj-C: (void) onItineraryUpdated
Type: Callback
Description: Called when itinerary is changed in CoPilot. This callback is being called when any of the following events occurred.
- Route calculation finished
- Route is finished
- Refresh of the route calculation dialog
- Current segment (link) is changed
- Any Detour
- Penalty added to link/segment (traffic received)
- Penalty removed from link/segment (traffic is cleared)
- Update itinerary report in case language or distance unit changed
- Trip is changed
onRoadClassChanged
Method Java: public void onRoadClassChanged(RoadClass previousRoadClass, RoadClass currentRoadClass)
Method Obj-C: (void) onRoadClassChanged:(enum CP_RoadClass)prevRoadClass withCurrRoadClass:(enum CP_RoadClass)currRoadClass
Type: Callback
Description: Called each time the road class changes. Parameters contain previous and new road class.
onStopArrivalStatusChange
Method Java: public void onStopArrivalStatusChange(StopList stopList)
Method Obj-C: -(void) onStopArrivalStatusChange:(NSArray*)stops
Type: Callback
Description: Called when a driver's stop's status changes (e.g OnTime to Late). The callback will return a list of stops who status have been changed.

SpeechListener

SpeechListeners are callbacks from the APIs found in SpeechMgr

onReadyToSpeakTurnInstruction
Method Java: public void onReadToSpeakTurnInstruction()
Method Obj-C: (void) onReadyToSpeakTurnInstruction
Type: Callback
Description: Called when CoPilot is about to play a turn instruction. Will not fire if CoPilot has been muted. To ensure this callback is provided the following setting must be set within the user.cfg
[User Settings]
"EnableTurnAlert"=1
This can be set by using the ConfigurationSetting API by using the ENABLE_TURN_ALERT value.
onSpeakTurnInstructionComplete
Method Java: public void onSpeakTurnInstructionComplete()
Method Obj-C: (void) onSpeakTurnInstructionComplete
Type: Callback
Description: Called after CoPilot has finished playing a turn instruction. If a message is sent with a mute override, this callback will fire, otherwise, if CoPilot is muted, it will not. To ensure this callback is provided the following setting must be set within the user.cfg
[User Settings]
"EnableTurnAlert"=1
This can be set by using the ConfigurationSetting API by using the ENABLE_TURN_ALERT value.
onReadyToSpeakUtterance
Method Java: public void onReadyToSpeakUtterance()
Method Obj-C: (void) onReadyToSpeakUtterance
Type: Callback
Description: Called when CoPilot is about to speak and utterance, including a turn instruction.
onSpeakUtteranceComplete
Method Java: public void onSpeakUtteranceComplete()
Method Obj-C: (void) onSpeakUtteranceComplete
Type: Callback
Description: Called after CoPilot has finished speaking anything including a turn instruction.
onSpeakTurnInstruction
Method Java: public void onSpeakTurnInstruction(String turnInstruction)
Type: Callback
Platforms: Linux
Description: Called when CoPilot is about to speak using a TTS String. The turnInstruction parameter contains the text that is to be spoken.
selectCoPilotLanguage
Method Java: public int selectCopilotLanguage(List<​Locale>availableLocales)
Type: Hook
Platforms: Linux
Description: Called on first start when a language must be selected. Returns the index within the list, availableLocales, of the language you wish to select. This allows selecting the first run language programmatically.
beforeSoundHook
Method Java: public Boolean beforeSoundHook(SoundType sound)
Type: Hook
Platforms: Linux
Description: Called before a sound is about to be played. The SoundType parameter contains the type of sound. Return true to play the sound, or false to stop the sound from being played.
onAfterSoundPlayed
Method Java: public void onAfterSoundPlayed()
Type: Callback
Platforms: Linux
Description: Called after a sound has finished playing.
onVoiceDownloadStatusUpdate
Method Java: public void onVoiceDownloadStatusUpdate (VoiceDownloadStatus status, VoiceInfo voice)
Method Obj-C: -(void) onVoiceDownloadStatusUpdate:(enum VoiceDownloadStatus)status forVoice:(VoiceInfovoice;
Type: Callback
Description: Called when there is an update on the download status of a voice.

UIListener

UIListeners are callbacks from the UIMgr APIs

onShowNavigationScreen
Method Java: public void onShowNavigationScreen(MapDrawer.MapViewType curView)
Method Obj-C: -(void) onShowNavigationScreen
Type: Callback
Description: Called when the navigation screen (map) is shown.
onLeaveNavigationScreen
Method Java: public void onLeaveNavigationScreen()
Method Obj-C: -(void) onLeaveNavigationScreen
Type: Callback
Description: Called when the navigation screen (map) is hidden.
onShowItineraryScreen
(Removed in CoPilot 10. Use UIListener.onShowNavigationScreen(MapDrawer.MapViewType curView), where curView is MapDrawer.MapViewType.ITINERARY)
Method Java: public void onShowItineraryScreen()
Method Obj-C: -(void) onShowItineraryScreen
Type: Callback
Description: Called when the itinerary screen (list of directions) is shown.
onShowSafetyViewScreen
Method Java: public void onShowSafetyViewScreen()
Method Obj-C: -(void) onShowSafetyViewScreen
Type: Callback
Description: Called when the safety view screen (next direction) is shown.
onStartingPoiWizard
Method Java: public void onStartingPoiWizard()
Method Obj-C: -(void) onStartingPoiWizard
Type: Callback
Description: Called when the POI wizard is shown.
onMapImageTouchEvent
Method Java: public void onMapImageTouchEvent(MapImageInfo mapImageInfo)
Type: Callback
Description: Called when a map image that was previously created using MapDrawer#drawImages(MapImageSet) was touched by the user.
onMapImageImportStatusUpdate
Method Java: public void onMapImageImportStatusUpdate(MapImageImportStatus status, String errorDescription)
Type: Callback
Description: Called when a request to MapDrawer#drawImages(MapImageSet) completes, either with a success or failure.
onMinimize
Method Java: public void onMinimize
Type: Callback
Description: Called when the user presses the back button on CoPilot navigation dialog. It is recommended that this is used to remove CoPilot view from fragment to show partner application
onZoomAnimationCompleted
Method Java: public void onZoomAnimationCompleted(MapDrawer.MapZoomLevel level)
Method Obj-C -(void) onZoomAnimationCompleted:(enum CPMapZoomLevel)level
Type: Callback
Description: Called when animation caused by MapDrawer.setMapZoomLevel(MapZoomLevel) completes. Also returns the current zoom level.

MapDataListener

MapDataListeners are callbacks from MapDataMgr

onMapdataUpdate
Method Java: public void onMapdataUpdate(MapDataSet mapSet, DownloadStatus status)
Method Obj-C: -(void) onMapDataUpdate:(MapDataSet* )mapSet andStatus: (CPMapDownloadStatus)status
Type: Callback
Description: Called when there is an update on a map download.
selectMapRegion
Method Java: public MapDataSet selectMapRegion(List availableMaps)
Platforms: Linux, Android
Type: Hook
Description: Called when CoPilot starts and a map region needs to be selected. availableMaps contains a list of MapDataSet that are available. Returning one of these MapDataSets selects that region to be licensed.
onMapSureOverrideSyncStarted
Method Java: public void onMapSureOverrideSyncStarted()
Platforms: Android
Type: Callback
Description: Called when CoPilot has started a MapSure sync in response to a call to the API getMapSureOverride().
onMapSureOverrideSyncFailed
Method Java: public void onMapSureOverrideSyncFailed()
Platforms: Android
Type: Callback
Description: Called when CoPilot has triggered a MapSure sync in response to a call to the API getMapSureOverride() but it has failed.
onMapSureOverrideSyncSuccess
Method Java: public void onMapSureOverrideSyncSuccess(int successful, int failed)
Platforms: Android
Type: Callback
Description: Provides notification that a MapSure Override sync has completed and it includes the number of edits that have been successfully updated and the number that have failed
onReadyToDownloadInitialMapData
Method Java: public void onReadyToDownloadInitialMapData() { }
Platforms: Android
Type: Callback
Description: Callback to notify the user that CoPilot is ready to download initial map data
onMapDownloadResponse
Method Java: public void onMapDownloadResponse(MapDownloadResponse response, List<​MapRegion> requestedRegions, boolean bOverwriteExistingMaps) {}
Platforms: Android
Type: Callback
Description: Called with the download response of a map data download
onMapLocationPicked
Method Java: public void onMapLocationPicked(Stop)
Method Obj-C (void) onMapLocationPicked(Stop)
Platforms: Android, iOS
Type: Callback
Description: When user calls MapDataMgr.sendMapFeedback() and the json that sent in has the option “ReturnMapPickUp” turned on, CoPilot will show a map view where user can pick up location there. This callback will be called when a location is picked. The callback returns a stop object which is the picked location.

LicenseListener

LicenseListeners are hooks and callbacks from LicenseMgr

onLicenseMgtLogin
Available in CoPilot 10.14.0.368 and Higher
Method Java: public void onLicenseMgtLogin(LicenseActivationResponse activationStatus, LicenseMgtInfo loginInfo)

activationStatus - The license activation status observed. See LicenseActivationResponse for possible responses.

loginInfo - a LicenseMgtInfo object containing the username and company name combination for which activationStatus was observed.

Type: Callback
Description: This callback is fired during login events using the Trimble MAPS Account Manager.
@Override
public void onLicenseMgtLogin() {
   makeToast("onLicenseMgtLogin \nStatus : " + activationStatus.name()
+ "\nUserName :" + loginInfo.getUserName() + "\nCompanyName :"
+ loginInfo.getCompanyName());
}
licenseMgtCredentialHook
Available in CoPilot 10.14.0.368 and Higher
Method Java: public LicenseMgtInfo licenseMgtCredentialHook()
Type: Hook
Description: This hook is fired on startup requesting credentials to use for AMS login. The integrating app can either respond with:

1. New login credentials: Copilot logs out any pre-existing account and removes all pre-existing licenses and attempts to login with the new user.

2. The same user information that is already logged in: Copilot does nothing with this and attempts to restore licenses for the existing account as it always does.

3. An empty object: Copilot attempts to restore licenses if a user is already logged in. Otherwise, it continues its regular startup process.

Notes

  • Upon a successful Account Manager login, Copilot will no longer fire the mapRegionUpgradeKeyHook and the following APIs are also disabled, licenseMgr.activateLicense and licenseMgr.deactivateLicense.

  • Our sample application implements this hook to respond to it with info from a AMSUserInfo.txt file in the root directory of CoPilot. We expect the file to contain the username and the company name separated by a semicolon. Example: amsuser;CMPNAM

@Override
public LicenseMgtInfo licenseMgtCredentialHook() {
   return new LicenseMgtInfo("User", "Company");
}
onFeatureActivated
Method Java: public void onFeatureActivated(LicenseFeature activatedFeature)
Method Obj-C: -(void) onFeatureActivated:(CPLicenseFeatures)activatedFeature
Type: Callback
Description: Called when a license is successfully activated. This callback is fired once for each feature.
onInAppPurchase
Method Java: public void onInAppPurchase(String productID, String orderID)
Method Obj-C: -(void) onInAppPurchase:(NSString*)productID withOrderID:(NSString*)orderID
Type: Callback
Description: Called when an in app purchase has been successfully made and the product key has been successfully activated.
onLicensingReady
Method Java: public void onLicensingReady()
Method Obj-C: -(void) onLicensingReady
Type: Callback
Description: Called when CoPilot is ready to accept licenses to be activated.
mapRegionUpgradeKeyHook
Method Java: public License mapRegionUpgradeKeyHook()
Platforms: Android, Linux
Type: Hook
Description: Called on a first start when an upgrade key is required to license a region.

Note

When using the mapRegionUpgradeKeyHook() method to activate an upgrade key, the key should be hard coded in the application. For demonstration purposes within our sample application, you can put the upgrade product keys in a text file named key.txt within the CoPilot directory.

OptimizationListener

Callbacks related to OptimizationMgr

onOptimizationProgress
Method: public void onOptimizationProgress(OptimizationEnums.OptimizationNotification optNotification)
Platforms: Android, Linux
Type: Callback
Description: Called to provide progress update for Optimization.
onOptimizationError
Method: public void onOptimizationError(OptimizationEnums.OptimizationError optError)
Platforms: Android, Linux
Type: Callback
Description: Called to provide error encountered during the Optimization. Optimization will be stopped after getting this error.
onOptimizationStopError
Method: public void onOptimizationStopError(OptimizationEnums.OptimizationstopError stopError, short sStopNo)
Platforms: Android, Linux
Type: Callback
Description: Called to provide stop error encountered during the Optimization. Optimization engine will still go ahead by ignoring those stops.
onOptimizationStopGeocode
Method: public void onOptimizationStopGeocode(short sStopNo, Coordinate coord, short sError)
Platforms: Android, Linux
Type: Callback
Description: Called to provide geocode results where stops having address data but does not contain the latitude/longitude.
onOptimizationResult
Method: public void onOptimizationResult(short sFinalETA, double dTotalDistance, ArrayList optOutStops)
Platforms: Android, Linux
Type: Callback
Description: Called to provide Optimization result once Optimization finished. It will provide final ETA, total distance as well individual stop’s optimization number, ETA and distance.

GeofenceListener

Callbacks related to GeofenceMgr

onGeofenceEntry
Method: public void onGeofenceEntry(Geofence geofence, Coordinate position, Date time)
Platforms: Android, Linux
Type: Callback
Description: Called when the current position enters a geofence that has an entry notification sent. Contains details on the geofence that was entered, the position at which the geofence was entered, and the time at which the geofence was entered.
onGeofenceExit
Method: public void onGeofenceExit(Geofence geofence, Coordinate position, Date time)
Platforms: Android, Linux
Type: Callback
Description: Called when the current position leaves a geofence that has an exit notification sent. Contains details on the geofence that was exited, the position at which the geofence was exited, and the time at which the geofence was exited.
onGeofenceRouteThrough
Method: public void onGeofenceRouteThrough(List<Geofence> geofenceList)
Platforms: Android, Linux
Type: Callback
Description: Called when a route is calculated which passes through any geofences which have the route through notification set.

Last update: May 12, 2020