Hooks and Callbacks (CPIK Libraries)

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 behavior 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. User can return true if they desire the Custom Contact List
    // Your code here

    return true;
  }
  @Override
  public void onCPStartup() {
    // This is a callback method. User can write some code if they think they want to do something on this callback
    // Write your code here
  }
  @Override
  public void onCPShutdown() {
     // This is a callback method. User can write some code if they think they want to do something on this callback
     // 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

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

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

Driver alerts

(Available in CoPilot 10.19.0.1798 and Later)

CoPilot issues pop-up alerts for drivers in a number of situations related to traffic conditions and road restrictions. An outside application can use the callbacks below to identify when these events happen.

Traffic alerts

TrafficAlertInfo class

TrafficAlertType enum

Traffic Alert Config Settings

Config settings are also available to manage the behavior of pop-up messages related to traffic alerts.

For traffic alerts:

[FlowTraffic]
"ShowTrafficAlertPopup" = true

See the possible config settings for sudden slowdown alerts.

Sample Code

public void onTrafficAlert(TrafficAlertInfo trafficAlertInfo) {
            super.onTrafficAlert(trafficAlertInfo);
            if(mGuidanceListenerMsgTable.get(GUIDANCE_onTrafficAlert)){
                String message ="";
                if(trafficAlertInfo.getTrafficAlertType() == TrafficAlertType.TRAFFIC_ALERT_TRAFFIC_DETOUR)
                    message = "onTrafficAlert received:\n OrigMins:" + trafficAlertInfo.getOrigDurationMins() + " DetourMins:"+ trafficAlertInfo.getDetourDurationMins();
                else if(trafficAlertInfo.getTrafficAlertType() == TrafficAlertType.TRAFFIC_ALERT_ROAD_CLOSURE)
                    message = "onTrafficAlert received:\n Road Closure - Road name:" + trafficAlertInfo.getTrafficAlertType();
                else if(trafficAlertInfo.getTrafficAlertType() == TrafficAlertType.TRAFFIC_ALERT_SLOWDOWN)
                    message = "onTrafficAlert received:\n Traffic Slowdown in " + trafficAlertInfo.getDistance() + " miles";
                MainActivity.makeToast(message);
            }
        }

Environmental alerts

EnvironmentZoneType enum

Restricted road alerts

TruckRestrictionType enum

Truck Restriction Config Setting

The following setting affects whether to show restricted warnings to the driver.

[User Settings]
“ShowRestrictedRoadWarning” = true

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