Skip to content

Routing

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 Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

alkmsg.h
- long Msg_SetRoutingProfileJSON(const char* pJson);
alkmsg.cs
- public static extern int Msg_SetRoutingProfileJSON(byte[] pJson);

Parameters String jsonString - the routing profile in JSON format.

Return Value

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

Return Codes

Code Description
MSG_ROUTINGPROFILERESULT _SUCCESS Successfully modified Routing Profile
MSG_ROUTINGPROFILERESULT _PARSE_JSON_FAIL JSON not formatted properly
MSG_ROUTINGPROFILERESULT _FAILED_PROFILE_NOT_FOUND Attempted to modify a profile that was not found
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_DEFAULT Cannot modify a profile named "Default"
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_TRIPOPTION Attempted to Modify a Restricted or Invalid TripOption
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_VEHICLETYPE Once created, the vehicle profile type for a profile cannot be modified.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CANNOT_MODIFY_REGION Once created, the vehicle's region cannot be modified.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_ROUTINGTYPE_CHANGE_NOT_ALLOWED Profile’s routing type cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_FERRYCLOSED_CHANGE_NOT_ALLOWED Ferry Closed profile cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_TOLLAVOID_CHANGE_NOT_ALLOWED Toll Avoid profile attribute cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_TOLLCLOSED_CHANGE_NOT_ALLOWED Toll Closed profile attribute cannot be modified
MSG_MODIFYROUTINGPROFILERESULT _FAILED_HAZTYPE_NOT_SUPPORTED_FOR_VEHICLE_TYPE Hazardous Material types are support for Truck Heavy Duty and Medium Duty profiles only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_INTLBORDERS_NOT_SUPPORTED_FOR_REGION The International Borders profile option is available in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_CONGESTIONZONE_NOT_SUPPORTED_FOR_REGION Congestion Zones are supported in Europe only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_EMISSIONZONE_NOT_SUPPORTED_FOR_REGION Emission Zones are supported in Europe only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_NATIONALNETWORK_NOT_SUPPORTED_FOR_VEHICLE_TYPE The 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_TYPE 53-foot routing is supported for Truck Heavy Duty profiles in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_PROPANERESTRICTED_NOT_SUPPORTED_FOR_VEHICLE_TYPE Propane restrictions for tunnels are available for RV profiles in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_PROPANERESTRICTED_NOT_SUPPORTED_FOR_REGION Propane restrictions for tunnels are available for RV profiles in the U.S. only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_ELEVATIONAVOID_NOT_SUPPORTED_FOR_VEHICLE_TYPE Elevation limits are available for Truck Heavy Duty and Medium Duty profiles only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_ELEVATION_ALTITUDE_LIMIT_NOT_SUPPORTED_FOR_VEHICLE_TYPE Elevation limits are available for Truck Heavy Duty and Medium Duty profiles only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_GOVERNOR_SPEED_NOT_SUPPORTED_FOR_VEHICLE_TYPE Governor speed is available for Truck profiles only.
MSG_MODIFYROUTINGPROFILERESULT _FAILED_DIMENSION_CHANGE_NOT_SUPPORTED_FOR_VEHICLE_TYPE Dimension settings are available for Truck profiles only.
MSG_MODIFYROUTINGPROFILERESULT _LENGTH_OUT_OF_RANGE_FOR_VEHICLE_TYPE Length out of valid range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _WIDTH_OUT_OF_RANGE_FOR_VEHICLE_TYPE Width out of valid range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _HEIGHT_OUT_OF_RANGE_FOR_VEHICLE_TYPE Height out of valid range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _WEIGHT_OUT_OF_RANGE_FOR_VEHICLE_TYPE Weight out of range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT _WEIGHT_PER_AXLE_OUT_OF_RANGE_FOR_VEHICLE_TYPE Weight per axle out of range for vehicle type
MSG_MODIFYROUTINGPROFILERESULT_FAILED_INVALID_SIDE_OF_STREET_ADHERENCE_COST Will 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: https://developer.copilotpro.com/sdk/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: https://developer.copilotpro.com/sdk/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: https://developer.copilotpro.com/sdk/route/

