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 SDK Libraries 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 SDK Libraries 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
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
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 SDK Libraries. 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. If you rely on getting the advance ETA after the route calculation is completed, you will need to register for onStopArrivalStatusChange. |
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 SDK Libraries 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 SDK Libraries.
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 first time when a trip containing advance ETA information is sent to CoPilot which in return provides a status for each stop. It will also be called when a driver's stop's status changes (eg. OnTime to Late). The callback will return a list of stops who's status has been changed. Any user relying on getting advance ETA's should wait for this callback before retrieving ETA from the stop. |
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.
Option 1: If you are using Asset ID and Company ID, we expect the file to contain the Asset ID and the Company ID separated by a semicolon. Example: amsuser;CMPNAM
@Override public LicenseMgtInfo licenseMgtCredentialHook() { return new LicenseMgtInfo("amsuser", "CMPNAM"); }
Option 2: If you are using Asset ID, External Account ID, and Partner ID, we expect the file to contain the Asset ID, External Account ID, and Partner ID separated by semicolons. Example: amsuser;myextacctid;AL4BA0
@Override public LicenseMgtInfo licenseMgtCredentialHook() { return new LicenseMgtInfo("amsuser", "myextacctid", "AL4BA0"); }
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: February 10, 2021