Summary
Overview of SDK API’s
Launching CoPilot and Initiating Messaging
These APIs are used to start & exit CoPilot. It also used to start and shutdown messaging.
| API | Description |
|---|---|
| Msg_HasStarted | Determines whether the messaging layer has been initialized by a call to Msg_StartUp(). In most scenarios, this should be the first API called, as this will determine if CoPilot is already initiated and connected. |
| Msg_Startup | Starts up messaging communications using user.cfg [ConnectionInfo1] file for connection parameters. |
| Msg_IsConnected | Determines if the application layer is actually connected to the CoPilot application. Use this API to check that the application communication is established, once Msg_Startup has been called. |
| ALK_StartCoPilot | The call to Launch CoPilot, this offers a simple launch with options to show/hide. |
| ALK_StartCoPilotEx | Launch CoPilot including show/hide mode but with advance option to define the window parameter CoPilot will run within. |
| ALK_ExitCoPilot | Send message for CoPilot to exit properly if messaging is connected. If messaging is not connected, it will close the CoPilot process forcefully. |
| ALK_GetCoPilotWindow | It will retrieve the CoPilot window handle. |
| Msg_SendAppExit | Send message to CoPilot to exit the application properly. If it is not possible to close the application properly, CoPilot will not exit. We recommend to use ALK_ExitCoPilot rather than this API. |
| Msg_Shutdown | Shuts down the messaging communications between the two application. This function must be the last function before the client application exits. |
Callbacks
These APIs are used to set the callback based on message type. It also used to provide queue functionalities if platform does not support callback.
| API | Description |
|---|---|
| Msg_SetCallback | Set a callback function for a particular message type. Used in conjunction with subscription-based messages. We recommend using Msg_UpdateOptions instead of Msg_SetCallback. |
| Msg_UpdateOptions | Updates the options for different ALK messages. Primarily used for setting callback function. We recommend to use Msg_UpdateOptions instead of Msg_SetCallback. |
| Msg_Subscribe | Subscribe to event-based notification of real-time information from the CoPilot application. |
| Msg_Unsubscribe | Unsubscribe to event-based notification of real-time information from the CoPilot application. |
Buffer Management
These APIs are used to delete the parser previously allocated when sending data to CoPilot.
| API | Description |
|---|---|
| Msg_ParserDelete | Delete a previously-allocated message buffer handle and free associated resources. |
License Activation
The below APIs are used to activate/deactivate and query license status.
| API | Description |
|---|---|
| Msg_ActivateLicense | This function use to activate the license by passing the product key. Response of the activation is being send by Msg_ID_LicenseResponse. |
| Msg_DeactivateLicense | This function use to deactivate the license by passing the product key. Response of the deactivation is being send by Msg_ID_LicenseResponse. |
| Msg_LicenseStatus | This function use to retrieve the license information associated with given product key. |
| Msg_GetLicenseNotification | This function is helper function to decode the response received in context of Msg_ActivateLicense and Msg_DeactivateLicense. This function is also use when CoPilot send the notification regarding license when CoPilot start up. |
| Msg_GetLicenseStatus | This function is helper function to decode the response received in context of Msg_LicenseStatus. |
| Msg_GetCurrentMapRegion | This API will be used following Msg_ActivateLicense to determine which map region CoPilot is currently locked to for licensing purposes, or to determine that a map region has not yet been selected. This should be used following the activation of a major region license, for instance, UK, France or DACH. It is not required if you have a PAN region license as there is no selection necessary. |
| Msg_GetAllowedMapRegions | This API will be used following Msg_ActivateLicense to determine a list of the available map data regions with the current license. This should be used following the activation of a major region license, for instance, UK, France or DACH. It is not required if you have a PAN region license as there is no selection necessary. |
| Msg_SetLockedMapRegion | This API can be used to specify the map region CoPilot will use, on the condition that the current license allows for that region as determined by Msg_GetAllowedMapRegions. Once a region has been set it can not be changed. |
| Msg_ParseMapRegionResponseActionCode | This API can be used to interpret the data received from Msg_GetCurrentMapRegion(), Msg_GetAllowedMapRegions(), Msg_SetLockedMapRegion(). This will provide the action code related to the callback and indicate which API the response you have received relates to. |
| Msg_ParseMapRegionResponseStatusCode | This API can be used to interpret the data received from Msg_GetCurrentMapRegion(), Msg_GetAllowedMapRegions(), Msg_SetLockedMapRegion(). This will provide the action code related to the callback and indicate the status of the response you have received. |
| Msg_ParseMapRegionResponseNumberOfRegions | This API can be used to determine the number of regions that are included in a response from a call to either Msg_GetCurrentMapRegion(), Msg_GetAllowedMapRegions () or Msg_SetLockedMapRegion(). Use this API alongside Msg_ParseMapRegionResponseRegionInfo() to extract more detailed information about each region that was included in the response. |
| Msg_ParseMapRegionResponseRegionInfo | This API can be used to extract the map region info included in a response from a call to either Msg_GetCurrentMapRegion()Msg_GetAllowedMapRegions or Msg_SetLockedMapRegion(). Use this API alongside Msg_ParseMapRegionResponseNumberOfRegions() to extract more detailed information about each region that was included in the response. |
Searching and Entering Destinations
These APIs are used to send the destinations to the CoPilot application, including waypoint, as well as retrieving current stop information.
| API | Description |
|---|---|
| Msg_TripLoad | Allocate a trip message buffer and return its buffer handle. This needs to be included in every new trip to be sent to CoPilot. This defines the options for how the trip is to be added. |
| Msg_TripAddStopWithHouseNum | Add a stop to a previously allocated trip message buffer, all individual stops need to be added. To be used when House number and Street Address need to be defined separately. We recommend client application uses Msg_TripAddStopWithHouseNum instead of Msg_TripAddStop. |
| Msg_SendTrip | Send a new trip itinerary (list of stops) to the application. This is used following Msg_TripLoad and Msg_TripAddStopWithHouseNum. |
| Msg_TripParse | This is the first API to be used if you want to receive all of the details of the currently loaded Trip. Decodes and retrieves the message ID from a trip message buffer. |
| Msg_TripGet | This is the second step to be used if you want to receive details of the currently loaded Trip. This provides header information including the total number of stops. |
| Msg_TripGetStopInfo | Used in conjunction with Msg_Trip* APIs, returns itinerary stop list information from a Msg_ID_Trip message, returning all individual stop details. We recommend to use Msg_tripGetStopWaypointInfo instead of Msg_TripGetStopInfo. |
| Msg_TripGetStopWaypointInfo | Used in conjunction with Msg_Trip* APIs, returns itinerary stop list information from a Msg_ID_Trip message, returning all individual stop details including Waypoints. We recommend to use Msg_tripGetStopWaypointInfo instead of Msg_TripGetStopInfo. |
| Msg_SendTripStopInfoRequest | Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary, to be followed by Msg_TripGet* APIs. We recommend to use Msg_SendStopInfoRequest instead of Msg_SendTripStopInfoRequest. |
| Msg_SendStopInfoRequest | Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary, to be followed by Msg_Trip* APIs. Includes information on Waypoints. We recommend to use Msg_SendStopInfoRequest instead of Msg_SendTripStopInfoRequest. |
| Msg_MultiStopParse | Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH. Returns the message ID to be used with Msg_MultiStopGet* APIs. |
| Msg_MultiStopGetHeader | Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH. Returns the header information including the number of stops. |
| Msg_MultistopGetDetails | Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH. Returns the individual stop details. |
Geocoding Locations
These APIs are used to geocode the stop to latitude/longitude as well reverse geocoded from latitude/longitude to stop.
| API | Description |
|---|---|
| Msg_RequestGeocode | Request to CoPilot providing a latitude/longitude for an address. |
| Msg_RequestReverseGeocode | Request to reverse geocode and provide the address closest to the given latitude and longitude. |
| Msg_ReverseGeocodeInfo | Retrieves and decodes the address information from a Msg_ID_ReverseGeocode message. To be used in conjunction with Msg_RequestReverseGeocode. |
Address Searching
These APIs are used to do typeahead search for address. By using these APIs, customers can implement a very similar address entry experience as the one in CoPilot.
| API | Description |
|---|---|
| Msg_SearchCityAndPostcode | Request a search of City and Postcodes based upon provided prefix. This API gives same results like user type in CoPilot. |
| Msg_SearchStreet | Following Msg_SearchCityAndPostcode this will request a search for a street based upon provided criteria including partial name. |
| Msg_SearchExtendedStreet | Following Msg_SearchStreet returns complete street name this API will return all multiple matches for the street and house number. |
| Msg_RequestMoreSearch | Requests to retrieve more search results (city, postcode or street) based upon last request, used when more results are available than max results provided. |
| Msg_SearchParse | Required to retrieve results following a city, street or postcode search. Decodes and retrieves the message ID from a search message buffer. |
| Msg_SearchGetHeader | Required to retrieve results following a city, street or postcode search. Retrieves the search address details from given search. |
| Msg_SearchGetDetails | Required to retrieve results following a city, street or postcode search. Retrieves the search identifier, search count and error codes. |
| Msg_ClearSearchResults | Once the city, postcode or street search completed this API should be used to remove the cache results from the memory and stop searching. |
POI Searching
These APIs are used to provide POI search functionality. User can search the POI based on current location, on the route and at location within specified radius.
| API | Description |
|---|---|
| Msg_SearchPOIEx | Request a search of POIs based upon a series of criteria including by category, location, on a route etc. |
| Msg_RequestMorePOI | Sends a request to retrieve more POIs based upon last request criteria provided in Msg_SearchPOIEx. |
| Msg_POIParse | Required to retrieve results following Msg_SearchPOIEx and Msg_RequestMorePOI. Decodes and retrieves the message ID from a POI search message buffer. |
| Msg_POIGetHeader | Required to retrieve results following Msg_SearchPOIEx and Msg_RequestMorePOI. Decodes and retrieves the POI count and error codes. |
| Msg_POIGetDetails | Required to retrieve results following Msg_SearchPOIEx and Msg_RequestMorePOI. Returns the POI details for the selected result. |
| Msg_ClearPOIResults | Once the POI search is completed this API should be used to remove the cached results from memory and stop searching POIs. |
Creating and Saving Favorite locations
The below APIs are used to set/get the favorites to/from CoPilot.
| API | Description |
|---|---|
| Msg_SetFavoritesStopInfo | Set the request to CoPilot to add the given favorites including home, work and others. |
| Msg_SendFavoritesStopRequest | Sends the request to CoPilot to to retrieve favorites. To be followed by Msg_FavoritesStopParse, Msg_FavoritesStopGetHeader, Msg_FavoritesStopGetDetails to retrieve favorite stop details. |
| Msg_FavoritesStopParse | This is the helper function to retrieve the favorite stops requested using Msg_SendFavoritesStopRequest. Returns the parser ID to be used with Msg_FavoritesStopGetHeader and Msg_FavoritesStopGetDetails. |
| Msg_FavoritesStopGetHeader | This is the helper function to retrieve the favorite stops requested using Msg_SendFavoritesStopRequest. Returns the header information including the number of stops and any error. |
| Msg_FavoritesStopGetDetails | This is the helper function to retrieve the favorite stops requested using Msg_SendFavoritesStopRequest. Returns the individual stop details. |
Custom POI Management
These APIs are used to add and delete custom POI categories dynamically to CoPilot.
| API | Description |
|---|---|
| Msg_DrawImageAtCoordinates | Request to add the Image Drawer category. It accepts the series of lat/longs, image name and category name. |
| Msg_DeleteCategory | Use to delete specific Image Drawer category. |
| Msg_DeleteAllCategory | Use to delete all user defined Image Drawer categories. |
| Msg_AddMapImageClickedHandler | Use to add a callback function to receive events when a map image drawn by Msg_DrawImageAtCoordinates is touched on the screen. |
| MsgMapImageTouchedCB | The function type of the callback function to be passed into Msg_AddMapImageClickedHandler |
CoPilot Settings Management
These APIs are used to retrieve and set different type of settings in CoPilot. These APIs are also used to retrieve acknowledgement of the message sent to CoPilot. Additionally they are also used to retrieve map data list, itinerary, eta/distance etc.
| API | Description |
|---|---|
| Msg_SendGenericData | Sends a generic data message Msg_ID_GenericData to CoPilot. It will use to set/get the settings and request some generic operation. |
| Msg_GenericDataGet | Decodes and retrieves requested information through Msg_ID_GenericData. |
| Msg_IDT_GEORESULT | Returns result for geocoding success, including error codes for destination details that have failed to geocode. To be used following Msg_SendTrip. |
| Msg_IDT_TOGGLESTOPORWAYPOINT | Use this function to toggle a stop to a waypoint and vice versa. |
| Msg_IDT_ITINCLR | CoPilot itinerary cleared. |
| Msg_IDT_MAXTYPEAHEADCHNG | Use this function in conjunction with Msg_SearchCityAndPostcode to set the number of results returned. |
| Msg_IDT_MAXTYPEAHEAD | Use this function in conjunction with Msg_SearchCity / Msg_SearchPostcode/Msg_SearchCityAndPostcode to set the number of results returned. |
| Msg_IDT_CLEARPOISEARCH | To be used in conjunction with Msg_SearchPOIEx, to clear the CoPilot cache memory. We recommend that you use Msg_ClearPOIResults. |
| Msg_IDT_CLEARADDRESSSEARCH | To be used in conjunction with Msg_SearchCityAndPostcode, to clear the CoPilot cache memory. We recommend that you use Msg_ClearSearchResults. |
| Msg_IDT_REQMAPONCE | To be used in conjunction with Msg_ID_GuidanceMap to provide the map image once. |
| Msg_IDT_ZOOM | This API enables the client application to zoom in and out of the map image. |
| Msg_IDT_RESETSPEEDVARZOOM | CoPilot in 3D mode will automatically zoom in and out of the map details based upon vehicle speed. Autozoom is currently switched on by default, until the user touches the zoom buttons, this then switches off the autozoom. Use this function to re-enable the autozoom. |
| Msg_IDT_REQDISTUNIT | Returns the current value set within CoPilot for distance measurement. |
| Msg_IDT_MUTEALERTCHNG | Sets Mute / Un-Mute value for all audio alerts within CoPilot including speech. |
| Msg_IDT_ALRTSTATUS | Retrieves the current status Mute / Un-Mute value for audio alerts within CoPilot. |
| Msg_IDT_REPEATSPOKENINST | CoPilot will play the last spoken instruction. |
| Msg_IDT_VOLUMECHNG | This will change the volume setting within CoPilot. This will also set device volume. |
| Msg_IDT_VOLUME | |
| Msg_IDT_TURNINSTRUCTIONALERT | This identifier enables CoPilot to send an event notification to the client application to provide a pre-notification of a navigational audio alert |
| Msg_IDT_VIEWMODE | Changes the current view mode within CoPilot. |
| Msg_IDT_MAPHEADINGCHNG | Changes the current heading setting within the view, north up or heading up. |
| Msg_IDT_MAPHEADING | |
| Msg_IDT_VIEWEXTENDED2DMODE | Extends the 2D view to include current or last known position and next stop within the stop list. |
| Msg_IDT_DAYNIGHTMODECHNG | Changes the setting of day and night mode within CoPilot. |
| Msg_IDT_DAYNIGHTMODE | |
| Msg_IDT_UICONTROLCHNG | Enables the client application to lock the menu within CoPilot, so that the user is not able to access menu options. Often used in conjunction with monitoring vehicle movement to enhance driver safety. To monitor vehicle movement use Msg_SendGPSPositionRequest. |
| Msg_IDT_UICONTROL | |
| Msg_IDT_SIPCONTROLCHNG | Controls the Soft Input Panel within Operating System, allows this to be removed to stop users returning to the OS. |
| Msg_IDT_SIPCONTROL | |
| Msg_IDT_GPSCHNG | Provides the ability to disable / enable GPS within CoPilot. |
| Msg_IDT_GPS | |
| Msg_IDT_REOPENGPSPORT | Re-open GPS port to be used in after Msg_SendNMEA if you want to re-use the default GPS port. |
| Msg_IDT_ROUTEFERRYAVOIDCHNG Msg_IDT_ROUTEFERRYAVOID | Ability to avoid Ferries. |
| Msg_IDT_ROUTINECOMPLETED | To be used in conjunction with Msg_ID_WindowMode, Msg_ID_ResizeCoPilot and subscribe/unsubscribe Msg_ID_GUIDANCEMAP return when the function has completed. |
| Msg_IDT_SCREENORIENTATION | Toggles the screen orientation between Portrait and Landscape |
| Msg_IDT_RELEASE_CACHEMEMORY | If the hardware requires more memory you can call this to free up all cache memory of CoPilot. |
| Msg_IDT_BACKLIGHT | Sets the backlight status. |
| Msg_IDT_TRUCKWARNING_LOOKAHEAD | Controls the setting for truck warning and alerts. |
| Msg_IDT_TRUCKWARNING | |
| Msg_IDT_UTURNCOST | Provides the ability to amend the cost associated with u-turns. |
| Msg_IDT_POIDISPLAY_OPTION | Provides the ability to display or remove POIs from the screen. |
| Msg_IDT_TRUCKALERTS_TO_SDKONLY | Use this to enable / disable truck alerts from the CoPilot application and to provide them only to the client application. |
| Msg_IDT_ERASETRIP_ONEXIT | This will ensure that all trip information is deleted each time CoPilot is exited. |
| Msg_IDT_SETMAPDRAG | CoPilot automatically moves the position to the current GPS location. To disable this and allow the user to drag the map and view other locations. It is usually required when using Msg_SetMapPan and Msg_ZoomToStop. |
| Msg_IDT_LOADPROFILE_RESULT | This message provides acknowledgement for Msg_IDT_LOADPROFILE message. Client can load the profile using Msg_SendGenericTextData with identifier (Msg_IDT_LOADPROFILE) and this message will provide acknowledgement |
| Msg_IDT_FAVORITES_SET_RESULT | This message provides acknowledgement for Msg_SetFavoritesStopInfo API. Following is the success and failure code. |
| Msg_IDT_HIDE | This message provides notification when CoPilot is hidden. This is a notification only message and will be sent by CoPilot when the user presses the hide button. |
| Msg_RequestGenericInformation | Is the first message to be used in conjunction with Msg_GenericInformation* APIs. Requests information from CoPilot, Msg_ID_GenericInformation. Used to set/get the settings and request generic operation. |
| Msg_GenericInformationParse | Decodes and retrieves the message ID from a generic information message buffer. |
| Msg_GenericInformationGetHeader | Decodes and retrieves the header information (item counts, message id etc.) from a generic information message buffer. |
| Msg_GenericInformationGetDetails | Decodes and retrieves the request specific information from a generic information message buffer. |
| Msg_IDT_MAPDATA | Returns information on the map data region. |
| Msg_IDT_COUNTRIES | Returns ID, name and ISO code for the map data countries within the region – this does not represent the installed country information. |
| Msg_IDT_STATES | Returns name and abbreviation for the map data states within the region – this does not represent the installed country information |
| Msg_IDT_POICATEGORIES | Returns ID and name for the POI categories. |
| Msg_IDT_ITINERARY | Returns information to the client application providing the itinerary of turn instructions and street names to the next destination. |
| Msg_IDT_ETADIST | Provides the complete ETA and distance for all destinations. This should be the first request for ETA and distance. For one destination or one off ETA/Dist, need to use Msg_IDT_ETADIST. |
| Msg_IDT_COMPLETE_ETADIST | Provides the ETA and distance for the next destination, and should be used for all subsequent requests for ETA and distance. We recommend using Msg_GetTurnDistances instead of Msg_IDT_COMPLETE_ETADIST. |
| Msg_IDT_LANGVOICES | Returns the ID and name for all languages and voices available. |
| Msg_IDT_CURRENT_LANGVOICE | Returns the ID and name of the current language and voice selected. |
| Msg_IDT_GEOCODE | Returns the latitude, longitude, address error, place error and stop name for successfully geocoded stops. If the destination passed has failed to geocode this will return the error code and stop name. |
| Msg_IDT_CPVERSION | Provides the CoPilot version number. |
| Msg_IDT_CPMEMORY | Returns CoPilot memory usage information. |
| Msg_IDT_POIDISPLAYLIST | Enables the ability to change the current settings for POI categories being displayed on screen to the end user. |
| Msg_CreateGenericInformation | Creates a generic message with a particular ID to be sent from client application to CoPilot to change the current settings for language, voice, lane assist and POI categories to be displayed. |
| Msg_GenericInformationAddDetail | Encodes the information and adds it to the Msg ID returned from the Msg_CreateGenericInformation. |
| Msg_IDT_SPEEDLIMIT | Enable and disable the speed limit display in CoPilot |
| Msg_IDT_CURRENT_LANGVOICE | Enables the ability to change the current language and voice set within CoPilot. |
| Msg_IDT_LANEASSIST | Enables the ability to change the current setting to show or not show the Lane Assist information. |
| Msg_IDT_SUSPEND_NAVIGATION | Suspends navigation in CoPilot. Guidance will stop and the current position will not be updated, but the GPS receiver will continue to run in the background. |
| Msg_SendGenericInformation | Sends a generic message with a particular ID to be sent from client application to CoPilot to change the current settings for language, voice, lane assist and POI categories to be displayed. |
Configuration Settings
These APIs are used to set/get the CoPilot settings stored in user.cfg. Different types of settings can be set/retrieved using one of the following APIs.
| API | Description |
|---|---|
| Msg_ConfigSetIntVal | In order to configure CoPilot settings, they are saved as a file in user.cfg – contained in the program files/copilot folder. This API is used to set the integer or boolean variables values. For Boolean use 0 or 1. |
| Msg_ConfigSetStrVal | In order to configure CoPilot settings, they are saved a file in user.cfg – contained in program files/copilot folder. This API is used to set the string variables value. |
| Msg_ConfigGetIntVal | In order to configure CoPilot settings, they are saved as a file in user.cfg – contained in program files/copilot folder. This API is used to retrieve the integer or boolean variables values. |
| Msg_ConfigGetStrVal | In order to configure CoPilot settings they are saved in a file in user.cfg – contained in program files/copilot folder. This API is used to retrieve the string variables value. |
| Msg_AddConfigCallback | This is used to add a callback to receive the messages from CoPilot when setting or getting the values using Msg_ConfigSetIntVal, Msg_ConfigSetStrVal, Msg_ConfigGetIntVal, Msg_ConfigGetStrVal |
| Msg_ConfigRspCallback | This is the definition of the callback function for receiving a response from CoPilot when using Msg_ConfigSetIntVal, Msg_ConfigSetStrVal, Msg_ConfigGetIntVal, Msg_ConfigGetStrVal |
Version Information
These APIs are used to retrieve version number of CoPilot, POI, Data and City.
| API | Description |
|---|---|
| Msg_RequestVersionInfo | This is used to request the version information from CoPilot. |
| Msg_GetVersionInfo | Decode the version information received from CoPilot in response to a Msg_RequestVersionInfo() call. The response contains version information for CoPilot, Data, City and POIs. Msg_UpdateOptions() should be used to establish a callback for message ID Msg_ID_VersionInfo in order to receive the response from CoPilot. |
GPS Position and NMEA Messages
These APIs are used to retrieve GPS position information from CoPilot. It also provides functionality to send NMEA message to CoPilot.
| API | Description |
|---|---|
| Msg_SendGPSPositionRequest | Request current position information from CoPilot. Including the current lat/long, vehicle speed and heading. |
| Msg_GPSPositionGet | Decode and retrieve the current position information from CoPilot. Including the current lat/long, vehicle speed and heading. |
| Msg_SendNMEA | Sends an NMEA-formatted message to the CoPilot application. Used to provide GPS information into CoPilot via the client application. |
Routing Profile and Routing
These APIs are used to set and retrieve the vehicle profile. These APIs are also useful to subscribe for turn distances, turn instruction, different routing events, speed limit event, country border event etc.
| API | Description |
|---|---|
| Msg_SendRoutingProfile | Deprecated |
| Msg_RequestRoutingProfile | Deprecated |
| Msg_RoutingProfileGet | Deprecated |
Truck Routing Profile
These APIs are used to set and retrieve the truck profile which includes height, width & weight of the truck, hazmat restriction, speed and avoid/favour for type of road etc.
| API | Description |
|---|---|
| Msg_SendTruckRoutingProfileEx | Deprecated |
| Msg_RequestTruckRoutingProfileEx | Deprecated |
| Msg_TruckRoutingProfileGetEx | Deprecated |
| Msg_GetTruckAlert | Truck alerts are provided to inform the drivers of hazards on the road ahead, including sharp curves, steep hills, cross winds etc. Use this to receive these alerts via the client application as it decodes truck alert message from the message buffer received through subscription of Msg_ID_TruckAlert. |
Route Calculation and On-Route Events
| API | Description |
|---|---|
| Msg_GetRoutingEvent | Provides event based routing information through subscription of Msg_ID_RoutingEvent. The routing information includes: Route Calculation Progress, destination reached event, GPS signal loss, waypoint passed, destination changed event, restricted road event. |
| Msg_IDT_ROUTECALC_START | Used to monitor when a route calculation has started. |
| Msg_IDT_ROUTECALC_PROGRESS | Monitors route calculation is in progress. |
| Msg_IDT_ROUTECALC_END | Used to monitor route calculation has finished. |
| Msg_IDT_DESTINATION_REACHED | Driver has reached their destination. |
| Msg_IDT_GPS_NOSIGNAL | CoPilot has detected that there is no GPS signal. |
| Msg_IDT_GPS_SIGNALBACK | CoPilot has detected that GPS signal has returned. |
| Msg_IDT_GPS_DETERMINING_POS | CoPilot is determining the current position. |
| Msg_IDT_TRIP_NOSTOP | There are no destinations within the CoPilot itinerary. |
| Msg_IDT_GPS_SEARCHING | CoPilot is searching for a GPS signal. |
| Msg_IDT_WAYPOINT_PASSED | One of the waypoints in CoPilot itinerary has been passed. |
| Msg_IDT_TRIP_CHANGED | CoPilot itinerary changed – used to monitor itinerary changes linked with destination passed, waypoint passed, new destination added. |
| Msg_IDT_ROUTE_RESTRICTEDDEST | Reports if the destination set is on restricted route. |
| Msg_IDT_ROUTE_RESTRICTEDROAD | Route contain restricted road. |
| Msg_IDT_ROUTE_CALCFAILED | Route calculation has failed. |
| Msg_IDT_RESTRICTED_ROAD | Restricted Road. |
| Msg_IDT_DISTUNIT_CHANGED | Distance Unit Changed |
| Msg_IDT_XMILES_NOTIFICATION | This notification is being sent when user is X miles/kms (based on the unit selected in CoPilot) away from the destination. User can configure the X distance by following of the 2 ways. |
| Msg_IDT_ROUTE_SYNC_MISMATCH | This provide notification to SDK if RouteSync provided route is not match with planned route by CoPilot. |
| Msg_IDT_ROUTE_SYNC_CALC_FINISHED | This provide notification to SDK on completion of route sync route calculation. |
| Msg_IDT_TRAFFIC_DELAY | This provides traffic delay notification in minutes if traffic is found on the route. |
| Msg_GetTurnDistances | Provides turn distance information received through a subscription to Msg_ID_TurnDist. Turn information includes next and second turn distances. |
| Msg_GetTurnInstructionsEx | Returns turn instruction information received through a subscription to Msg_ID_TurnInstructions. Information includes turn image, street information and street class information. We recommend using Msg_GetTurnInstructionsEx instead of Msg_GetTurnInstructions. |
| Msg_GetCountryBorderInfo | Decode and retrieve the country border crossing information contained in a message buffer received through a subscription to Msg_ID_CountryBorderEvent |
| Msg_GetSpeedLimitEventEx | Decode and retrieve the Over-SpeedLimit and Current- SpeedLimit information received when subscribing for Msg_ID_OverSpeedLimitEvent or Msg_ID_CurrentSpeedLimitEvent |
| Msg_ID_OverSpeedLimitEvent/Msg_ID_CurrentSpeedLimitEvent | Event alerts for current and overspeed notification |
Screen and GUI Messages
These APIs are used to control the GUI of CoPilot as well as provide shared maps functionalities. They are also used to resize CoPilot, Panning the map inside CoPilot and to customize the info bar.
| API | Description |
|---|---|
| Msg_SendWindowMode | Change the application window’s show state, including hide and topmost options. |
| Msg_ZoomToStop | CoPilot will zoom to a given location on the map. This is not added as destination, but used to mark/search an area not the current location. |
| Msg_ResizeCopilotReq | Request to resize CoPilot window after CoPilot is already launched. (V9 and Above). |
| Msg_ShowGUI | Request to show a specific page within CoPilot. This can be used to hide specific options until no other option available, for example destination entry menu. |
| Msg_IDT_MENU | Shows the Menu page. |
| Msg_IDT_HOME | Passes a new destination saved within CoPilot as the Home address. If no home address is set, it will display address entry to add Home address. |
| Msg_IDT_RECENT | Shows the Recent history of destinations entered. |
| Msg_IDT_FAVORITE | Shows the Favorite list of user destinations. |
| Msg_IDT_DESTINATION_ADDRESS | Shows the address entry wizard screens. |
| Msg_IDT_START_ROUTEDEMO | Starts a demo trip running. |
| Msg_IDT_START_ROUTINGWIZARD | Shows the Routing menu within CoPilot. |
| Msg_IDT_SHOW_ROUTINGPROFILE | Shows the routing profile menu screens within CoPilot. |
| Msg_IDT_SHOW_PLANEDITTRIP | Shows the Plan Edit Trip screens. |
| Msg_IDT_SHOW_WARNING | Displays the Legal Warning. |
| Msg_IDT_SHOWROUTE | Calculate and Show Route. |
| Msg_IDT_POI | Display the POI dialog box. |
| Msg_IDT_NOMAPDATA_WARNING | Display the No Map data warning for entered latitude/longitude. |
| Msg_IDT_STOP_ROUTEDEMO | Stop the route demo. |
| Msg_SendDevProjCoordinationReq | If the client application also contains a mapping application. this API will help to match the CoPilot location and zoom level to the inbuilt map – providing the user with smooth switching of maps. It is used to request the device projection coordination. This response is received as Msg_ID_DevProjCoordinate. The user needs to setup a callback function using Msg_UpdateCallback to receive and process the message with message id Msg_ID_DevProjCoordinate. |
| Msg_DevProjCoordinateGet | This API is used to parse the message with message id Msg_ID_DevProjCoordinate. |
Map Downloads and Updates
These APIs are used to control the map update feature in CoPilot. It allows the user to start/pause/stop new map data from the server as well allows the user to switch map data.
| API | Description |
|---|---|
| Msg_AddMapUpdateCallback | This API is used to receive the notification sent by CoPilot while processing the requests sent using the Msg_MapUpdate. The parameter is callback function of type MsgHandlerMapUpdate that will be called when the notification is received from CoPilot. The Client Application will need to write its implementation of the callback function of the type “MsgHandlerMapUpdate”. |
| MsgHandlerMapUpdate | This API is used to receive the notification sent by CoPilot while processing the requests sent using the Msg_MapUpdate. |
| Msg_MapActionRequestSpecific | This is designed to be used for the specific version map update process for CoPilot. This API can be used to download and update to a specific version(denoted by a quarter and year) of map data. |
| Msg_MapActionRequestGeneric | This is designed to be used for the specific version map update process CoPilot. This API can be used to download and update to a specific version(denoted by a quarter and year) of map data. |
| Msg_MapActionRequestDataList | This is designed to retrieve the currently installed or licensed list of maps on CoPilot |
| Msg_MapAddActionRequestCallback | This API is used to receive the notification sent by CoPilot while processing the requests sent using the Msg_MapActionRequestSpecific, Msg_MapActionRequestGeneric, or Msg_MapActionRequestDataList APIs. |
| Msg_MapAddDownloadStatusCallback | This API is used to receive the current download status generated by CoPilot while processing the download requests sent using the Msg_MapActionRequestSpecific, Msg_MapActionRequestGeneric, or Msg_MapActionRequestDataList APIs. |
Advanced Features
RouteSync
These APIs are used to work with RouteSync functionalities.
| API | Description |
|---|---|
| Msg_SendFlex | CoPilot is able to receive a route planned via a third-party application passed into CoPilot via latitude/longitude values. These locations will be used to generate the matching route /roads already planned. This is used to send a raw flex message from the SDK to CoPilot. Client Application cannot generate messages to be sent. Currently Only RouteSync Object received from PC*Miler can be used with this. |
| Msg_SetFlexCallback | This APIs used to set the callback for RouteSync message which allowed client application to monitor when and where user left the prescribed route, join the route and total out of route mileage. |
| Msg_SendManagedRouteJSON | CoPilot is able to receive managed routes using JSON. These locations will be used to generate the matching route /roads already planned, handle response events from CoPilot on a per event basis. Each event will have its own callback function. |
| Msg_ManagedRouteCallback | This APIs used to set the callback for RouteSync managed message which allowed client application to monitor when CoPilot receive the Routesync data. |
| Msg_GetPointsOffRouteSyncRoute | Provides lat/long coordinates from the input file that is not included on the route generated by CoPilot. These details are provided through subscription of Msg_ID_RouteSyncPointsOff. |
Text-To-Speech
The below APIs are used to enable CoPilot TTS voice to read strings passed into it from third party applications.
| API | Description |
|---|---|
| Text-To-Speech API | This API is used to send the request to CoPilot to speak the TTS message. For this to work, CoPilot should have TTS voices selected. |
| Msg_TTSRequestCallback | This API is used to set callback to receive notifications when requesting a TTS message to be played by CoPilot. |
| MsgFlexTTSCallback | Function definition of the callback function when setting a callback using Msg_TTSRequestCallback. |
Advanced Optimization APIs
Below are the APIs user for the advanced optimization calculations which can be made by CoPilot
| API | Description |
|---|---|
| ALK_SendRouteHeader | User can pass the route header information by using this function. This is the first function needs to call before passing the stops, this defines driver start time, start location and end location. |
| ALK_SendRouteStop | This function will pass the destination address details; including open and close window time and the onsite wait time. This function needs to be called for each destination. |
| ALK_SendRouteStopWithBlockWindowTime | This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, the blocking window open and close time. A blocking time means, do not reach this destination between these two times. For example a shop is open between 9am to 5 but closes 12pm to 1pm for lunch. |
| ALK_SendRouteStopWithSecondWindowTime | This function will pass the destination address details; including open and close window time and the onsite wait time (same as ALK_SendRouteStop), in addition, a second window open and close time. A second time window is when you provide two positive destination reached time. For example a shop is open between 9am to 12pm and 1pm to 5pm. |
| ALK_StartETACalculation | After passing route header and destination details, call this function to start the Optimization and/or ETA calculation process. |
| ALK_StopETACalculation | This call will stop the ETA calculation process at an appropriate time. |
Geofence
Below APIs are used to draw polygons and retrieve geofence events based upon drivers entering or exiting defined zones
| API | Description |
|---|---|
| Msg_ImportPolygonSet | This API is used to import Polygon Sets from an XML file. See note 2 for an example input file and note 3 for a description of the fields available for these objects. |
| Msg_DeletePolygons | This API is used to delete polygons. It can delete all polygons, a specific polygon set, or a specific polygon or polygons within a specific set. |
| Msg_SetPolygonSetProperty | This API is used to set a value of a polygon set after it has been imported. |
| Msg_SetPolygonProperty | This API is used to set a value of a polygon after it has been imported. |
| Msg_GetPolygonSetProperty | This API is used to get a value of a property of a polygon set after it has been imported. |
| Msg_GetPolygonProperty | This API is used to get a value of a property of a polygon after it has been imported. |
| Msg_GetGeofenceEventInfo | Decode and retrieve the information contained in a message buffer received through a subscription to Msg_ID_GeofenceEvent. These events occur when the users current position enters or leaves a geofence containing flags to send messages |
| Msg_GetGeofenceRoutingEventInfo | Decode and retrieve the information contained in a message buffer received through a subscription to Msg_ID_GeofenceRoutingEvent. This event is triggered when a new route is created which passes through any geofences with the “RouteThroughEvent” property set. |