//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: https://developer.copilotpro.com/sdk/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: https://developer.copilotpro.com/sdk/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,
    "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 = Use 53-foot routing. 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 governor speed - 0 = off, 55 mph = default
  • "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 Since Minimum Operating System
CoPilot 10.9.0.1322 Windows 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 Since Minimum Operating System
CoPilot 10.14.0.325 Windows 10, Android 4.1
Enum Value Description
Off 0 Will not reroute according to side of the street.
Minimal 250 Will increase the route by up to a maximum of 1⁄4 mile to avoid ending up on the wrong side of the street.
Moderate 500 Will increase the route by up to a maximum of 1/2 mile to avoid ending up on the wrong side of the street.
Average 1000 Will increase the route by up to a maximum of 1 mile to avoid ending up on the wrong side of the street.
Strict 5000 Will increase the route by up to a maximum of 5 miles to avoid ending up on the wrong side of the street.
Adhere 10000 Will increase the route by up to a maximum of 10 miles to avoid ending up on the wrong side of the street.
StronglyAdhere 1000000 Will 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 Since Minimum Operating System
CoPilot 10.9.0.1322 Windows 10, Android 4.1

Values

Enum Value
InValid -1
None 0
BCDE 8
CDE 9
DE 10
E 11

THazType

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

Supported Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Values

Enum Value Description
HazType_None 0
HazType_General 1
HazType_Explosive 2
HazType_Inhalant 3
HazType_Radioactive 4
HazType_Caustic 5
HazType_Flammable 6
HazType_Harmful2Water 7

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 Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Values

Enum Value
VT_Auto 0
VT_RV 2
VT_TruckHeavyDuty 3
VT_Bus 4
VT_Motorcycle 6
VT_Bicycle 7
VT_Walking 8
VT_TruckLightDuty 11
VT_TruckMediumDuty 12

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 Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)


Methods

Method Name Return Type Description
RoadSpeedSet(IntPtr input) N/A - constructor Accepts 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 Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Alkmsg.h
  int Msg_AddRoadSpeedSetCallback(void* fnProcessMsg, callingConvention convention = convention_default);
alkmsg.cs
  public static extern int Msg_AddRoadSpeedSetCallback(delCallback fnDel, Msg.callingConvention convention);

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

Return Value

Value Result
0 Indicates a general connection failure
Greater than 0 Success 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 Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
int iVehType The 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 iRoadArea Integer representation of the RoadArea {User = 0, Default = 1}
pJurisdiction The jurisdiction to get the custom road speeds for. Passing null or empty string will return all jurisdictions.

Return Value

Value Result
0 Indicates a general connection failure
Greater than 0 Success 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 Since Minimum Operating System
CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

Alkmsg.h
    long Msg_SetRoadSpeedSet(void *pBytes, unsigned long byteLen);
alkmsg.cs
  public static extern int Msg_SetRoadSpeedSet(byte[] pBytes, uint bytes);

Return Value

Value Result
0 Indicates a general connection failure
Greater than 0 Success 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 Since Minimum Operating System
CoPilot 10.9.0 Windows 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

Value Result
0 Indicates a general connection failure
Greater than 0 Success 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0 Windows 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

