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

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.

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

OptimizationListener¶

Callbacks related to OptimizationMgr

GeofenceListener¶

Callbacks related to GeofenceMgr