Skip to main content

Routing

Contents

Msg_SetRoutingProfileJSON

This API accepts JSON input and will set the routing profile according to the attributes defined in the JSON. The following steps are the recommended way to modify a profile:

  • If the profile does not exist:

    • Add a profile, sending in the name and vehicle type
    • CoPilot will create a new profile and return the properly formatted JSON representation of the routing profile. It will return it in the callback set with Msg_SetFlexCallback
  • If the profile already exists:

    • Request the profile to get the proper JSON format, modify, and resend to CoPilot with Msg_SetRoutingProfileJSON
    • MSG_IDT_ADDROUTINGPROFILE and MSG_IDT_ROUTINGPROFILE_REQUEST for more detailed description on how to use those

For all of the matching identifiers please see Routing Profile Identifiers.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Parameters String jsonString - the routing profile in JSON format.

Return Value

ValueResult
0Indicates a general connection failure
Greater than 0Success and indicated the number of bytes sent successfully to CoPilot

Return Codes

CodeDescription
MSG_ROUTINGPROFILERESULT _SUCCESSSuccessfully modified Routing Profile
MSG_ROUTINGPROFILERESULT _PARSE_JSON_FAILJSON not formatted properly
MSG_ROUTINGPROFILERESULT _FAILED_PROFILE_NOT_FOUNDAttempted to modify a profile that was not found
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_DEFAULTCannot modify a profile named “Default”
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_TRIPOPTIONAttempted to Modify a Restricted or Invalid TripOption
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_VEHICLETYPEOnce created, the vehicle profile type for a profile cannot be modified.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_REGIONOnce created, the vehicle’s region cannot be modified.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_ROUTINGTYPE_CHANGE_NOT_ALLOWEDProfile’s routing type cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_FERRYCLOSED_CHANGE_NOT_ALLOWEDFerry Closed profile cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_TOLLAVOID_CHANGE_NOT_ALLOWEDToll Avoid profile attribute cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_TOLLCLOSED_CHANGE_NOT_ALLOWEDToll Closed profile attribute cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_HAZTYPE_NOT_SUPPORTED_FOR_VEHICLE_TYPEHazardous Material types are support for Truck Heavy Duty and Medium Duty profiles only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_INTLBORDERS_NOT_SUPPORTED_FOR_REGIONThe International Borders profile option is available in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CONGESTIONZONE_NOT_SUPPORTED_FOR_REGIONCongestion Zones are supported in Europe only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_EMISSIONZONE_NOT_SUPPORTED_FOR_REGIONEmission Zones are supported in Europe only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_NATIONALNETWORK_NOT_SUPPORTED_FOR_VEHICLE_TYPEThe National Network is supported for Truck Heavy Duty and Medium Duty profiles in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_53FTROUTING_NOT_SUPPORTED_FOR_VEHICLE_TYPE53-foot routing is supported for Truck Heavy Duty profiles in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_PROPANERESTRICTED_NOT_SUPPORTED_FOR_VEHICLE_TYPEPropane restrictions for tunnels are available for RV profiles in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_PROPANERESTRICTED_NOT_SUPPORTED_FOR_REGIONPropane restrictions for tunnels are available for RV profiles in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_ELEVATIONAVOID_NOT_SUPPORTED_FOR_VEHICLE_TYPEElevation limits are available for Truck Heavy Duty and Medium Duty profiles in North America only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_ELEVATION_ALTITUDE_LIMIT_NOT_SUPPORTED_FOR_VEHICLE_TYPEElevation limits are available for Truck Heavy Duty and Medium Duty profiles in North America only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_GOVERNOR_SPEED_NOT_SUPPORTED_FOR_VEHICLE_TYPEGovernor speed is available for Truck profiles only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_DIMENSION_CHANGE_NOT_SUPPORTED_FOR_VEHICLE_TYPEDimension settings are available for Truck profiles only.
MSG_MODIFYROUTINGPROFILERESULT _LENGTH_OUT_OF_RANGE_FOR_VEHICLE_TYPELength out of valid range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _WIDTH_OUT_OF_RANGE_FOR_VEHICLE_TYPEWidth out of valid range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _HEIGHT_OUT_OF_RANGE_FOR_VEHICLE_TYPEHeight out of valid range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _WEIGHT_OUT_OF_RANGE_FOR_VEHICLE_TYPEWeight out of range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _WEIGHT_PER_AXLE_OUT_OF_RANGE_FOR_VEHICLE_TYPEWeight per axle out of range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT_FAILED_INVALID_SIDE_OF_STREET_ADHERENCE_COSTWill be returned if attempting to set a value that is not one of the values in EStreetAdherenceCost.

Sample Code

The following code shows the steps needed to check, add, and change a Vehicle Routing Profile.

//Step 1: Check whether the profile exists
//For more information, please see: /copilot-navigation/v10-19/sdk-app/api-functions/settings/#msg_idt_routingprofile_request

//Set the callback for error
Msg.delCallback delOnGenericData = new Msg.delCallback(OnGenericData);
Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericData, true, false, delOnGenericData, Msg.callingConvention.convention_stdcall);

//Set the callback for successfully receiving a profile
Msg.delSDKDeliverCB delOnRoutingProfileResponseCB = new Msg.delSDKDeliverCB(OnRoutingProfileResponse);
Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkRoutingProfileJsonRsp"), delOnRoutingProfileResponseCB);
string strProfileName = "Custom Heavy Duty";
Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ROUTINGPROFILE_ACTION,
Msg.MSG_IDT_ROUTINGPROFILE_REQUEST,
Util.ConvertString(strProfileName),
strProfileName.Length, -1, -1, -1, false);

//Routing profile received if it already exists in CoPilot
private void OnRoutingProfileResponse(IntPtr pData, uint numBytes)
{
string sJson = Msg.MarshalNativeUTF8ToManagedString(pData);
}

//Callback will be called if profile could not be not be found
private void OnGenericData(uint pData, uint bytes)
{
int nIdentifier;
int nPayload;
Msg.Msg_GenericDataGet((uint)pData, out nIdentifier, out nPayload);
if (nIdentifier == Msg.MSG_IDT_ROUTINGPROFILEJSON_RESULT)
{
switch (nPayload)
{
case Msg.MSG_ROUTINGPROFILERESULT_FAILED_PROFILE_NOT_FOUND:
//Profile could not be found
break;
}
}
}

//Step 2: Add the routing profile
//For more information, please see: /copilot-navigation/v10-19/sdk-app/api-functions/settings/#msg_idt_addroutingprofile

//Set the callback to check the result
Msg.delCallback delOnGenericData = new Msg.delCallback(OnGenericData);
Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericData, true, false, delOnGenericData,
Msg.callingConvention.convention_stdcall);

//Set the callback to receive a routing profile if the request is successful
Msg.delSDKDeliverCB delOnRoutingProfileResponseCB = new Msg.delSDKDeliverCB(OnRoutingProfileResponse);
Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkRoutingProfileJsonRsp"),
delOnRoutingProfileResponseCB);

//Set FlexCallback to receive the newly created routing profile
string strProfileName = "Custom Heavy Duty";
Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ADDROUTINGPROFILE,
Msg.EVehicleType.VT_TruckHeavyDuty, //EVehicleType
Util.ConvertString(strProfileName),
strProfileName.Length, -1, -1, -1, false);

//Newly created routing profile successfully received.
private int OnRoutingProfileResponse(IntPtr pData, uint numBytes)
{
//JSON file for newly created profile
string strJson = Msg.MarshalNativeUTF8ToManagedString(pData);
}
//Callback will be called for success or error
private void OnGenericData(uint pData, uint bytes)
{
int nIdentifier;
int nPayload;
Msg.Msg_GenericDataGet((uint)pData, out nIdentifier, out nPayload);
if (nIdentifier == Msg.MSG_IDT_ROUTINGPROFILEJSON_RESULT)
{
switch (nPayload)
{
case Msg.MSG_ROUTINGPROFILERESULT_SUCCESS:
//Success
break;
//Rest are error codes. The following are a few examples.
case Msg.MSG_ROUTINGPROFILERESULT_FAIL:
break;
case Msg.MSG_ROUTINGPROFILERESULT_PARSE_JSON_FAIL:
break;
case Msg.MSG_ADDROUTINGPROFILERESULT_DUPLICATE_PROFILE_NAME_EXCEPTION:
break;
}
}
}

//Step 3: Change the profile received in either Step 1 or Step 2
//For more information, please see: /copilot-navigation/v10-19/sdk-app/api-functions/routing/

//Set the callback for the result
Msg.delCallback delOnGenericData = new Msg.delCallback(OnGenericData);
Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericData, true, false, delOnGenericData,
Msg.callingConvention.convention_stdcall);