Parameter Description
lBreakMinute Break frequency (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
lBreakWaitMinute Break period (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
lVehicleType Type of vehicle (VEH_Auto or VEH_RV).
lRoutingType Type of routing (RTE_Quickest, RTE_Shortest, RTE_AvoidMajorRoads, RTE_Scenic). ‘Scenic’ and ‘avoid highways’ are not supported in CoPilot 9.2.0
usPropaneRestr Propane 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.
usIntBordersOpen International 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.
lLondonCongZone Display London Congestion Zone(CZ_Avoid, CZ_Allow, CZ_Warn)
lTollRoads Allow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction.
lAvoidRtFrwy Level of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedFrwy Speed limit of freeways (in miles/hr.). Recommended range is 50-80.
lAvoidRtDivHwy Level of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedDivHwy Speed limit of divided highways (in miles/hr.). Recommended range is 30-60.
lAvoidRtPriHwy Level of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedPriHwy Speed limit of primary highways (in miles/hr.). Recommended range is 20-50.
lAvoidSecRd Level of avoiding/favoring secondary roads (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedSecRd Speed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
lAvoidLclSt Level of avoiding/favoring local streets (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedLclSt Speed limit of local streets (in miles/hr.). Recommended range is 10-40.
lDestID Destination 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.
lSrcID Unique 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
lDestID Destination 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.
lSrcID Unique 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0 Windows 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

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
rBreakMinute Break frequency (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
rBreakWaitMinute Break period (in minutes). No longer supported, parameter only exists for backwards compatibility. This should be set to 0
rVehicleType Type of vehicle (VEH_Auto or VEH_RV).
rRoutingType Type of routing (RTE_Quickest, RTE_Shortest, RTE_AvoidMajorRoads, RTE_Scenic). ‘Scenic’ and ‘avoid highways’ are not supported in CoPilot 9.2.0
usPropaneRestr Propane 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.
usIntBordersOpen International 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.
rLondonCongZone London Congestion Zone (CZ_Avoid, CZ_Allow, CZ_Warn).
rTollRoads Allow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction).
rAvoidRtFrwy Level of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedFrwy Speed limit of freeways (in miles/hr.). Recommended range is 50-80.
rAvoidRtDivHwy Level of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedDivHwy Speed limit of divided highways (in miles/hr.). Recommended range is 30-60.
rAvoidRtPriHwy Level of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedPriHwy Speed limit of primary highways (in miles/hr.). Recommended range is 20-50.
rAvoidSecRd Level of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedSecRd Speed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
rAvoidLclSt Level of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedLclSt Speed 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0 Windows 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

Parameter Description
lBreakMinute*:* Break frequency (in minutes).
lBreakWaitMinute Break period (in minutes).
lRoutingType Type of routing (RTE_Practical, RTE_Shortest).
usIntBordersOpen International borders open (1/0). US only. For all other regions pass 1.
lTollRoads Allow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction).
usOvrdTruckRestr Override 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
usNatlNetwork National network (1/0). US only. For all other regions pass 1.
us53ftTrailer Truck is a 53’ trailer (1/0). US only. For all other regions pass 1.
usHazmatRt Use Hazmat restriction (1/0).
lHazType Hazmat type(HazType_None = 0, HazType_General, HazType_Explosive, HazType_Inhalant, HazType_Radioactive, HazType_Caustic, HazType_Flammable, HazType_Harmful2Water)
lAvoidRtFrwy Level of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedFrwy Speed limit of freeways (in miles/hr.). Recommended range is 50-80.
lAvoidRtDivHwy Level of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedDivHwy Speed limit of divided highways (in miles/hr.). Recommended range is 30-60.
lAvoidRtPriHwy Level of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedPriHwy Speed limit of primary highways (in miles/hr.). Recommended range is 20-50.
lAvoidSecRd Level of avoiding/favoring secondary roads (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedSecRd Speed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
lAvoidLclSt Level of avoiding/favoring local streets (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
lSpeedLclSt Speed limit of local streets (in miles/hr.). Recommended range is 10-40.
lLengthRestr Truck length restriction used in multiples of tens of inches.
lWidthRestr Truck width restriction used in multiples of tens of inches.
lHeightRestr Truck height restriction used in multiples of tens of inches.
lWeightRestr Truck weight restriction used in tenths of Pounds.
lWeightPerAxleRestr Truck weight restriction used in tenths of Pounds
lLondonCongZone London Congestion Zone (Only applicable for UK data) (Supported only in 960+)
lLowEmissionZone Low Emission Zone. (Only applicable for UK data) (Supported only in 960+)
lDestID Destination 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.
lSrcID Unique 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0 Windows 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

Parameter Description
lDestID Destination 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.
lSrcID Unique 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.9.0 Windows 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

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
rBreakMinute Break frequency (in minutes).
rBreakWaitMinute Break period (in minutes).
rRoutingType Type of routing (RTE_Practical, RTE_Shortest).
rIntBordersOpen International borders open (1/0).
rTollRoads Allow toll roads or not (TR_AlwaysAvoid, TR_IfNecessary, TR_NoRestriction).
usOvrdTruckRestr Override truck restrictions (1/0). Note: this parameter will not be processed in CoPilot V10 onwards
usNatlNetwork National network (1/0).
us53ftTrailer Truck is a 53’ trailer (1/0).
usHazmatRt Use Hazmat restriction (1/0).
rHazType Hazmat type(HT_None = 0, HT_General, HT_Explosives, HT_Inhalants, HT_Radioactive, HT_Caustic, HT_Flammable)
rAvoidRtFrwy Level of avoiding/favoring freeways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedFrwy Speed limit of freeways (in miles/hr.). Recommended range is 50-80.
rAvoidRtDivHwy Level of avoiding/favoring divided highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedDivHwy Speed limit of divided highways (in miles/hr.). Recommended range is 30-60.
rAvoidRtPriHwy Level of avoiding/favoring primary highways (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedPriHwy Speed limit of primary highways (in miles/hr.). Recommended range is 20-50.
rAvoidSecRd Level of avoiding/favoring secondary roads (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedSecRd Speed limit of secondary roads (in miles/hr.). Recommended range is 15-45.
rAvoidLclSt Level of avoiding/favoring local streets (AV_StrongAvoid, AV_Avoid, AV_Neutral, AV_Favor, AV_StrongFavor).
rSpeedLclSt Speed limit of local streets (in miles/hr.). Recommended range is 10-40.
rLengthRestr Truck length restriction used in multiples of tens of inches.
rWidthRestr Truck width restriction used in multiples of tens of inches.
rHeightRestr Truck height restriction used in multiples of tens of inches.
rWeightRestr Truck weight restriction used in tenths of Pounds.
lWeightPerAxleRestr Truck weight restriction used in tenths of Pounds
lLondonCongZone London Congestion Zone (Only applicable for UK data) (Supported only in 960+)
lLowEmissionZone Low 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 Since Minimum Operating System
CoPilot 9.2.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pBufLen Buffer length
pAlertType Any of the predefined warning type. Please see the description below. If it returns the other alert type then please ignore it.
pAlertDistance Distance 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_LaneMergeRight                          1995
#define TypeID_LaneMergeLeft                           1996
#define TypeID_LaneMergeCenter                         1997
#define TypeID_RailwayCrossingProtected                1998
#define TypeID_RailwayCrossingUnprotected              1999
#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_AccidentHazard                          1980
#define TypeID_TreeOverhang                            1986
#define TypeID_TruckPetrolStation                      1979
#define TypeID_TruckRestaurant                         1991
Alert Type Description Image
0 No Overtaking No Overtaking icon
1990 No UTurn No UTurn icon
1992 Protected Overtaking ExtraLane Protected Overtaking ExtraLane icon
1993 Protected Overtaking ExtraLaneRight Protected Overtaking ExtraLaneRight icon
1994 Protected Overtaking ExtraLaneLeft Protected Overtaking ExtraLaneLeft icon
1995 Lane Merge Right Lane Merge Right icon
1996 Lane Merge Left Lane Merge Left icon
1997 Lane Merge Center Lane Merge Center icon
1998 Railway Crossing Protected Railway Crossing Protected icon
1999 Railway Crossing Unprotected Railway Crossing Unprotected icon
1987 Road Narrows Road Narrows icon
1988 No Left Turn No Left Turn icon
1989 No Right Turn No Right Turn icon
1978 Sharp Curve Left Sharp Curve Left icon
1977 Sharp Curve Right Sharp Curve Right icon
1982 SteepHill Upwards SteepHill Upwards icon
1981 SteepHill Downwards SteepHill Downwards icon
1985 Lateral Wind Lateral Wind icon
1983 Risk Of Grounding Risk Of Grounding icon
1980 Accident Hazard Accident Hazard icon
1986 Tree Overhang Tree Overhang icon
1979 Truck Petrol Station Truck 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 Since Minimum Operating System
CoPilot 9.2.0 Windows 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]
"GPSRoutingEvent" = 0/1

  • MSG_IDT_GPS_NOSIGNAL
  • MSG_IDT_GPS_SEARCHING
  • MSG_IDT_GPS_DETERMINING_POS
  • MSG_IDT_GPS_SIGNALBACK

[SDK]
"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

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pBufLen Buffer length
rEventType Any of the predefined event. Please see the description below.
rPayload If 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 Values MESSAGES 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 Since Minimum Operating System
CoPilot 9.2.0 Windows 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

Parameter Description
pBuf The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
dNextTurnDist The distance in miles or kilometers (depending on user settings) to the next turn.
dSecondTurnDist The distance in miles or kilometers (depending on user settings) to the second turn (the turn after the next turn).
dDestDist The distance in miles or kilometers (depending on user settings) to the destination along the chosen route.
dAirDist The distance in miles or kilometers (depending on user settings) to the destination along an imaginary straight line (“as the crow flies”).
dETA The 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.4.0 Windows 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

Parameter Description
pBuf The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pszNextTurn A user-allocated buffer into which text describing the next turn will be copied.
lNextTurnLen The size, in bytes, of the user-allocated buffer dereference by pszNextTurn.
pszSecondTurn A user-allocated buffer into which text describing the second turns (turn after next turn) will be copied.
lSecondTurnLen The size, in bytes, of the user-allocated buffer dereference by pszSecondTurn.
pszCurrentStreet A user-allocated buffer into which the name of the current street will be copied.
lCurrentStreetLen The size, in bytes, of the user-allocated buffer dereference by pszCurrentStreet.
pszTurnStreet A user-allocated buffer into which the name of the next street onto which the user should turn will be copied.
lTurnStreetLen The size, in bytes, of the user-allocated buffer dereference by pszTurnStreet.
pszTurnAction A user-allocated buffer into which the name of the next action that the user should take will be copied.
lTurnActionLen The size, in bytes, of the user-allocated buffer dereference by pszTurnAction.
lTurnImage The 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) Description Image
-1 -1 No Next Turn
0 32 Straight icon28
1 33 Left (90 degrees) icon29
2 34 Right (90 degrees) icon30
3 35 Bear Left icon31
4 36 Bear Right icon32
5 37 Sharp Left icon33
6 38 Sharp Right icon34
7 39 Left U-turn icon35
8 40 Blank icon37
9 9 No GPS signal (image of satellite) icon38
10 10 Final Destination (checkered flag) icon39
16 48 Straight through traffic circle icon40
17 49 Left through traffic circle (270degrees CCW) icon42
18 50 Right through traffic circle (90 degrees CCW) icon44
19 51 Bear Left through traffic circle icon46
20 52 Bear Right through traffic circle icon48
21 53 Sharp Left through traffic circle icon50
22 54 Sharp Right through traffic circle icon52
23 55 U-Turn through traffic circle (180 degrees CCW) icon54
67 99 Merge Right icon56
68 100 Merge Left icon57
>128 >128 Exit from the highway/Motorway icon58

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 Since Minimum Operating System
CoPilot 9.2.0 Windows 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

Parameter Description
pBuf The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions ().
pszNextTurn A user-allocated buffer into which text describing the next turn will be copied.
lNextTurnLen The size, in bytes, of the user-allocated buffer dereference by pszNextTurn.
pszSecondTurn A user-allocated buffer into which text describing the second turn (turn after next turn) will be copied.
lSecondTurnLen The size, in bytes, of the user-allocated buffer dereference by pszSecondTurn.
pszCurrentStreet A user-allocated buffer into which the name of the current street will be copied.
lCurrentStreetLen The size, in bytes, of the user-allocated buffer dereference by pszCurrentStreet.
pszTurnStreet A user-allocated buffer into which the name of the next street onto which the user should turn will be copied.
lTurnStreetLen The size, in bytes, of the user-allocated buffer dereference by pszTurnStreet.
pszTurnAction A user-allocated buffer into which the name of the next action that the user should take will be copied.
lTurnActionLen The size, in bytes, of the user-allocated buffer dereference by pszTurnAction.
lTurnImage The 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.
lCurrentStreetClass It contain the class of the current street. For exact type of class please refer TRoadClass enum.
lCurrentStreetRoadSpeed It 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)
lSecondTurnImage The 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.
lIsTruckSpeedLimit It 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) Description Image
-1 -1 No Next Turn
0 32 Straight img/image28.png
1 33 Left (90 degrees) img/image29.png
2 34 Right (90 degrees) img/image30.png
3 35 Bear Left img/image31.png
4 36 Bear Right img/image32.png
5 37 Sharp Left img/image33.png
6 38 Sharp Right img/image34.png
7 39 Left U-turn img/image35.png
8 40 Blank img/image37.png
9 9 No GPS signal (image of satellite) img/image38.png
10 10 Final Destination (checkered flag) img/image39.png
16 48 Straight through traffic circle img/image40.png
17 49 Left through traffic circle (270degrees CCW) img/image42.png
18 50 Right through traffic circle (90 degrees CCW) img/image44.png
19 51 Bear Left through traffic circle img/image46.png
20 52 Bear Right through traffic circle img/image48.png
21 53 Sharp Left through traffic circle img/image50.png
22 54 Sharp Right through traffic circle img/image52.png
23 55 U-Turn through traffic circle (180 degrees CCW) img/image54.png
67 99 Merge Right img/image56.png
68 100 Merge Left img/image57.png
>128 >128 Exit from the highway/Motorway img/image58.png

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 Since Minimum Operating System
CoPilot 9.2.0 Windows 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

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
pCountryName A user-allocated buffer to hold the country name or state name for North America region.
lCountryNameLen The size of the user-allocated buffer pointed to by pCountryName (128).
pLanguage A user-allocated buffer to hold the language
lLanguageLen The size of the user-allocated buffer pointed to by pLanguage (64).
pDriveSide A user-allocated buffer to hold the Driving Side
lDriveSideLen The size of the user-allocated buffer pointed to by pDriveSide (8).
pUnitName A user-allocated buffer to hold the unit used
lUnitLen The size of the user-allocated buffer pointed to by pUnitName (24).
pCurrency A user-allocated buffer to hold the currency used
lCurrencyLen The 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 Since Minimum Operating System
CoPilot 9.2.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lEventType This identifier corresponding to the Over Speed limit or Current Speed Limit. It value should be equal to Msg_IDT_OVERSPEEDLIMIT or Msg_IDT_CURRENTSPEEDLIMIT
lPayload if (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 Since Minimum Operating System
CoPilot 9.2.0 Windows 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

Parameter Description
pBuffer The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLen The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lEventType This identifier corresponding to the Over Speed limit or Current Speed Limit. It value should be equal to Msg_IDT_OVERSPEEDLIMIT or Msg_IDT_CURRENTSPEEDLIMIT
lPayload lPayload 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.
lTruck Specifies if vehicle is truck (value 1) or non-truck (value 0).
lActual If (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 Since Minimum Operating System
CoPilot 9.2.0 Windows 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 Since Minimum Operating System
CoPilot 9.2.0, Deprecated CoPilot 10.4.0 Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

Parameter Description
lDestID Destination 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.
lSrcID Unique 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 update: June 11, 2020