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

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;
      }
}

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;
      }
}

POIListener¶

POI Listeners relate to the POI APIs within the CoPilot Version

RouteListener¶

RouteListener's relate to RouteMgr

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

GuidanceListener¶

GuidanceListener's are callbacks from the APIs in GuidanceMgr

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.

| 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. | |

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

SpeechListener¶

SpeechListeners are callbacks from the APIs found in SpeechMgr

UIListener¶

UIListeners are callbacks from the UIMgr APIs

MapDataListener¶

MapDataListeners are callbacks from MapDataMgr

LicenseListener¶

LicenseListeners are hooks and callbacks from LicenseMgr

@Override
public void onLicenseMgtLogin() {
   makeToast("onLicenseMgtLogin \nStatus : " + activationStatus.name()
+ "\nUserName :" + loginInfo.getUserName() + "\nCompanyName :"
+ loginInfo.getCompanyName());
}

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"); }

OptimizationListener¶

Callbacks related to OptimizationMgr

GeofenceListener¶

Callbacks related to GeofenceMgr