//Set the routing profile
Msg.Msg_SetRoutingProfileJSON(strJsonProfile);

//Callback received for success or error
private void OnGenericData(uint pData, uint bytes)
{
int nIdentifier;
int nPayload;
Msg.Msg_GenericDataGet((uint)pData, out nIdentifier, out nPayload);
if (nIdentifier == Msg.MSG_IDT_ROUTINGPROFILEJSON_RESULT)
{
switch (nPayload)
{
case Msg.MSG_ROUTINGPROFILERESULT_SUCCESS:
break;
//Rest are error codes. The following are a few examples.
case Msg.MSG_ROUTINGPROFILERESULT_FAIL:
break;
case Msg.MSG_ROUTINGPROFILERESULT_PARSE_JSON_FAIL:
break;
case Msg.MSG_ADDROUTINGPROFILERESULT_DUPLICATE_PROFILE_NAME_EXCEPTION:
break;
}
}
}

//Step 4: Check whether or not profile is active in CoPilot
//For more information, please see: /copilot-navigation/v10-19/sdk-app/api-functions/settings/#msg_idt_requestactiveprofile

// Set FlexCallback to receive the active routing profile
Msg.delSDKDeliverCB delOnRoutingProfileResponseCB = new Msg.delSDKDeliverCB(OnRoutingProfileResponse);
Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkRoutingProfileJsonRsp"),
delOnRoutingProfileResponseCB);
Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ROUTINGPROFILE_ACTION,
Msg.MSG_IDT_REQUESTACTIVEPROFILE,
(byte[])null,
0, -1, -1, -1, false);

//Receive the active profile
private int OnRoutingProfileResponse(IntPtr pData, uint numBytes)
{
string strJson = Msg.MarshalNativeUTF8ToManagedString(pData);

//Check the JSON to see whether the routing profile name is same one as you plan to set as active
}

//Step 5: If routing profile is not active, then set profile as an active profile in CoPilot
//For more information, please see: /copilot-navigation/v10-19/sdk-app/api-functions/settings/#msg_idt_routingprofile_setasactive

//Set the callback for the result
Msg.delCallback delOnGenericData = new Msg.delCallback(OnGenericData);
Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericData, true, false, delOnGenericData,
Msg.callingConvention.convention_stdcall);
string strProfileName = "Custom Heavy Duty";
Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ROUTINGPROFILE_ACTION,
Msg.MSG_IDT_ROUTINGPROFILE_SETASACTIVE,
Util.ConvertString(strProfileName),
strProfileName.Length, -1, -1, -1,
false);
private void OnGenericData(uint pData, uint bytes)
{
int nIdentifier;
int nPayload;
Msg.Msg_GenericDataGet((uint)pData, out nIdentifier, out nPayload);
if (nIdentifier == Msg.MSG_IDT_ROUTINGPROFILEJSON_RESULT)
{
switch (nPayload)
{
case Msg.MSG_ROUTINGPROFILERESULT_SUCCESS:
//Active routing profile is set successfully
break;
//Rest are error codes. The following are a few examples.
case Msg.MSG_ROUTINGPROFILERESULT_FAIL:
//Error occurred when setting profile
break;
}
}
}

Example JSON

{
  "ProfileName": "Test1",
  "Region": "NA",
  "UserCreated": true,
  "ReadOnly": false,
  "Options": {
    "RouteType": 0,
    "VehicleType": 0,
    "HazType": 0,
    "BordersOpen": 1,
    "CongestionZonesOpen": 2,
    "LowEmissionZonesOpen": 2,
    "TollAvoid": 0,
    "NationalNetwork": 0,
    "53FootRouting": 0, //Deprecated in CoPilot 10.19.3.48. Use NationalNetwork
    "PropaneRestricted": 0,
    "Length": 0,
    "Width": 0,
    "Height": 0,
    "Weight": 0,
    "WeightPerAxle": 0,
    "TollClosed": 0,
    "FerryClosed": 0,
    "ElevationAvoid": 0,
    "ElevationAltitudeLimit": 7500,
    "GovernorSpeed": 0,
    "UltraLowEmissionZonesOpen": 2,
    "WrongSideOfStreetCostX1000": 500
  }
}

JSON Field Descriptions

  • "ProfileName" // Profile Name
  • "Region" // Region Name
  • "UserCreated" // Whether the profile is a default profile, or user created
  • "ReadOnly"
  • "Options": {
    • "RouteType" // Integer representation of RoutingType { RTE_Quickest = 0; RTE_Shortest = 1; RTEFastest = 3 (_Requires ActiveTraffic license)}
    • "VehicleType" // Integer representation of EVehicleType
    • "HazType" // Integer representation of THazType or a integer value returned by setHazmatTypeField that represents both the Hazmat Type and the EU Tunnel Code in Europe.
    • "BordersOpen" // Do (0) or do not (1, default) try to avoid border crossings
    • "CongestionZonesOpen" // {Avoid = 0, Allow = 1, Warn = 2} when route will enter a Congestion Zone. Default is Warn (2).
    • "LowEmissionZonesOpen" // {Avoid = 0, Allow = 1, Warn = 2} when route will enter a Low Emission Zone. Default is Warn (2).
    • "TollAvoid" // 1 = Route will avoid tolls if practical. (Set to 0 if using TollClosed.)
    • "NationalNetwork" // 1 = Use National Network preference for routing. Off (0) by default. (U.S. Only)
    • "53FootRouting" // 1 = // Deprecated in CoPilot 10.19.3.48. Use NationalNetwork. Off (0) by default. _(U.S. Only)
    • "PropaneRestricted" // 1 = Avoid Propane Restricted Roads. Off (0) by default. (U.S. Only)
    • "Length" // Truck Length in Hundredths of an inch
    • "Width" // Truck Height in Hundredths of an inch
    • "Height" // Truck width in Hundredths of an inch
    • "Weight" // Truck weight in tens of pounds
    • "WeightPerAxle" // Truck weight per axle in tens of pounds
    • "TollClosed" // 1 = Route will always avoid tolls (TollAvoid should = 0)
    • "FerryClosed" // 1 = Avoid Ferries
    • "ElevationAvoid" // 1 = Avoid Roads above the ElevationAltitudeLimit requires NA18Q3 or higher data
    • "ElevationAltitudeLimit" // Threshold for Elevation avoid in feet requires NA18Q3 or higher data
    • "GovernorSpeed" // Set a governor speed - 0 = off, which is the default. To apply a governor speed to ETA calculations, pass the speed in multiples of 1000. That is, to set the speed as 60 mph, you need to pass 60000 as the value.
    • "UltraLowEmissionZonesOpen" // {Avoid = 0, Allow = 1, Warn = 2} when route will enter an Ultra Low Emission Zone. Default is Warn (2).
    • "WrongSideOfStreetCostX1000"Available in CoPilot 10.14.0.325 or Higher // // Integer representation of EStreetAdherenceCost. Allows you to set the side of street adherence cost for a routing profile. Side of street adherence defines the extent to which CoPilot will try to route to the side of the street where a stop is located.

setHazmatTypeField and parseHazTypeField

To generate hazardous materials routing, the “HazType” field must be set in Msg_SetRoutingProfileJSON. That field holds an integer value that either represents the Hazmat Type for that profile or both the Hazmat Type and the EU Tunnel Code for hazardous materials routing in Europe.

setHazmatTypeField is a helper function that creates an integer value to represent both the Hazmat Type and the EU Tunnel Code. If the EU Tunnel Code is already set, you can parse the JSON to get the HazType value, and use the helper function parseHazTypeField to decode the Hazmat Type and EU Tunnel Code.

Supported SinceMinimum Operating System
CoPilot 10.9.0.1322Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h or alkmsg.java)

static unsigned long setHazmatTypeField(THazType hazType, TEUTunnelCode euTunnelCode);
static void parseHazTypeField(unsigned long ulHazType, THazType& hazType, TEUTunnelCode& euTunnelCode);
static public ulong setHazmatTypeField(THazType hazType, TEUTunnelCode euTunnelCode)
static public void parseHazTypeField(ulong ulHazType, out THazType hazType, out TEUTunnelCode euTunnelCode)
public static int setHazmatTypeField(THazType hazType, TEUTunnelCode euTunnelCode);
public static void parseHazTypeField(int ulHazType, THazType[] hazType, TEUTunnelCode[] euTunnelCode)

Parameters

THazType hazType - Hazardous Type that reflects the THazType enumerations. TEUTunnelCode euTunnel Code - Tunnel code type that reflects the TEUTunnelCode enumerations.

Return Value

The integer value that should be inserted into the RoutingProfile JSON field “HazType” to reflect the desired Hazmat Type and EU Tunnel Code pair.

Sample Code

//To create an integer value that represents an "Explosive" Hazmat Type and "CDE" Tunnel Code.

Msg.THazType hazType = HazType_Explosive;
Msg.TEUTunnelCode euTunnelCode = TEUTunnelCode.CDE;
ulong jsonHazTypeFieldValue = Msg.setHazmatTypeField(hazType, euTunnelCode);

//You would then set your JSON value of “HazType” to this value and use Msg_SetRoutingProfileJSON to set the routing profile

//This sample takes the parsed value of the HazType field from a JSON formatted Routing Profile

ulong ulHazType = Convert.ToUInt64((hazTypeFieldValue));
Msg.TEUTunnelCode euTunnelCode;
Msg.THazType hazType;
Msg.parseHazTypeField(ulHazType, out hazType, out euTunnelCode);

EStreetAdherenceCost

Enum used to set the side of street adherence cost for a routing profile with the Msg_SetRoutingProfileJSON API call.

Supported SinceMinimum Operating System
CoPilot 10.14.0.325Windows 10, Android 4.1
EnumValueDescription
Off0Will not reroute according to side of the street.
Minimal250Will increase the route by up to a maximum of 1⁄4 mile to avoid ending up on the wrong side of the street.
Moderate500Will increase the route by up to a maximum of 1/2 mile to avoid ending up on the wrong side of the street.
Average1000Will increase the route by up to a maximum of 1 mile to avoid ending up on the wrong side of the street.
Strict5000Will increase the route by up to a maximum of 5 miles to avoid ending up on the wrong side of the street.
Adhere10000Will increase the route by up to a maximum of 10 miles to avoid ending up on the wrong side of the street.
StronglyAdhere1000000Will route the driver by any possible means to reach the correct side of the street.

TEUTunnelCode

Enum used to select a EU Tunnel Code for hazmat routing in Europe.

Supported SinceMinimum Operating System
CoPilot 10.9.0.1322Windows 10, Android 4.1

Values

EnumValue
InValid-1
None0
BCDE8
CDE9
DE10
E11

THazType

Enum used to select a hazmat type for a Truck Heavy Duty or Truck Medium Duty profile.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Values

EnumValueDescription
HazType_None0
HazType_General1
HazType_Explosive2
HazType_Inhalant3
HazType_Radioactive4
HazType_Caustic5
HazType_Flammable6
HazType_Harmful2Water7

EVehicleType

Enum used to allow user to send an integer representation of a vehicle type. This is currently used in routing profiles and road speed sets

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Values

EnumValue
VT_Auto0
VT_RV2
VT_TruckHeavyDuty3
VT_Bus4
VT_Motorcycle6
VT_Bicycle7
VT_Walking8
VT_TruckLightDuty11
VT_TruckMediumDuty12

RoadSpeedSet

Object representing a set of road speeds. This object contains a region and a vehicle type, as well as individual speeds for urban / rural roads of types interstate, divided highway, primary, secondary, local, ferry and ramp.

Note: Methods exist in C# alkmsg.cs, C++, and Java simply use the structure. C# public methods are to help transition from unmanaged structure to managed C# structure

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Methods

Method NameReturn TypeDescription
RoadSpeedSet(IntPtr input)N/A - constructorAccepts an IntPtr that is the incoming unmanaged road speed set. And appropriately fills out the RoadSpeedSet managed structure that can be used by C# code.
Data()byte[]Returns a byte array that can be sent to CoPilot in the Msg.Msg_SetRoadSpeedSet api call.

Sample Code

private void OnRoadSpeedSetResponse(uint pData, uint bytes)
{
  uint uiNumSets = bytes / 260;
  IntPtr tmpRoadSpeedSetPtr = new IntPtr(pData);
  delListUpdate = new AddListItem(additem);
  if (uiNumSets > 1)
  {
    for (int i = 0; i < uiNumSets; i++)
    {
      if (i != 0)
      tmpRoadSpeedSetPtr = new IntPtr(tmpRoadSpeedSetPtr.ToInt64() + 260);
      Msg.RoadSpeedSet tmpRoadSpeedSet = new Msg.RoadSpeedSet(tmpRoadSpeedSetPtr);
      BeginInvoke(delListUpdate, new object[] { tmpRoadSpeedSet.jurisdiction });
    }
  }
  else if (uiNumSets == 1)
  {
    setRoadSpeed = new Msg.RoadSpeedSet(tmpRoadSpeedSetPtr);
    BeginInvoke(delRoadSpeedsUpdate, setRoadSpeed);
  }
  else
  {
    BeginInvoke(delStatusUpdate, "Error: Road Speed Set Request : Returned 0 Sets");
  }
}

Msg_AddRoadSpeedSetCallback

API to set a callback function that will receive the RoadSpeed set once a user calls Msg_RequestRoadSpeedSet

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Parameters void * fnProcessMsg - a pointer to the function that will receive the roadspeedset.

Return Value

ValueResult
0Indicates a general connection failure
Greater than 0Success and indicated the number of bytes sent successfully to CoPilot

Sample Code

delStatusUpdate = new StatusUpdate(statusUpdate);
  delRoadSpeedsUpdate = new SpeedTabUpdate(updateSpeedTab);
  btnRequestRoadSpeeds.Enabled = false;
  cmbVehType.SelectedIndex = 0;
  cmbSpeedSetType.SelectedIndex = 0;
  Msg.EVehicleType selectedVehicleType = ConvertVehicleTypeDropBoxIndexToVehicleType();
  int selSSTIdx = cmbSpeedSetType.SelectedIndex;
  //Version Specific Map Updates
  if (delOnRoadSpeedSetResponse == null)
  {
    delOnRoadSpeedSetResponse = new Msg.delCallback(OnRoadSpeedSetResponse);
    Msg.Msg_AddRoadSpeedSetCallback(delOnRoadSpeedSetResponse, Msg.callingConvention.convention_stdcall);
  }
  Msg.Msg_RequestRoadSpeedSet((int)selectedVehicleType, selSSTIdx, Util.ConvertString(""));

Msg_RequestRoadSpeedSet

This API requests the road speed that are currently set for a specified vehicle type, road area (Urban or Rural) and jurisdiction.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Parameters

ParameterDescription
int iVehTypeThe vehicle type to get the custom road speeds for. This field is mandatory. Passing in an invalid vehicle type of null will result in a null value being returned.
int iRoadAreaInteger representation of the RoadArea {User = 0, Default = 1}
pJurisdictionThe jurisdiction to get the custom road speeds for. Passing null or empty string will return all jurisdictions.

Return Value

ValueResult
0Indicates a general connection failure
Greater than 0Success and indicated the number of bytes sent successfully to CoPilot

Sample Code

   delStatusUpdate = new StatusUpdate(statusUpdate);
    delRoadSpeedsUpdate = new SpeedTabUpdate(updateSpeedTab);
    btnRequestRoadSpeeds.Enabled = false;
    cmbVehType.SelectedIndex = 0;
    cmbSpeedSetType.SelectedIndex = 0;
    Msg.EVehicleType selectedVehicleType = ConvertVehicleTypeDropBoxIndexToVehicleType();
    int selSSTIdx = cmbSpeedSetType.SelectedIndex;

    if (delOnRoadSpeedSetResponse == null)
     {
      delOnRoadSpeedSetResponse = new Msg.delCallback(OnRoadSpeedSetResponse);
      Msg.Msg_AddRoadSpeedSetCallback(delOnRoadSpeedSetResponse, Msg.callingConvention.convention_stdcall);
     }
    Msg.Msg_RequestRoadSpeedSet((int)selectedVehicleType, selSSTIdx, Util.ConvertString(""));```

Msg_SetRoadSpeedSet

This API allows for the setting of custom road speeds within CoPilot. Road Speeds are stored within CoPilot against each vehicle type and jurisdiction.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Return Value

ValueResult
0Indicates a general connection failure
Greater than 0Success and indicated the number of bytes sent successfully to CoPilot

Sample Code

private void btnSetRoadSpeedSet_Click(object sender, EventArgs e)
{
  Msg.Msg_SetRoadSpeedSet(setRoadSpeed.Data(), 260);
}

Msg_ResetRoadSpeedSetToDefault

Reset custom road speeds that were specified in CoPilot. By default, no custom road speeds are specified unless they were changed by the user via API. Custom road speeds can only be set via API, not the CoPilot UI from 10.9.0.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Alkmsg.h
  long Msg_ResetRoadSpeedSetToDefault(int iVehType, const char *pJurisdiction = 0);
Alkmsg.cs
  public static extern int Msg_ResetRoadSpeedSetToDefault(int ulVehType, byte[] pJurisdiction);

Parameters

int iVehType - integer representation of EVehicleType
const char *pJurisdiction - Jurisdiction to be reset, NULL indicates reset all

Return Value

ValueResult
0Indicates a general connection failure
Greater than 0Success and indicated the number of bytes sent successfully to CoPilot

Sample Code

private void btnResetJurRdSpds_Click(object sender, EventArgs e)
{
  Msg.EVehicleType selectedVehType = ConvertVehicleTypeDropBoxIndexToVehicleType();
  int selSSTIdx = cmbSpeedSetType.SelectedIndex;
  string tmpString = lstJurisdictions.Text;
  Msg.Msg_ResetRoadSpeedSetToDefault((int)selectedVehType, Util.ConvertString(lstJurisdictions.Text));
}

Msg_SendRoutingProfile

Sends an updated customized auto routing profile to CoPilot and sets it for all future trips to be run. The routing profile includes avoid and favor road categories as well as average road speeds for each road category.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_SendRoutingProfile(long lBreakMinute,
   long lBreakWaitMinute,
   long lVehicleType,
   long lRoutingType,
   unsigned short usPropaneRestr,
   unsigned short usIntBordersOpen,
   long lLondonCongZone,
   long lTollRoads,
   long lAvoidRtFrwy,
   long lSpeedFrwy,
   long lAvoidRtDivHwy,
   long lSpeedDivHwy,
   long lAvoidRtPriHwy,
   long lSpeedPriHwy,
   long lAvoidSecRd,
   long lSpeedSecRd,
   long lAvoidLclSt,
   long lSpeedLclSt,
   long lDestID = CONN_ID_NONE,
   long lSrcID = CONN_ID_NONE);

Parameters

ParameterDescription
lBreakMinuteBreak frequency (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
lBreakWaitMinuteBreak period (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
lVehicleTypeType of vehicle (VEH_Auto or VEH_RV).
lRoutingTypeType of routing (RTE_Quickest, RTE_Shortest, RTE_AvoidMajorRoads, RTE_Scenic). ‘Scenic’ and ‘avoid highways’ are not supported in CoPilot 9.2.0
usPropaneRestrPropane restriction in tunnels (1/0). Default =0 (no propane restrictions exist, all tunnels are available for use). 1= avoid tunnels with propane restrictions. Only for US and only in RV mode, not supported rest of the world.
usIntBordersOpenInternational borders open (1/0). Default=1. =1 means that the borders are open, no restriction will be placed if the route crosses a border. =0 means that borders are closed if not necessary to cross. If driving from New York to Detroit it is shorter to drive through Canada, setting =0 will ensure that the route does not leave North America.
lLondonCongZoneDisplay London Congestion Zone(CZ_Avoid, CZ_Allow, CZ_Warn)
lTollRoadsAllow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction.
lAvoidRtFrwyLevel of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedFrwySpeed limit of freeways (in miles/hr.). Recommended range is 50-80.
lAvoidRtDivHwyLevel of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedDivHwySpeed limit of divided highways (in miles/hr.). Recommended range is 30-60.
lAvoidRtPriHwyLevel of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedPriHwySpeed limit of primary highways (in miles/hr.). Recommended range is 20-50.
lAvoidSecRdLevel of avoiding/favoring secondary roads (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedSecRdSpeed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
lAvoidLclStLevel of avoiding/favoring local streets (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedLclStSpeed limit of local streets (in miles/hr.). Recommended range is 10-40.
lDestIDDestination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lSrcIDUnique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Note: The profile gets saved in the “Save” folder as a flat file. The file names are “ALKAuto_trip.dat” and “ALKAuto_stop.dat” for routing profiles for the vehicle type of VEH_Auto, and “ALKRV_trip.dat” and “ALKRV_stop.dat” for the vehicle type of VEH_RV.

Enums

enum VehicleType { VEH_Auto = 0, VEH_RV };
enum RoutingType {
  RTE_Quickest = 0,
  RTE_Shortest,
  RTE_AvoidMajorRoads,
  RTE_Scenic
};
enum TCZOpts { CZ_Avoid = 0, CZ_Allow, CZ_Warn };
enum TollRoads {
  TR_AlwaysAvoid = 0,
  TR_IfNecessary,
  TR_NoRestriction
};
enum AvoidRouting {
  AV_StrongAvoid = 0,
  AV_Avoid,
  AV_Neutral,
  AV_Favor,
  AV_StrongFavor
};

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

Msg_RequestRoutingProfile

Requests the information on a current routing profile. The routing profile includes avoid and favor road categories as well as average road speeds for each road category.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_RequestRoutingProfile(long lDestID = CONN_ID_NONE,
                               long lSrcID = CONN_ID_NONE););

Parameters

ParameterDescription
lDestIDDestination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lSrcIDUnique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

  • Less than 0 = Failed to send message to CoPilot
  • 0 = Unable to send message as SDK didn’t find connections
  • Greater than 0 = Successful

Msg_RoutingProfileGet

Retrieves and decodes routing information from Msg_ID_RoutingProfile message. To be used in conjunction with Msg_RequestRoutingProfile. The routing profile includes avoid and favor road categories as well as average road speeds for each road category.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_RoutingProfileGet(void *pBuffer,
                           long &rBreakMinute,
                           long &rBreakWaitMinute,
                           long &rVehicleType,
                           long &rRoutingType,
                           unsigned short &usPropanRestr,
                           unsigned short &usIntBordersOpen,
                           long &rLondonCongZone,
                           long &rTollRoads,
                           long &rAvoidRtFrwy,
                           long &rSpeedFrwy,
                           long &rAvoidRtDivHwy,
                           long &rSpeedDivHwy,
                           long &rAvoidRtPriHwy,
                           long &rSpeedPriHwy,
                           long &rAvoidSecRd,
                           long &rSpeedSecRd,
                           long &rAvoidLclSt,
                           long &rSpeedLclSt);

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
rBreakMinuteBreak frequency (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
rBreakWaitMinuteBreak period (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
rVehicleTypeType of vehicle (VEH_Auto or VEH_RV).
rRoutingTypeType of routing (RTE_Quickest, RTE_Shortest, RTE_AvoidMajorRoads, RTE_Scenic). ‘Scenic’ and ‘avoid highways’ are not supported in CoPilot 9.2.0
usPropaneRestrPropane restriction in tunnels (1/0). Default =0 (no propane restrictions exist, all tunnels are available for use). 1= avoid tunnels with propane restrictions. Only for US and only in RV mode, not supported rest of the world.
usIntBordersOpenInternational borders open (1/0). Default=1. =1 means that the borders are open, no restriction will be placed if the route crosses a border. =0 means that borders are closed if not necessary to cross. If driving from New York to Detroit it is shorter to drive through Canada, setting =0 will ensure that the route does not leave North America.
rLondonCongZoneLondon Congestion Zone (CZ_Avoid, CZ_Allow, CZ_Warn).
rTollRoadsAllow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction).
rAvoidRtFrwyLevel of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedFrwySpeed limit of freeways (in miles/hr.). Recommended range is 50-80.
rAvoidRtDivHwyLevel of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedDivHwySpeed limit of divided highways (in miles/hr.). Recommended range is 30-60.
rAvoidRtPriHwyLevel of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedPriHwySpeed limit of primary highways (in miles/hr.). Recommended range is 20-50.
rAvoidSecRdLevel of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedSecRdSpeed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
rAvoidLclStLevel of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedLclStSpeed limit of local streets (in miles/hr.). Recommended range is 10-40.

Return Value

  • 0 - Invalid buffer pointer
  • 1 - Successful

lIdentifier

#define Msg_ID_RoutingProfile 0xf1000285

Enums

enum VehicleType { VEH_Auto = 0, VEH_RV };
enum RoutingType {
  RTE_Quickest = 0,
  RTE_Shortest,
  RTE_AvoidMajorRoads,
  RTE_Scenic
};

enum TCZOpts { CZ_Avoid = 0, CZ_Allow, CZ_Warn };
enum TollRoads {
  TR_AlwaysAvoid = 0,
  TR_IfNecessary,
  TR_NoRestriction
};

enum AvoidRouting {
  AV_StrongAvoid = 0,
  AV_Avoid,
  AV_Neutral,
  AV_Favor,
  AV_StrongFavor
};

Msg_SendTruckRoutingProfileEx

Sends a customized truck routing profile to CoPilot and sets it for all future trips to be run. It is used to provide vehicle heights, weights, widths etc, as well as Hazmat materials. Also average road speeds and avoid / favor road categories can be set.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_SendTruckRoutingProfileEx(long lBreakMinute,
   long lBreakWaitMinute,
   long lRoutingType,
   long usIntBordersOpen,
   long lTollRoads,
   unsigned short usOvrdTruckRestr,
   unsigned short usNatlNetwork,
   unsigned short us53ftTrailer,
   unsigned short usHazmatRt,
   long lHazType,
   long lAvoidRtFrwy,
   long lSpeedFrwy,
   long lAvoidRtDivHwy,
   long lSpeedDivHwy,
   long lAvoidRtPriHwy,
   long lSpeedPriHwy,
   long lAvoidSecRd,
   long lSpeedSecRd,
   long lAvoidLclSt,
   long lSpeedLclSt,
   long lLengthRestr,
   long lWidthRestr,
   long lHeightRestr,
   long lWeightRestr,
   long lWeightPerAxleRestr,
   long lLondonCongZone,
   long lLowEmissionZone,
   long lDestID = CONN_ID_NONE,
   long lSrcID = CONN_ID_NONE);

Parameters

ParameterDescription
lBreakMinute*:*Break frequency (in minutes).
lBreakWaitMinuteBreak period (in minutes).
lRoutingTypeType of routing (RTE_Practical, RTE_Shortest).
usIntBordersOpenInternational borders open (1/0). US only. For all other regions pass 1.
lTollRoadsAllow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction).
usOvrdTruckRestrOverride truck restrictions (1/0). To disable use 0. By passing 1 all truck restrictions will be overridden and ignored when generating a route. Note this parameter will not be processed in CoPilot V10 onwards
usNatlNetworkNational network (1/0). US only. For all other regions pass 1.
us53ftTrailerTruck is a 53’ trailer (1/0). US only. For all other regions pass 1.
usHazmatRtUse Hazmat restriction (1/0).
lHazTypeHazmat type(HazType_None = 0, HazType_General, HazType_Explosive, HazType_Inhalant, HazType_Radioactive, HazType_Caustic, HazType_Flammable, HazType_Harmful2Water)
lAvoidRtFrwyLevel of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedFrwySpeed limit of freeways (in miles/hr.). Recommended range is 50-80.
lAvoidRtDivHwyLevel of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedDivHwySpeed limit of divided highways (in miles/hr.). Recommended range is 30-60.
lAvoidRtPriHwyLevel of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedPriHwySpeed limit of primary highways (in miles/hr.). Recommended range is 20-50.
lAvoidSecRdLevel of avoiding/favoring secondary roads (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedSecRdSpeed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
lAvoidLclStLevel of avoiding/favoring local streets (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedLclStSpeed limit of local streets (in miles/hr.). Recommended range is 10-40.
lLengthRestrTruck length restriction used in multiples of tens of inches.
lWidthRestrTruck width restriction used in multiples of tens of inches.
lHeightRestrTruck height restriction used in multiples of tens of inches.
lWeightRestrTruck weight restriction used in tenths of Pounds.
lWeightPerAxleRestrTruck weight restriction used in tenths of Pounds
lLondonCongZoneLondon Congestion Zone (Only applicable for UK data) (Supported only in 960+)
lLowEmissionZoneLow Emission Zone. (Only applicable for UK data) (Supported only in 960+)
lDestIDDestination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lSrcIDUnique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

All parameters is same as Msg_SendRoutingProfile. Msg_SendTruckRoutingProfileEx adds these three parameters

  • lWeightPerAxleRestr
  • lLondonCongZone,
  • lLowEmissionZone

Note: The WeightPerAxle values can be converted via the helper function which are included in demo.cs.

For CoPilotV9 ‘Scenic’ and ‘avoid highways’ are not supported.

Test Data:

For a truck length of 16.5m (approx. 649 inches), our input for lLengthRestr is 6490 (649 * 10). The same logic applies for lHeightRestr and lWidthRestr.

For a truck length of 40ft (approx. 480 inches), our input for lLengthRestr is 4800 (480 * 10). The same logic applies for lHeightRestr and lWidthRestr.

For a truck weight of 8 tonnes (approx. 17640 lbs), our input for lWeightRestr is 1764 (17640 / 10). The same logic applies for lWeightPerAxleRestr.

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

Msg_RequestTruckRoutingProfileEx

Requests the current customized truck routing profile from CoPilot. To request vehicle heights, weights, widths etc, as well as Hazmat materials. Also average road speeds and avoid / favor road categories can be retrieved. Needs to be followed by Msg_TruckRoutingProfileGetEx to retrieve the responses.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_RequestTruckRoutingProfileEx(long lDestID = CONN_ID_NONE,
                                      long lSrcID = CONN_ID_NONE);

Parameters

Same as Msg_RequestTruckRoutingProfile

ParameterDescription
lDestIDDestination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lSrcIDUnique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

  • Less than 0 = Failed to send message to the CoPilot.
  • 0 = Unable to send message as SDK didn’t find connection.
  • Greater than 0 = Successful

Msg_TruckRoutingProfileGetEx

Following Msg_RequestTruckRoutingProfileEx retrieves and decodes routing information from Msg_ID_TruckRoutingProfile message.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_TruckRoutingProfileGetEx(void *pBuffer,
   long &rBreakMinute,
   long rBreakWaitMinute,
   long &rRoutingType,
   long &rIntBordersOpen,
   long &rTollRoads,
   unsigned short &usOvrdTruckRestr,
   unsigned short &usNatlNetwork,
   unsigned short &us53ftTrailer,
   unsigned short &usHazmatRt,
   long &rHazType,
   long &rAvoidRtFrwy,
   long &rSpeedFrwy,
   long &rAvoidRtDivHwy,
   long &rSpeedDivHwy,
   long &rAvoidRtPriHwy,
   long &rSpeedPriHwy,
   long &rAvoidSecRd,
   long &rSpeedSecRd,
   long &rAvoidLclSt,
   long &rSpeedLclSt,
   long &rLengthRestr,
   long &rWidthRestr,
   long &rHeightRestr,
   long &WeightRestr,
   long &lWeightPerAxleRestr,
   long &lLondonCongZone,
   long &lLowEmissionZone);

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
rBreakMinuteBreak frequency (in minutes).
rBreakWaitMinuteBreak period (in minutes).
rRoutingTypeType of routing (RTE_Practical, RTE_Shortest).
rIntBordersOpenInternational borders open (1/0).
rTollRoadsAllow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction).
usOvrdTruckRestrOverride truck restrictions (1/0). Note: this parameter will not be processed in CoPilot V10 onwards
usNatlNetworkNational network (1/0).
us53ftTrailerTruck is a 53’ trailer (1/0).
usHazmatRtUse Hazmat restriction (1/0).
rHazTypeHazmat type(HT_None = 0, HT_General, HT_Explosives, HT_Inhalants, HT_Radioactive, HT_Caustic, HT_Flammable)
rAvoidRtFrwyLevel of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedFrwySpeed limit of freeways (in miles/hr.). Recommended range is 50-80.
rAvoidRtDivHwyLevel of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedDivHwySpeed limit of divided highways (in miles/hr.). Recommended range is 30-60.
rAvoidRtPriHwyLevel of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedPriHwySpeed limit of primary highways (in miles/hr.). Recommended range is 20-50.
rAvoidSecRdLevel of avoiding/favoring secondary roads (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedSecRdSpeed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
rAvoidLclStLevel of avoiding/favoring local streets (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedLclStSpeed limit of local streets (in miles/hr.). Recommended range is 10-40.
rLengthRestrTruck length restriction used in multiples of tens of inches.
rWidthRestrTruck width restriction used in multiples of tens of inches.
rHeightRestrTruck height restriction used in multiples of tens of inches.
rWeightRestrTruck weight restriction used in tenths of Pounds.
lWeightPerAxleRestrTruck weight restriction used in tenths of Pounds
lLondonCongZoneLondon Congestion Zone (Only applicable for UK data) (Supported only in 960+)
lLowEmissionZoneLow Emission Zone. (Only applicable for UK data) (Supported only in 960+)

All parameters is same as Msg_SendRoutingProfile except the following

  • lWeightPerAxleRestr:

  • lLondonCongZone,

  • lLowEmissionZone

Return Value

  • 0 Invalid buffer pointer

  • 1 Successful

lIdentifier

#define Msg_ID_TruckRoutingProfileEx 0xf1000213

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.

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetTruckAlert (void *pBuffer,
                        unsigned long lBufLen,
                        unsigned long &rAlertType,
                        unsigned long &rAlertDistance);

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pBufLenBuffer length
pAlertTypeAny of the predefined warning type. Please see the description below. If it returns the other alert type then please ignore it.
pAlertDistanceDistance from the given alert type. Yards – If user setting is Miles, Meters if user setting is Km in CoPilot.

Return Value

  • 0 - Buffer is not intended for Msg_ID_TruckAlert

  • 1 - Successful

lIdentifier

#define Msg_ID_TruckAlert                              0xF100032E
#define TypeID_NoTruckOvertaking                       0
#define TypeID_Legal_RDM_No_UTurn                      1990
#define TypeID_Legal_RDM_No_Left                       1988
#define TypeID_Legal_RDM_No_Right                      1989
#define TypeID_Protected_Overtaking_ExtraLane          1992
#define TypeID_Protected_Overtaking_ExtraLaneRightSide 1993
#define TypeID_Protected_Overtaking_ExtraLaneLeftSide  1994
#define TypeID_RoadNarrows                             1987
#define TypeID_SharpCurveLeft                          1977
#define TypeID_SharpCurveRight                         1978
#define TypeID_SteepHillUpwards                        1982
#define TypeID_SteepHillDownwards                      1981
#define TypeID_LateralWind                             1985
#define TypeID_RiskOfGrounding                         1983
#define TypeID_TreeOverhang                            1986
#define TypeID_TruckPetrolStation                      1979
#define TypeID_TruckRestaurant                         1991

(The following alerts are available in Europe Only)

Alert TypeDescriptionImage
0No OvertakingNo Overtaking icon
1990No UTurnNo UTurn icon
1992Protected Overtaking ExtraLaneProtected Overtaking ExtraLane icon
1993Protected Overtaking ExtraLaneRightProtected Overtaking ExtraLaneRight icon
1994Protected Overtaking ExtraLaneLeftProtected Overtaking ExtraLaneLeft icon
1995Lane Merge RightLane Merge Right icon
1996Lane Merge LeftLane Merge Left icon
1997Lane Merge CenterLane Merge Center icon
1998Railway Crossing ProtectedRailway Crossing Protected icon
1999Railway Crossing UnprotectedRailway Crossing Unprotected icon
1987Road NarrowsRoad Narrows icon
1988No Left TurnNo Left Turn icon
1989No Right TurnNo Right Turn icon
1978Sharp Curve LeftSharp Curve Left icon
1977Sharp Curve RightSharp Curve Right icon
1982SteepHill UpwardsSteepHill Upwards icon
1981SteepHill DownwardsSteepHill Downwards icon
1985Lateral WindLateral Wind icon
1983Risk Of GroundingRisk Of Grounding icon
1980Accident HazardAccident Hazard icon
1986Tree OverhangTree Overhang icon
1979Truck Petrol StationTruck Petrol Station icon

Note

Following configuration file is used to enable/disable truck alert:

copilot user.cfg

[TruckWarnings]
“Enabled”= 1/0

  • If 1, it will display Truck alert in CoPilot. If Msg_ID_TruckAlerts are subscribed then it will provide real-time truck alerts to the SDK.

  • If 0, it will not display Truck alert in CoPilot. Subscription of Msg_ID_TruckAlerts will not be available.

“TruckAlertsToSDKOnly”=1/0

  • If 1, it will not display Truck alert in CoPilot.

  • If 0, it will display Truck alert in CoPilot assumed that “Enabled” flag is 1.

Example

Msg_Subscribe(MSG_ID_TruckAlert);

Msg_UpdateOptions (MSG_ID_TruckAlert, true, false, TruckAlertCallback);

// Receiving side either by callback or through message queue mechanism
void TruckAlertCallback (const char *pBuf,const unsigned long lBufLen) {
  long lAlertType;
  long lAlertDistance
  Msg_GetTruckAlert(pBuf, lBuflen, lAlertType, lAlertDistance);
}

Note: lAlertDistance is in yards or meters (depending on user settings miles or km). If no alerts are received from CoPilot, the client application should clear the last alert displayed in 3.5 seconds. Please see sample application for implementation of TruckAlert.

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.

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Note: Routing events are divided into different categories to allow the client application to control the notifications that are received. By default the config values for GPSRoutingEvent and TripRoutingEvent are set to = 0 and disabled. By default Restricted RoutingEvents is enabled and set to 1. The default config settings may differ depending on the version of CoPilot that you are running. A breakdown is provided below of the link between the identifiers and the config setting.

To enable the messages, each of the config values noted below should be set to = 1.

> [SDK] <br>
> "GPSRoutingEvent" = 0/1
  • MSG_IDT_GPS_NOSIGNAL
  • MSG_IDT_GPS_SEARCHING
  • MSG_IDT_GPS_DETERMINING_POS
  • MSG_IDT_GPS_SIGNALBACK
> [SDK] <br>
> "TripRoutingEvent"=0/1
  • MSG_IDT_ROUTECALC_START

  • MSG_IDT_ROUTECALC_PROGRESS

  • MSG_IDT_ROUTECALC_END

  • MSG_IDT_ROUTE_CALCFAILED

  • MSG_IDT_ALTERNATE_ROUTECALC_START

  • MSG_IDT_ALTERNATE_ROUTECALC_END

  • MSG_IDT_DESTINATION_REACHED

  • MSG_IDT_WAYPOINT_PASSED

  • MSG_IDT_TRIP_NOSTOP

  • MSG_IDT_TRIP_CHANGED

  • MSG_IDT_DISTUNIT_CHANGED

  • MSG_IDT_ROUTE_SYNC_MISMATCH

  • MSG_IDT_ROUTE_SYNC_CALC_FINISHED

  • MSG_ID_ROUTESYNCPOINTSOFF

  • MSG_IDT_TRAFFIC_DELAY

[SDK]
“RestrictedRoutingEvent” = 0/1

  • MSG_IDT_ROUTE_RESTRICTEDROAD
  • MSG_IDT_ROUTE_RESTRICTEDDEST
  • MSG_IDT_RESTRICTED_ROAD

Syntax (Prototyped in alkmsg.h)

long Msg_GetRoutingEvent (void *pBuffer,
   unsigned long lBufLen,
   unsigned long &rEventType,
   long &rPayload);

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pBufLenBuffer length
rEventTypeAny of the predefined event. Please see the description below.
rPayloadIf any information attached with event otherwise unused

Return Value

  • 0 Buffer is not intended for Msg_ID_RoutingEvent.
  • 1 Successful

lIdentifier

#define Msg_ID_RoutingEvent 0xf1000126

Msg_IDT_ROUTECALC_START

Route calculation started.

#define Msg_IDT_ROUTECALC_START 0x0001L

Msg_IDT_ROUTECALC_PROGRESS

Route calculation is in progress.

#define Msg_IDT_ROUTECALC_PROGRESS 0x0002L

Msg_IDT_ROUTECALC_END

Route calculation finished.

#define Msg_IDT_ROUTECALC_END 0x0003L

Msg_IDT_DESTINATION_REACHED

User reached to destination.

#define Msg_IDT_DESTINATION_REACHED 0x0004L

Msg_IDT_GPS_NOSIGNAL

CoPilot detected that there is no GPS signal.

#define Msg_IDT_GPS_NOSIGNAL 0x0005L

Msg_IDT_GPS_SIGNALBACK

CoPilot detected that GPS signal is back.

#define Msg_IDT_GPS_SIGNALBACK 0x0006L

Msg_IDT_GPS_DETERMINING_POS

CoPilot is determining current position.

#define Msg_IDT_GPS_DETERMINING_POS 0x0007L

Msg_IDT_TRIP_NOSTOP

No stop in the CoPilot itinerary.

#define Msg_IDT_TRIP_NOSTOP 0x0008L

Msg_IDT_GPS_SEARCHING

CoPilot is searching for a GPS signal.

#define Msg_IDT_GPS_SEARCHING 0x0009L

Msg_IDT_WAYPOINT_PASSED

One of the waypoints in CoPilot itinerary has been passed.

#define Msg_IDT_WAYPOINT_PASSED 0x000AL

Msg_IDT_TRIP_CHANGED

CoPilot itinerary changed.

#define Msg_IDT_TRIP_CHANGED 0x000BL

Msg_IDT_ROUTE_RESTRICTEDDEST

Destination is on a restricted route.

#define Msg_IDT_ROUTE_RESTRICTEDDEST 0x000DL

Msg_IDT_ROUTE_RESTRICTEDROAD

Route contains restricted road.

#define Msg_IDT_ROUTE_RESTRICTEDROAD 0x000EL

Msg_IDT_ROUTE_CALCFAILED

Route calculation is failed.

#define Msg_IDT_ROUTE_CALCFAILED 0x000FL

Msg_IDT_RESTRICTED_ROAD

Restricted road.

#define Msg_IDT_RESTRICTED_ROAD 0x0010L

Msg_IDT_DISTUNIT_CHANGED

Distance Unit changed.

#define Msg_IDT_DISTUNIT_CHANGED 0x0011L

Msg_IDT_XMILES_NOTIFICATION

#define Msg_IDT_XMILES_NOTIFICATION 0x0012L

This notification is being sent when user is X miles/kms (based on the unit selected in CoPilot) away from the destination. The user can configure the X distance in 2 ways:

User.cfg (Static way to change the distance notification settings)

[SDK] “NotificationXDist” = 2

By using above settings, CoPilot will provide Msg_IDT_XMILES_NOTIFICATION, once user is 0.2 miles/kms away from the destination.

Using API (Dynamic way to change the distance notification settings)

The user can use Msg_ConfigSetIntVal to set the NotificationXDist settings in CoPilot.

E.g. Msg_ConfigSetIntVal (“SDK”," NotificationXDist “, 20)

By using the above settings, CoPilot will provide Msg_IDT_XMILES_NOTIFICATION, once user is 2 miles/kms away from destination.

Additional Notes

  • Value of the NotificationXDist is always in multiplication of 10. If the user wants to have notification at 0.2 miles/kms from the destination, the user needs to pass 2.

  • User can change the notification value at any time. E.g. initially the user sets the notification at 2 mile by using Msg_ConfigSetIntVal (passing 20). The user gets the notification when user is 2 miles away from destination. Now the user wants to have another notification at 0.3 miles. This notification can be set again by using the Msg_ConfigSetIntVal by passing 3.

  • Once the value is set, it will be applied for all the destinations. If notification is not required then the user can unsubscribe the routing event or set the value as 0.

  • The user can get the notification once for a given value.e.g.

    • If the user sets the notification at 0.3 miles and gets the notification at 0.3 mile.
    • If the user is off route before reaching the destination and travelling away from destination.
    • When user is back again within 0.3 mile to destination. CoPilot will not send notification as it is already being sent.

Msg_IDT_ROUTE_SYNC_MISMATCH

This notification is being sent if RouteSync provided route is not match with planned route by CoPilot.

#define Msg_IDT_ROUTE_SYNC_MISMATCH 0x0013L

Msg_IDT_ROUTE_SYNC_CALC_FINISHED

This notification is being sent on completion of route sync route calculation.

#define Msg_IDT_ROUTE_SYNC_CALC_FINISHED 0x0015L

Msg_IDT_TRAFFIC_DELAY

This notification is being sent if active traffic is enabled. lPayload contain delay in number of minutes in ETA.

This notification is used with traffic bar and active traffic settings on the CoPilot. This notification is being sent whenever traffic bar is being refresh.

#define Msg_IDT_TRAFFIC_DELAY 0x0014L

Example

Msg_Subscribe(MSG_ID_RoutingEvents):
Msg_UpdateOptions(MSG_ID_RoutingEvents, true, false, MyRoutingEventsCallback);

//Receiving side either by callback or through message queue mechanism
void MyRoutingEventCallback(const char *pBuf, const unsigned long lBufLen) {
  long lRoutingEvent, lPayload;
  Msg_GetRoutingEvent(pBuf, lBufLen, lRoutingEvent, lPayload);
}

Notes

  • Above messages are divided into different categories to allow the client application to control what it wants to receive. By default the values in CoPilot user.cfg = 0, as per the example below, as a result the messages will be disabled. To enable the messages the config values should = 1.
User.cfg ValuesMESSAGES DISABLED
[SDK]
"RestrictedRoutingEvent"=0
Msg_IDT_ROUTE_RESTRICTEDROAD
Msg_IDT_ROUTE_RESTRICTEDDEST
Msg_IDT_RESTRICTED_ROAD
[SDK]
"TripRoutingEvent"=0
Msg_IDT_ROUTE_SYNC_MISMATCH
Msg_IDT_ROUTE_SYNC_CALC_FINISHED
Msg_IDT_TRAFFIC_DELAY Msg_ID_ROUTESYNCPOINTSOFF

Please note that configurations can be different in different version of CoPilot

  • rPayload is used with Msg_IDT_ROUTECALC_PROGRESS and Msg_IDT_DISTUNIT_CHANGED
  • rPayload when used with Msg_IDT_ROUTECALC_PROGRESS, it is used to show the percentage progress in route calculation.
  • rPayload when used with Msg_IDT_DISTUNIT_CHANGED, indicates when the unit is changed to English (rPayload = 1) or Metric (rPayload = 0).
  • rPayload in Msg_IDT_TRAFFIC_DELAY indicates the number of mins of delay due to traffic in current route.

Msg_GetTurnDistances

Provides turn distance information received through a subscription to Msg_ID_TurnDist. Turn information includes next and second turn distances.

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetTurnDistances(const char *pBuf, const long lBufLen,
    double &dNextTurnDist,
    double &dSecondTurnDist,
    double &dDestDist, double &dAirDist,
    double &dETA);

Parameters

ParameterDescription
pBufThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLenThe size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
dNextTurnDistThe distance in miles or kilometers (depending on user settings) to the next turn.
dSecondTurnDistThe distance in miles or kilometers (depending on user settings) to the second turn (the turn after the next turn).
dDestDistThe distance in miles or kilometers (depending on user settings) to the destination along the chosen route.
dAirDistThe distance in miles or kilometers (depending on user settings) to the destination along an imaginary straight line (“as the crow flies”).
dETAThe estimated remaining trip time in hours. If ETA difference is 15 minutes it returns 0.25 i.e (15/60)

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

Msg_GetTurnInstructions

Returns turn instruction information received through a subscription to Msg_ID_TurnInstructions. Information includes turn image, street information. We recommend using Msg_GetTurnInstructionsEx instead of Msg_GetTurnInstructions.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.4.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetTurnInstructions(const char *pBuf,
   const long lBufLen,
   char *pszNextTurn,
   long lNextTurnLen,
   char *pszSecondTurn,
   long lSecondTurnLen,
   char *pszCurrentStreet,
   long lCurrentStreetLen,
   char *pszTurnStreet,
   long lTurnStreetLen,
   char *pszTurnAction,
   long lTurnActionLen,
   shor &lTurnImage);

Parameters

ParameterDescription
pBufThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLenThe size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pszNextTurnA user-allocated buffer into which text describing the next turn will be copied.
lNextTurnLenThe size, in bytes, of the user-allocated buffer dereference by pszNextTurn.
pszSecondTurnA user-allocated buffer into which text describing the second turns (turn after next turn) will be copied.
lSecondTurnLenThe size, in bytes, of the user-allocated buffer dereference by pszSecondTurn.
pszCurrentStreetA user-allocated buffer into which the name of the current street will be copied.
lCurrentStreetLenThe size, in bytes, of the user-allocated buffer dereference by pszCurrentStreet.
pszTurnStreetA user-allocated buffer into which the name of the next street onto which the user should turn will be copied.
lTurnStreetLenThe size, in bytes, of the user-allocated buffer dereference by pszTurnStreet.
pszTurnActionA user-allocated buffer into which the name of the next action that the user should take will be copied.
lTurnActionLenThe size, in bytes, of the user-allocated buffer dereference by pszTurnAction.
lTurnImageThe index of the turn image represented by pszTurnAction. This index can be used to select an appropriate “turn arrow” image for display in the user application.

Table: Turn image codes retrieved using Msg_GetTurnInstructions()

Turn Image Code (Right Drive)Turn Image Code (Left Drive)DescriptionImage
-1-1No Next Turn
032Straighticon28
133Left (90 degrees)icon29
234Right (90 degrees)icon30
335Bear Lefticon31
436Bear Righticon32
537Sharp Lefticon33
638Sharp Righticon34
739Left U-turnicon35
840Blankicon37
99No GPS signal (image of satellite)icon38
1010Final Destination (checkered flag)icon39
1648Straight through traffic circleicon40
1749Left through traffic circle (270degrees CCW)icon42
1850Right through traffic circle (90 degrees CCW)icon44
1951Bear Left through traffic circleicon46
2052Bear Right through traffic circleicon48
2153Sharp Left through traffic circleicon50
2254Sharp Right through traffic circleicon52
2355U-Turn through traffic circle (180 degrees CCW)icon54
6799Merge Righticon56
68100Merge Lefticon57
>128>128Exit from the highway/Motorwayicon58

Note: For determining whether the Exit code is related to left hand drive or right hand drive, please subtract 128 from the returned code. This result should match one of the unique numbers on Left Drive or Right Drive. For Example- Returned Turn Image Code is 130. Subtracting 128 from it will return 2. Now two matches Right Exit (in Right Hand Drive). So it is right hand drive.

Return Value

Always returns 1

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.

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetTurnInstructionsEx(const char *pBuf,
                               const long lBufLen,
                               char *pszNextTurn,
                               long lNextTurnLen,
                               char *pszSecondTurn,
                               long lSecondTurnLen,
                               char *pszCurrentStreet,
                               long lCurrentStreetLen,
                               char *pszTurnStreet,
                               long lTurnStreetLen,
                               char *pszTurnAction,
                               long lTurnActionLen,
                               short &lTurnImage,
                               short &lCurrentStreetClass,
                               short &lCurrentStreetRoadSpeed,
                               short &lSecondTurnImage,
                               short &lIsTruckSpeedLimit);

Parameters

ParameterDescription
pBufThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLenThe size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions ().
pszNextTurnA user-allocated buffer into which text describing the next turn will be copied.
lNextTurnLenThe size, in bytes, of the user-allocated buffer dereference by pszNextTurn.
pszSecondTurnA user-allocated buffer into which text describing the second turn (turn after next turn) will be copied.
lSecondTurnLenThe size, in bytes, of the user-allocated buffer dereference by pszSecondTurn.
pszCurrentStreetA user-allocated buffer into which the name of the current street will be copied.
lCurrentStreetLenThe size, in bytes, of the user-allocated buffer dereference by pszCurrentStreet.
pszTurnStreetA user-allocated buffer into which the name of the next street onto which the user should turn will be copied.
lTurnStreetLenThe size, in bytes, of the user-allocated buffer dereference by pszTurnStreet.
pszTurnActionA user-allocated buffer into which the name of the next action that the user should take will be copied.
lTurnActionLenThe size, in bytes, of the user-allocated buffer dereference by pszTurnAction.
lTurnImageThe index of the turn image represented by pszTurnAction. This index can be used to select an appropriate “turn arrow” image for display in the user application.
lCurrentStreetClassIt contain the class of the current street. For exact type of class please refer TRoadClass enum.
lCurrentStreetRoadSpeedIt contain the speed limit of the current road. If data does not contain the speed limited then it will return 0. For unlimited speed (Example Germany) value returned is -1. (this is always in miles/hr irrespective of units set in CoPilot)
lSecondTurnImageThe index of the turn image represented by pszSecondTurn. This index can be used to select an appropriate “turn arrow” image for display in the user application.
lIsTruckSpeedLimitIt is a Boolean flag which tells whether the lCurrentStreetRoadSpeed is for Truck or not.

Table: Turn image codes retrieved using Msg_GetTurnInstructions()

Turn Image Code (Right Drive)Turn Image Code (Left Drive)DescriptionImage
-1-1No Next Turn
032Straightimage28
133Left (90 degrees)image29
234Right (90 degrees)image30
335Bear Leftimage31
436Bear Rightimage32
537Sharp Leftimage33
638Sharp Rightimage34
739Left U-turnimage35
840Blankimage37
99No GPS signal (image of satellite)image38
1010Final Destination (checkered flag)image39
1648Straight through traffic circleimage40
1749Left through traffic circle (270degrees CCW)image42
1850Right through traffic circle (90 degrees CCW)image44
1951Bear Left through traffic circleimage46
2052Bear Right through traffic circleimage48
2153Sharp Left through traffic circleimage50
2254Sharp Right through traffic circleimage52
2355U-Turn through traffic circle (180 degrees CCW)image54
6799Merge Rightimage56
68100Merge Leftimage57
>128>128Exit from the highway/Motorwayimage58

enum TRoadClass

{
   RC_CLOSED = 0,
   RC_INTERSTATE = 1,     //Inter state
   RC_INTERSTATE_NORAMPS, //Inter state with No Ramp
   RC_DIVIDED,            //Divided road
   RC_PRIMARY,            //Primary Road
   RC_FERRY,              //Ferry
   RC_SECONDARY,          //Secondary Road
   RC_RAMP,               //Ramp
   RC_LOCAL,              //Local Street
   RC_MAX
};

Note: For determining whether the Exit code is related to left hand drive or right hand drive, please subtract 128 from the returned code. This result should match one of the unique numbers on Left Drive or Right Drive. For Example- Returned Turn Image Code is 130. Subtracting 128 from it will return 2. Now two matches Right Exit (in Right Hand Drive). So it is right hand drive.

Return Value

Always returns 1

Msg_GetCountryBorderInfo

Decode and retrieve the country border crossing information contained in a message buffer received through a subscription to Msg_ID_CountryBorderEvent. For North America region the information relates to crossing a state.

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetCountryBorderInfo(void *pBuffer,
                              unsigned long lBufLen,
                              char *pCountryName,
                              unsigned long lCountryNameLen,
                              char* pLanguage,
                              unsigned long lLanguageLen,
                              char *pDriveSide,
                              unsigned long lDriveSideLen,
                              char *pUnit,
                              unsigned long lUnitLen,
                              char *pCurrency,
                              unsigned long lCurrencyLen);

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLenThe size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pCountryNameA user-allocated buffer to hold the country name or state name for North America region.
lCountryNameLenThe size of the user-allocated buffer pointed to by pCountryName (128).
pLanguageA user-allocated buffer to hold the language
lLanguageLenThe size of the user-allocated buffer pointed to by pLanguage (64).
pDriveSideA user-allocated buffer to hold the Driving Side
lDriveSideLenThe size of the user-allocated buffer pointed to by pDriveSide (8).
pUnitNameA user-allocated buffer to hold the unit used
lUnitLenThe size of the user-allocated buffer pointed to by pUnitName (24).
pCurrencyA user-allocated buffer to hold the currency used
lCurrencyLenThe size of the user-allocated buffer pointed to by pCurrency (24).

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

Msg_GetSpeedLimitEvent

Extracts and parses the over-speedlimit or current-speedlimit information buffer from a message buffer. Dependency - Msg_Subscribe(Msg_ID_OverSpeedLimitEvent) OR Msg_Subscribe(Msg_ID_OverSpeedLimitEvent). We recommend using Msg_GetSpeedLimitEventEx instead of Msg_GetSpeedLimitEvent

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetSpeedLimitEvent(void *pBuffer,
   unsigned long lBufLen,
   unsigned long &lEventType,
   long &lPayload)

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLenThe size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lEventTypeThis identifier corresponding to the Over Speed limit or Current Speed Limit. It value should be equal to Msg_IDT_OVERSPEEDLIMIT or Msg_IDT_CURRENTSPEEDLIMIT
lPayloadif (lEventType) is equal to Msg_IDT_OVERSPEEDLIMIT then lPayload signifies whether the speed limit is for truck or not. (1 or 0). Value is 1 when speed limit is truck type and value is 0 when speed limit is non-truck type.
if (lEventType) is equal to Msg_IDT_CURRENTSPEEDLIMIT then lPayload signifies the actual value of the speed limit. If data does not contain the speed limited then it will return 0. For unlimited speed (Example Germany) value returned is -1. (this is always in miles/hr irrespective of units set in CoPilot)

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful

Msg_GetSpeedLimitEventEx

Extracts and parses the over-speedlimit or current-speedlimit information buffer from a message buffer. Dependency - Msg_Subscribe(Msg_ID_OverSpeedLimitEvent) OR Msg_Subscribe(Msg_ID_OverSpeedLimitEvent)

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GetSpeedLimitEventEx(void *pBuffer,
   unsigned long lBufLen,
   unsigned long &lEventType,
   long &lPayload,
   long &lTruck,
   long &lActual)

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLenThe size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lEventTypeThis identifier corresponding to the Over Speed limit or Current Speed Limit. It value should be equal to Msg_IDT_OVERSPEEDLIMIT or Msg_IDT_CURRENTSPEEDLIMIT
lPayloadlPayload signifies the actual value of the speed limit and is always returned in MPH irrespective of the units set in CoPilot). If the data is not speed limited then it will return 0. For unlimited speed (E.g. Germany) the value returned is -1.
lTruckSpecifies if vehicle is truck (value 1) or non-truck (value 0).
lActualIf (lEventType) is equal to Msg_IDT_OVERSPEEDLIMIT, then lActual signifies the current speed of the vehicle.

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 - Successful

Msg_ID_OverSpeedLimitEvent/Msg_ID_CurrentSpeedLimitEvent

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1
  • Raises an event with message identifier - Msg_ID_CurrentSpeedLimitEvent or Msg_ID_CurrentSpeedLimitEvent.
  • Use Msg_GetSpeedLimitEvent (or Msg_GetSpeedLimitEventEx which is recommended) to decode the data received.
  • For setting the parameter for a Speed Limit warning, use Msg_CreateGenericInformation, Msg_GenericInformationAddDetail, Msg_SendGenericInformation.

Msg_SendTripDetour

Sends a simple request to CoPilot to detour from the current route, no user interaction required.

Supported SinceMinimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.4.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_SendTripDetour(long lDestID = CONN_ID_NONE,
   long lSrcID = CONN_ID_NONE);

Parameters

ParameterDescription
lDestIDDestination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lSrcIDUnique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

  • Less than or equal to 0 = Failed
  • Greater than 0 = Successful
Last updated March 8, 2022.