Skip to main content

Trip

Contents

Msg_TripLoad

Allocate a trip message buffer and return its buffer handle. This needs to be included in every new trip/destination to be sent to CoPilot. This defines the options for how a trip is to be added. Trip messages have a variable number of stops. The DLL must allocate memory to store these stops in a trip message and pass the message to CoPilot. This function stores the main portion of a Trip message structure for subsequent calls to and Msg_SendTrip.

Use Msg_ParserDelete to free the memory when finished with ParserID.

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

Syntax (Prototyped in alkmsg.h)

long Msg_TripLoad(long actionCode,
    long tripID = 0,
    long lMsgID = Msg_ID_Trip);

Defines

#define MSG_ACTION_NONE                0x00
#define MSG_ACTION_INSERT              0x01
#define MSG_ACTION_REPLACE             0x02
#define MSG_ACTION_APPEND              0x09
#define MSG_ACTION_SKIP_CURLOC         0x10

#define MSG_ACTOPT_NOCONFIRM           0x0100
#define MSG_ACTOPT_EXACTMATCHONLY      0x0300
#define MSG_ACTOPT_RETMULTIMATCH       0x0400
#define MSG_ACTOPT_CROSSSTREET         0x0800
#define MSG_ACTOPT_OPTIMIZE            0x1000
#define MSG_ACTOPT_IGNORE_BESTMATCH    0x2000
#define MSG_ACTOPT_OPTIMIZE_DESTFIXED  0x8000

Parameters

Parameter Description
actionCode The action to be performed on the trip. Values can be among the following:
Msg_ACTION_INSERT: Insert the stops contained in this message at the beginning of the existing trip. If current location/GPS fix/Last known position is available then it will add the stop after current location/last known GPS position. If current location/GPS Fix/Last known position is not available, it will insert the stop at top in itinerary
Msg_ACTION_REPLACE: Replace the current trip.
Msg_ACTION_APPEND: Append the stops contained in this message at the end of the existing trip.
Msg_ACTION_SKIP_CURLOC: Don’t add the current location to the trip. This option can only be used when CoPilot is showing “Plan and Edit Trip Screen”. If CoPilot is showing then this flag will be ignored.
Msg_ACTOPT_NOCONFIRM: Disable the confirmation dialog in CoPilot. If this flag is not present, the user needs to confirm the trip in CoPilot. Response is sent from CoPilot as Msg_ID_Response and can be retrieved using Msg_ResponseGet. Confirmation is not supported in CoPilot v9 so user must pass this flag while using v9.
Msg_ACTOPT_OPTIMIZE: This will optimize the sequence of stops in the CoPilot itinerary if it contains no less than 2 and no more than 100 stops, otherwise optimizing will be performed.
Msg_ACTOPT_EXACTMATCHONLY: If this flag is set, CoPilot will only return destinations which match 100% based upon the input address details passed. It will not consider any nearly matches or multiple match. By default without this flag set CoPilot will provide the best match available, this will include the 100% match, as well as nearly matches. Due to backward compatibility, once this flag is set, confirmation dialog will be disabled in CoPilot.
Msg_ACTOPT_RETMULTIMATCH: If this flag is set, CoPilot will return all the multiple matches found for given stop. If this flag is set then CoPilot provides stops through Msg_ID_GeocodeResultSet message. By default without this flag set CoPilot will provide the best match available, this will include the 100% match, as well as nearly matches.
Msg_ACTOPT_CROSSSTREET: If this flag is set, CoPilot will return all cross streets based on given input. It will not consider any guessed or multiple match. If this flag is set, then CoPilot provides stops through Msg_ID_GeocodeResultSet message. To use this feature, the following flag should be set in the user.cfg

[Geocoding]
"SDKFindCrossStreets"=1

If using this function ensure the following:
- Msg_ACTION_REPLACE
- Msg_ACTOPT_NOCONFIRM
- Msg_ACTOPT_RETMULTIMATCH
- Msg_ACTOPT_CROSSSTREET
If Msg_ACTOPT_RETMULTIMATCH is not passed, CoPilot will not return the cross street.

Msg_ACTOPT_IGNORE_BESTMATCH: If this flag is not set and CoPilot has found multiple matches then CoPilot will add the best guess stop into itinerary. If the user does not want to use CoPilot intelligence for best guess match, then set this flag.
Msg_ACTOPT_OPTIMIZE_DESTFIXED: It will optimize the sequence of stops excluding the current location and the final end location added.

Note: Whenever you are sending multiple stops, you need to call Msg_TripLoad once followed by Msg_TripAddStopWithHouseNum for each stop, followed by Msg_SendTrip. (Please see sample code below under Adding Multiple Stops.)

tripID Not used, pass 0.
lMsgID Trip message ID, always pass Msg_ID_TripNew. It is initialized to Msg_ID_Trip to provide backwards compatibility for earlier versions of CoPilot.

Notes

  • To clear the trip, set actionCode = Msg_ACTION_REPLACE without adding any stops (i.e. do not call Msg_TripAddStop).

  • To disable the confirmation dialog on the CoPilot Application, set the actionCode parameter to the bitwise-OR of the desired action and Msg_ACTOPT_NOCONFIRM.

  • To optimize the stops in CoPilot’s trip itinerary, set the actionCode parameter to the bitwise-OR of the desired action and Msg_ACTOPT_OPTIMIZE OR Msg_ACTOPT_OPTIMIZE_DESTFIXED.

  • When GPS feed is provided, CoPilot will remove the first stop in the list.

Return Value

  • Less than 0 = Failed

  • Greater than or equal to 0 - Successful

Returned ID needed for subsequent calls to Msg_TripAddStopWithHouseNum and Msg_SendTrip.

Adding Single Stop

You need to use Msg_TripLoad trip, followed by a Msg_TripAddStopWithHouseNum followed by a Msg_SendTrip() in the same order with appropriate arguments.

Adding Multiple Stops

You need to use a Msg_TripLoad trip, followed by a multiple Msg_TripAddStopWithHouseNum (depending number of stops) followed by a Msg_SendTrip() in the same order with appropriate arguments.

The recommended code sequence for multiple stops:

lngTrip = Msg.Msg_TripLoad(Msg.MSG_ACTION_REPLACE | Msg.MSG_ACTOPT_NOCONFIRM | MSG_ACTOPT_OPTIMIZE_DESTFIXED, 0, Msg.MSG_ID_Trip);

for (int i = 0; i < addresses.Length; i++)
{
var address = addresses[i];
Log.Verbose(LogCategory.Copilot, "Address(" + (i + 1) + "): " + address);

lngTest = Msg.Msg_TripAddStopWithHouseNum(
(int)lngTrip,
CopilotUtil.ConvertString(i.ToString()),
CopilotUtil.ConvertString(address.street),
CopilotUtil.ConvertString(address.streetName),
CopilotUtil.ConvertString(address.city),
CopilotUtil.ConvertString(address.state),
CopilotUtil.ConvertString(address.zip),
null,
address.lat,
address.longt,
Msg.MSG_ID_TripNew, null, null, null, 1);

if (lngTest <= 0)

{ Msg.Msg_SendWindowMode(Msg.WM_SH_HIDE, -1); throw new Exception("Trip add stop failed"); }
}

Msg.Msg_SendTrip((int)lngTrip, -1, -1, Msg.MSG_ID_TripNew);

Msg_TripLoadEx

Allocate a trip message buffer and return its buffer handle. This needs to be included in every new trip/destination to be sent to CoPilot. This defines the options for how a trip is to be added. Trip messages have a variable number of stops. The DLL must allocate memory to store these stops in a trip message and pass the message to CoPilot. This function stores the main portion of a Trip message structure for subsequent calls to and Msg_SendTrip.

Use Msg_ParserDelete to free the memory when finished with ParserID.

Msg_TripLoadEx functions the same as Msg_TripLoad except it has one additional parameter, lShowGUIIdentifier, which allows you to select a screen for the driver to preview the trip before they start navigation.

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

Syntax (Prototyped in alkmsg.h)

long Msg_TripLoadEx(long actionCode,
    long tripID = 0,
    long lMsgID = Msg_ID_Trip,
    long lShowGUIIdentifier);

Defines

#define MSG_ACTION_NONE                0x00
#define MSG_ACTION_INSERT              0x01
#define MSG_ACTION_REPLACE             0x02
#define MSG_ACTION_APPEND              0x09
#define MSG_ACTION_SKIP_CURLOC         0x10

#define MSG_ACTOPT_NOCONFIRM           0x0100
#define MSG_ACTOPT_EXACTMATCHONLY      0x0300
#define MSG_ACTOPT_RETMULTIMATCH       0x0400
#define MSG_ACTOPT_CROSSSTREET         0x0800
#define MSG_ACTOPT_OPTIMIZE            0x1000
#define MSG_ACTOPT_IGNORE_BESTMATCH    0x2000
#define MSG_ACTOPT_OPTIMIZE_DESTFIXED  0x8000

Parameters

Parameter Description
actionCode The action to be performed on the trip. Values can be among the following:
Msg_ACTION_INSERT: Insert the stops contained in this message at the beginning of the existing trip. If current location/GPS fix/Last known position is available then it will add the stop after current location/last known GPS position. If current location/GPS Fix/Last known position is not available, it will insert the stop at top in itinerary
Msg_ACTION_REPLACE: Replace the current trip.
Msg_ACTION_APPEND: Append the stops contained in this message at the end of the existing trip.
Msg_ACTION_SKIP_CURLOC: Don’t add the current location to the trip. This option can only be used when CoPilot is showing “Plan and Edit Trip Screen”. If CoPilot is showing then this flag will be ignored.
Msg_ACTOPT_NOCONFIRM: Disable the confirmation dialog in CoPilot. If this flag is not present, the user needs to confirm the trip in CoPilot. Response is sent from CoPilot as Msg_ID_Response and can be retrieved using Msg_ResponseGet. Confirmation is not supported in CoPilot v9 so user must pass this flag while using v9.
Msg_ACTOPT_OPTIMIZE: This will optimize the sequence of stops in the CoPilot itinerary if it contains no less than 2 and no more than 100 stops, otherwise optimizing will be performed.
Msg_ACTOPT_EXACTMATCHONLY: If this flag is set, CoPilot will only return destinations which match 100% based upon the input address details passed. It will not consider any nearly matches or multiple match. By default without this flag set CoPilot will provide the best match available, this will include the 100% match, as well as nearly matches. Due to backward compatibility, once this flag is set, confirmation dialog will be disabled in CoPilot.
Msg_ACTOPT_RETMULTIMATCH: If this flag is set, CoPilot will return all the multiple matches found for given stop. If this flag is set then CoPilot provides stops through Msg_ID_GeocodeResultSet message. By default without this flag set CoPilot will provide the best match available, this will include the 100% match, as well as nearly matches.
Msg_ACTOPT_CROSSSTREET: If this flag is set, CoPilot will return all cross streets based on given input. It will not consider any guessed or multiple match. If this flag is set, then CoPilot provides stops through Msg_ID_GeocodeResultSet message. To use this feature, the following flag should be set in the user.cfg

[Geocoding]
"SDKFindCrossStreets"=1

If using this function ensure the following:
- Msg_ACTION_REPLACE
- Msg_ACTOPT_NOCONFIRM
- Msg_ACTOPT_RETMULTIMATCH
- Msg_ACTOPT_CROSSSTREET
If Msg_ACTOPT_RETMULTIMATCH is not passed, CoPilot will not return the cross street.

Msg_ACTOPT_IGNORE_BESTMATCH: If this flag is not set and CoPilot has found multiple matches then CoPilot will add the best guess stop into itinerary. If the user does not want to use CoPilot intelligence for best guess match, then set this flag.
Msg_ACTOPT_OPTIMIZE_DESTFIXED: It will optimize the sequence of stops excluding the current location and the final end location added.

Note: Whenever you are sending multiple stops, you need to call Msg_TripLoad once followed by Msg_TripAddStopWithHouseNum for each stop, followed by Msg_SendTrip. (Please see sample code below under Adding Multiple Stops.)

tripID Not used, pass 0.
lMsgID Trip message ID, always pass Msg_ID_TripNew. It is initialized to Msg_ID_Trip to provide backwards compatibility for earlier versions of CoPilot.
lShowGUIIdentifier The view you want to change to, available views are:
MSG_IDT_CURRENT_VIEW: - Display the current view in CoPilot.
MSG_IDT_SHOW_PLANEDITTRIP - Display the trip plan.
MSG_IDT_SHOWROUTE - Display the trip map.

Notes

  • To clear the trip, set actionCode = Msg_ACTION_REPLACE without adding any stops (i.e. do not call Msg_TripAddStop).

  • To disable the confirmation dialog on the CoPilot Application, set the actionCode parameter to the bitwise-OR of the desired action and Msg_ACTOPT_NOCONFIRM.

  • To optimize the stops in CoPilot’s trip itinerary, set the actionCode parameter to the bitwise-OR of the desired action and Msg_ACTOPT_OPTIMIZE OR Msg_ACTOPT_OPTIMIZE_DESTFIXED.

  • When GPS feed is provided, CoPilot will remove the first stop in the list.

Return Value

  • Less than 0 = Failed

  • Greater than or equal to 0 - Successful

Returned ID needed for subsequent calls to Msg_TripAddStopWithHouseNum and Msg_SendTrip.

Adding Single Stop

You need to use Msg_TripLoad trip, followed by a Msg_TripAddStopWithHouseNum followed by a Msg_SendTrip() in the same order with appropriate arguments.

Adding Multiple Stops

You need to use a Msg_TripLoad trip, followed by a multiple Msg_TripAddStopWithHouseNum (depending number of stops) followed by a Msg_SendTrip() in the same order with appropriate arguments.

The recommended code sequence for multiple stops:

lngTrip = Msg.Msg_TripLoadEx(Msg.MSG_ACTION_REPLACE | Msg.MSG_ACTOPT_NOCONFIRM | MSG_ACTOPT_OPTIMIZE_DESTFIXED, 0, Msg.MSG_ID_Trip, Msg.MSG_IDT_SHOWROUTE);

for (int i = 0; i < addresses.Length; i++)
{
var address = addresses[i];
Log.Verbose(LogCategory.Copilot, "Address(" + (i + 1) + "): " + address);

lngTest = Msg.Msg_TripAddStopWithHouseNum(
(int)lngTrip,
CopilotUtil.ConvertString(i.ToString()),
CopilotUtil.ConvertString(address.street),
CopilotUtil.ConvertString(address.streetName),
CopilotUtil.ConvertString(address.city),
CopilotUtil.ConvertString(address.state),
CopilotUtil.ConvertString(address.zip),
null,
address.lat,
address.longt,
Msg.MSG_ID_TripNewEx, null, null, null, 1);

if (lngTest <= 0)

{ Msg.Msg_SendWindowMode(Msg.WM_SH_HIDE, -1); throw new Exception("Trip add stop failed"); }
}

Msg.Msg_SendTrip((int)lngTrip, -1, -1, Msg.MSG_ID_TripNewEx);

Msg_TripAddStopWithHouseNum

Add a stop to a previously allocated trip message buffer, all individual stops need to be added. To be used when House number and Street Address need to be defined separately.

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

Syntax (Prototyped in alkmsg.h)

long Msg_TripAddStopWithHouseNum (long ID,
                        char *pName,
                        char *pHouseNum,
                        char *pAddress,
                        char *pCity,
                        char *pState,
                        char *pPostal,
                        char *pJurisdiction,
                        long lLat,
                        long lLon,
                        long lMsgID = Msg_ID_Trip,
                        char *pNorthing = NULL,
                        char *pEasting = NULL,
                        char *pGridSQ = NULL,
                        long lStopVia = 1);

Parameters

Parameter Description
ID ID returned from Msg_TripLoad (Mandatory)
pName Stop Name custom text field – please use this parameter to populate the ‘Destination’ field within the Info Bar. This can be used to provide the driver with the exact address details required for the destination. Its greatest benefit is to mask the address name if not 100% matched by CoPilot as this will show the exact name the driver needs to see. Maximum of 20 characters, single line.
pHouseNum House Number
pAddress Street Name
pCity City name.
pState In North America this is the State abbreviation. Outside of North America this is the Country abbreviation: Code — ISO 3166-1 alpha-2 code It is essential to include this for geocoding success
pPostal Valid 5-digit zip code (USA/Europe) or 4-7 digit full postcode (UK only) or 6 digit Netherlands postcode
pJurisdiction Jurisdiction
lLat Latitude, expressed as an integer value in millionths of a degree.
lLon Longitude, expressed as an integer value in millionths of a degree.
lMsgID Trip message ID, always pass Msg_ID_TripNew. It is initialized to Msg_ID_Trip to provide backwards compatibility for earlier versions of CoPilot.
pNorthing Northing for the OS Grid, the number of digits should be between 2-5 and should be equal to the number of digits in pEasting.
pEasting Easting for the OS Grid, the number of digits should be between 2-5 and should be equal to the number of digits in pNorthing.
pGridSq Grid Square abbreviation, the number of characters should be equal to 2.
lStopVia Signifies stop or waypoint. (1: Stop 0:Waypoint) (Currently not in use – should always be 1) To convert a stop to a waypoint (or visa-versa) we advise to use Msg_TripGetStopWaypointInfo along with Msg_IDT_TOGGLESTOPORWAYPOINT

Return Value

  • ≤ 0 - Failed
  • Greater than 0 - Successful

Additional Notes

Latitude and Longitude Input All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, ALK London office is located at 0.122805W & 51.518220N so it should be passed as a -122805 longitude & 51518220 latitude.

ID and one of the following combination parameters are mandatory. 1. lLat and lLong 2. pState and (pCity OR pPostal) 3. pNorthing, pEasting and pGridSq

Logic when only sending in Lat/Long for address: When using a Latitude and Longitude only, the location does not exactly snap to a road, which can lead CoPilot to take the most convenient road to the route (not the nearest), which can cause issues in the routing. In order to overcome this issue, we would recommend that you add one of the following adjustments: Within User.cfg please add the following line:

> [Geocoding] <br>
> "CleanupBestChoiceOnly"=1 <br>

Other Option for either:

  • If you pass street address with the lat/long, we try to match the address details if this is within a short distance of the Lat/Long provided, we will snap the location to the correct road.

Postcode search results:

  • When entering postcode information and searching streets you may notice a number of results are returned for streets that do not match the postcode entered. These are stated as being within the neighboring area. This means that they do not match the exact postcode entered but they are nearby in case you have incorrect details.

To remove these addresses from the list of return destinations please add the following entry to user.cfg.

[Geocoding]
“DeleteOutOfCityMatches”=1

Address vs Coordinates vs Address and Coordinates What if I have a Latitude and Longitude value as well as the street address, what is the priority in CoPilot?

  • Scenario 1 – Only the full address is passed via SDK • This is straight forward CoPilot will try to geocode the address.

  • Scenario 2 – Only Lat is passed via SDK • This is straight forward. CoPilot will try to use lat-long to provide the route.

  • Scenario 3 – Both Address and Lat-Lon are passed via SDK • If CoPilot receives a complete lat/long and address details

    • CoPilot will assume the lat/long is 100% correct
    • CoPilot will identify all nearby street names and search each one by distance to match the street name provided in the input address. CoPilot will snap to the closest link, regardless of house number.
    • In the address field CoPilot will mask the house number to match the version supplied, even if it is not the nearest house number to the Lat/Lon provided
    • If no matching street name can be found within 1 mile, CoPilot will use the lat/long.

Msg_SendTrip

Send a new trip itinerary (list of stops) to the application. This is used following Msg_TripLoad and Msg_TripAddStopWithHouseNum

Sends a message with trip stop to destination ID.

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

Syntax (Prototyped in alkmsg.h)

long Msg_SendTrip(long ID,
                  long lDestID = CONN_ID_NONE,
                  long lSrcID = CONN_ID_NONE,
                  long lMsgID = Msg_ID_Trip);

Parameters

Parameter Description
ID ID returned from Msg_TripLoad.
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).
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.
lMsgID Trip message ID, always pass Msg_ID_TripNew. Msg_ID_Trip to provide backwards compatibility for earlier versions of CoPilot. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

  • ≤ 0 - Failed
  • Greater than 0 - Successful

Notes

  • CoPilot will send the acknowledgement by Msg_ID_GeocodeResultSet, if user does set the Msg_ACTOPT_RETMULTIMATCH during Msg_TripLoad.

  • CoPilot will send the acknowledgement by Msg_ID_GenericData (payload Msg_IDT_GEORESULT), if user does not set the Msg_ACTOPT_RETMULTIMATCH during Msg_TripLoad. For CoPilot 920 and above, we highly recommend customer to use Msg_IDT_GEOCODE. Msg_IDT_GEOCODE contains more information including any geocoding error, latitude, longitude, stop name, place errors and address errors.

  • Version 920 CoPilot and above

    • CoPilot will respond with a geocode result to Msg_ID_GenericInformation (identifier Msg_IDT_GEOCODE). For further information, please read the Msg_ID_GenericInformation in detail.

Msg_TripParse

This is the first API to be used if you wish to receive all the details of the currently loaded Trip. Decodes and retrieves the message ID from a trip message buffer.

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

Syntax (Prototyped in alkmsg.h)

long Msg_TripParse(void *pBytes,
   unsigned long bytes,
   long lMsgID = Msg_ID_Trip);

Parameters

Parameter Description
pBytes The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
bytes The size of the message buffer in bytes, passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lMsgID Trip message ID, always pass Msg_ID_Trip.

Return Value

Returned ID needed for subsequent calls to Msg_TripGet and Msg_TripGetStopInfo.


Msg_SendTripJSON

This API is used to send stops in JSON format from the client application to CoPilot. This will include the stop location, side of street tolerance, stop icon as well as advanced ETA attributes.

If the user would NOT like to change views MSG_IDT_CURRENT_VIEW should be passed to CoPilot.

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

Syntax (Prototyped in alkmsg.h)

Parameters

Parameter Description
actionCode Same as Msg_TripLoad action code
lShowGUIIdentifier The view you want to change to, available views are MSG_IDT_CURRENT_VIEW, MSG_IDT_SHOW_PLANEDITTRIP and MSG_IDT_SHOWROUTE
bShowCoPilot If this is true, we show CoPilot
pJson Complete contents of a JSON message describing a CoPilot set of stops

lShowGUIIdentifier Identifiers

Identifier Description
MSG_IDT_CURRENT_VIEW Display the current view in CoPilot.
MSG_IDT_PLANEDITTRIP Display the trip plan.
MSG_IDT_SHOWROUTE Display the trip map.

JSON Example

{
  "Trip": {
    "Name": "Road Test trip ",
    "Stops": [
      {
        "Location": {
          "Address": {
            "StreetAddress": "1 Independence Way",
            "City": "Princeton",
            "State": "NJ",
            "Zip": "08540",
            "Country": ""
          },
          "Coords": {
            "Lat": "40.361153",
            "Lon": "-74.602685"
          },
          "VehicleRestricted": "false"
        },
        "stopType": 0,
        "stopSequence": 0,
        "Note": "2 Large Packages",
        "SideOfStreet": 0,
        "Name": "Current location : 1 Independence Way,Princeton, NJ 08540",
        "SafeToTurnAround": 0,
        "GeocodeType": 2,
        "ID": "784552125"
      },
      {
        "Location": {
          "Address": {
            "StreetAddress": "401 Kingston Terrace",
            "City": "Princeton",
            "State": "NJ",
            "Zip": "08540",
            "Country": ""
          },
          "Coords": {
            "Lat": "40.376828",
            "Lon": "-74.605018"
          },
          "VehicleRestricted": "false"
        },
        "CustomFields": {
          "Note2": "2 + 3",
          "Note3": "$",
          "DetailsDisplay": "DEL: 4532 1 + 2 10:30 $"
        },
        "stopType": 0,
        "stopSequence": 1,
        "Note": "2 small boxes",
        "SideOfStreet": 1,
        "SafeToTurnAround": 1,
        "Name": "Stop 2: 401 Kingston Terrace, Princeton, NJ 08540",
        "GeocodeType": 2,
        "ID": "321545614652641"
      },
      {
        "Location": {
          "Address": {
            "StreetAddress": "3 Carter Brook Lane",
            "City": "Princeton",
            "State": "NJ",
            "Zip": "08540",
            "Country": ""
          },
          "Coords": {
            "Lat": "40.379089",
            "Lon": "-74.600965"
          },
          "VehicleRestricted": "false"
        },
        "stopType": 0,
        "stopSequence": 2,
        "Note": "Large envelope",
        "SideOfStreet": 2,
        "Name": "Stop 3: 3 Carter Brook Lane,Princeton, NJ 08540",
        "SafeToTurnAround": 2,
        "GeocodeType": 2,
        "ID": "5146851946814"
      }
    ]
  }
}

Return Value

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

To receive return values a callback needs to be set up with Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericInformation, true, false, delOnGenericInformation, Msg.callingConvention.convention_stdcall); and listen for MSG_IDT_IMPORT_TRIP, the return values are te payload for that callback.

Return Codes

Value Description
MSG_IDT_IMPORT_TRIP_SUCCESS Successful in sending the request to CoPilot.
MSG_IDT_IMPORT_TRIP_JSON_PARSE_ERROR JSON parsing failed - ensure a valid json object is being passed
MSG_IDT_IMPORT_TRIP_INVALID_TRIP_JSON JSON has missing/incomplete fields required for trip integration

Trip JSON field description

The JSON schema is defined below. All fields not marked as Optional are required.

  • Set (array)
  • Name - (string; optional; 256 char) The unique trip name; not visible anywhere in CoPilot, used for organizational purposes.
  • Stops - (array)
    • Location - (array)
      • Address - (object) Used for geocoding stop
        • StreetAddress - (string; optional; 64 char max)
        • City - (string; optional; 34 char max)
        • Zip - (string; optional; 12 char max)
        • State - (string; optional; 4 char max) State (US) or Country (EU) abbreviation
        • County - (string; optional; 64 char max)
    • Coords - (object) Used for geocoding stop
      • Lat - (string) decimal degrees; positive for North, negative for South
      • Lon - (string) decimal degrees, positive for East, negative for West
    • VehicleRestricted - (boolean) True indicates the stop is on a road link for pedestrians and bicycles only. Available in CoPilot 10.14 and higher
    • ID - (string;optional; 66535 char) Unique stop identifier
    • Name - (string; optional; 256 char) Unique stop name. Displayed when viewing a stop
    • StopSequence - (unsigned integer; required) Used for identifying stop sequence number.eg ‘Stop n’ where n is the sequence number.
    • Note - (string; optional; 66535 char) Use this field to provide other specific information related to the stop. Displayed in stop detail view.
    • GeocodeType - (integer; optional) Used when geocoding stops
      • Default = 0
      • AddressOnly = 1
      • LatLonOnly = 2
      • AddressAndLatLon = 3
    • StopType - (integer; optional) Used for specific routing logic and for display
      • None = 0
      • Origin = 1
      • Work = 2
      • WayPoint = 3
      • FuelStop = 4
      • RestStop = 7
      • Destination = 9
    • SideOfStreet - (integer; optional) Will be used in routing and guidance. This will override current side of street logic in CoPilot
      • Unknown = -1
      • Left = 0
      • Right = 1
    • SafeToTurnAround - (integer; optional) Used to display information to the driver
      • Yes = 0
      • No = 1
      • Unknown = 2
    • StopIcon - (string; optional; 66535 char) Use this field to provide stop icon name . No need to provide file extension
    • CustomFields - (array) Key and value must be of type string (technically can hold up 66535 char, but the display, will be able to display all of those characters. Key can be any string with no spaces and cannot be a duplicate of a previous key.

CustomFields JSON Explanation
“Note2” - string to hold Note2 description
“Note3” - string to hold Note3 description
“CustomChevronDisplay” - custom message for underneath the Chevron. In general, this string can display around 23-24 characters.
“DetailsDisplay” - custom message banner along the top of the 3D Nav screen. In general, this should be able to hold between 21-24 characters.


Msg_TripGet

This is the second step to be used if you want to receive details of the currently loaded Trip. This provides header information including the total number stops

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

Syntax (Prototyped in alkmsg.h)

long Msg_TripGet(long ID,
   long &rActionCode,
   long &rTripID,
   long &rStopCount,
   long &rSourceID,
   long &rDestID,
   char *pFromScreenName,
   unsigned long maxFromScreenName,
   long lMsgID = Msg_ID_Trip);

Parameters

Parameter Description
ID Message buffer handle returned by Msg_TripParse.
rActionCode Unused.
rTripID Unused.
rStopCount Number of stops in the message.
rSourceID Unique ID of the sender of the message.
Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
rDestID 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.
pFromScreenName A user-allocated buffer to store the name of the sender.
maxFromScreenName The size of the user-allocated buffer pointed to by pFromScreenName.
lMsgID Trip message ID, always pass Msg_ID_Trip.

Return Value

  • ≤ 0 - Failed

  • Greater than 0 - Successful


Msg_TripGetStopInfo

Used in conjunction with Msg_Trip* APIs, returns itinerary stop list information from a Msg_ID_Trip message, returning all individual stop details. We recommend using Msg_tripGetStopWaypointInfo instead of Msg_TripGetStopInfo.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_TripGetStopInfo(long ID,
   long index,
   char *pName,
   long lNameLen,
   char *pCity,
   long lCityLen,
   char *pState,
   long lStateLen,
   char *pAddress,
   long lAddressLen,
   char *pZip,
   long lZipLen,
   char *pJuris,
   long lJurisLen,
   long &rLatitude,
   long &rLongitude,
   long lMsgID = Msg_ID_Trip);

Parameters

Parameter Description
ID Message buffer handle returned by Msg_TripParse.
index Index of the stop whose information is being retrieved.
pName A user-allocated buffer to store the name of the stop.
lNameLen The size of the user-allocated buffer pointed to by pName.
pCity A user-allocated buffer to store the city name of the stop.
lCityLen The size of the user-allocated buffer pointed to by pCity.
pState A user-allocated buffer to store the state name of the stop.
lStateLen The size of the user-allocated buffer pointed to by pState.
pAddress A user-allocated buffer to store the street address of the stop.
lAddressLen The size of the user-allocated buffer pointed to by pAddress.
pZip A user-allocated buffer to store the zip code of the stop.
lZipLen The size of the user-allocated buffer pointed to by pZip.
pJuris A user-allocated buffer to store the jurisdiction name of the stop.
lJurisLen The size of the user-allocated buffer pointed to by pJuris.
rLatitude Latitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Latitude.
rLongitude Longitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Longitude.
lMsgID Trip message ID, always pass Msg_ID_Trip.

Return Value

  • ≤ 0 - Failed

  • Greater than 0 - Successful

Notes: The first stop returned by Msg_TripGetStopInfo() is the current location of the vehicle and the rest are the stops present in CoPilot’s itinerary.

All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 0.122805W & 51.518220N so it should be pass as a -122805 longitude & 51518220 latitude.

Msg_TripGetStopWaypointInfo

Used in conjunction with Msg_Trip* APIs, returns itinerary stop list information from a Msg_ID_Trip message, returning all individual stop details including Waypoints. We recommend using Msg_tripGetStopWaypointInfo instead of Msg_TripGetStopInfo

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

Syntax (Prototyped in alkmsg.h)

long Msg_TripGetStopWaypointInfo(long ID,
   long index,
   char *pName,
   long lNameLen,
   char *pCity,
   long lCityLen,
   char *pState,
   long lStateLen,
   char *pAddress,
   long lAddressLen,
   char *pZip,
   long lZipLen,
   char *pJuris,
   long lJurisLen,
   long &rLatitude,
   long &rLongitude,
   long &lStopVia,
   long lMsgID = Msg_ID_TripNew);

Parameters

Parameter Description
ID Message buffer handle returned by Msg_TripParse.
index Index of the stop whose information is being retrieved.
pName A user-allocated buffer to store the name of the stop.
lNameLen The size of the user-allocated buffer pointed to by pName.
pCity A user-allocated buffer to store the city name of the stop.
lCityLen The size of the user-allocated buffer pointed to by pCity.
pState A user-allocated buffer to store the state name of the stop.
lStateLen The size of the user-allocated buffer pointed to by pState.
pAddress A user-allocated buffer to store the street address of the stop.
lAddressLen The size of the user-allocated buffer pointed to by pAddress.
pZip A user-allocated buffer to store the zip code of the stop.
lZipLen The size of the user-allocated buffer pointed to by pZip.
pJuris A user-allocated buffer to store the jurisdiction name of the stop.
lJurisLen The size of the user-allocated buffer pointed to by pJuris.
rLatitude Latitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Latitude.
rLongitude Longitude of the stop (in millionths of a degree). Divide this number by 1,000,000 to obtain degrees Longitude.
lStopVia Tells whether the Stop is waypoint or not (if value is 0, stop is waypoint) To convert a stop to a waypoint (or visa-versa) we advise to use Msg_TripGetStopWaypointInfo along with Msg_IDT_TOGGLESTOPORWAYPOINT
lMsgID Trip message ID, always pass Msg_ID_Trip.

Return Value

  • ≤ 0 - Failed

  • Greater than 0 - Successful

Note: The first stop returned by Msg_TripGetStopInfo() is the current location of the vehicle and the rest are the stops present in CoPilot’s itinerary.

Note: All Latitude and Longitude values are sent as long integers. These values are encoded as millionths of a degree. North and East are positive values, South and West are negative values. For example, the Trimble Maps London office is located at 0.122805W & 51.518220N so it should be pass as a -122805 longitude & 51518220 latitude.


Msg_SendTripStopInfoRequest

Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary, to be followed by Msg_TripGet* APIs. We recommend using Msg_SendStopInfoRequest instead of Msg_SendTripStopInfoRequest

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_SendTripStopInfoRequest(void);

Notes

In order to retrieve the list of stops in CoPilot’s itinerary, you must have previously set a callback for the Msg_ID_Trip message. This is done as follows. First, declare the callback:

void OnTripMsg(const char *pBuf, const unsigned long lBufLen){
  // Declare all variables to be used in this function here
  long msgID = Msg_TripParse(pBuffer, cBuffer,MSG_ID_Trip);

  Msg_TripGet(msgID, actionCode, tripID, lStopCount,
  lSourceID, destID, fromScreenName,
  sizeof(fromScreenName), MSG_ID_Trip);

  for (int i = 0; i <lStopCount; i++)
  {
    long ret = Msg_TripGetStopInfo(msgID, i, stopName, sizeof(stopName),
      cityName, sizeof (cityName),
      stateName, sizeof (stateName),
      address, sizeof (address),
      zipCode, sizeof (zipCode),
      jurisName, sizeof (jurisName),
      lLatitude, lLongitude,
      MSG_ID_Trip);
  }
  // Use the data in your application here
}

Second, set the callback for Msg_ID_TripNew message via the SDK:

Msg_UpdateOptions(Msg_ID_Trip, true, true, false, (void *) OnTripMsg));

Finally, call Msg_SendTripStopInfoRequest() to request the position immediately:

Msg_SendTripStopInfoRequest();

Return Value

  • ≤ 0 Failed

  • Greater than 0 Successful


Msg_SendStopInfoRequest

Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary, to be followed by Msg_Trip* APIs, includes information on Waypoints. We recommend to use Msg_SendStopInfoRequest instead of Msg_SendTripStopInfoRequest

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

Syntax (Prototyped in alkmsg.h)

long Msg_SendStopInfoRequest(void);

Parameters

None

Notes: In order to retrieve the list of stops in CoPilot’s itinerary, you must have previously set a callback for the Msg_ID_TripNew message. This is done as follows:

First, declare the callback:

void OnTripMsg(const char *pBuf, const unsigned long lBquen) {
  //Declare all variables to be used in this function here
  long msgID = Msg_TripParse(pBuffer, cBuffer, MSG_ID_TripNew);

  Msg_TripGet(msgID, actionCode, tripID, lStopCount, lSourceID, destID,
    fromScreenName, sizeof(fromScreenName), MSG_ID_TripNew);
  for (int i = 0; i < lStopCount; i++) {
    long ret = Msg_TripGetStopWaypointInfo(msgID, i,
      stopName, sizeof(stopName),
      cityName, sizeof(cityName),
      stateName, sizeof(stateName),
      address, sizeof(address),
      zipCode, sizeof(zipCode),
      jurisName, sizeof(jurisName),
      lLatitude, lLongitude,
      lStopVia, HSG_ID_TripNew);
  }
  // Use the data in your application here
}

Second, set the callback for Msg_ID_TripNew message via the SDK:

Msg_UpdateOptions(MSG_ID_TripNew, true, false, (void *)OnTripMsg);

Finally, call Msg_SendTripStopInfoRequest() to request the position:

Msg_SendTripStopInfoRequest();

Return Value

  • ≤ 0 - Failed

  • Greater than 0 - Successful


Msg_SendStopInfoRequestJSON()

Sends the request to CoPilot to get the list of stops in CoPilot’s itinerary in JSON format.

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

Syntax (Prototyped in alkmsg.h)

long Msg_SendStopInfoRequestJSON(void);

Parameters

None

Return Values

Less than or Equal to 0 - Error Great than 0 - Successful

Callback Function

private int OnSDKStopInfoResponse(IntPtr pData, uint numBytes);

Sample Code

//First, declare and implement the callback function:
public form_address_trip()
{
InitializeComponent();
delOnSDKStopInfoResponseCB = new Msg.delSDKDeliverCB(OnSDKStopInfoResponse);
 }

private int OnSDKStopInfoResponse(IntPtr pData, uint numBytes);
{ String sJson = Msg.MarshalNativeUTF8ToManagedString(pData); }

//Second, set the callback attached to the “TSdkStopInfoJsonRsp” flex callback message via the SDK:
        Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkStopInfoJsonRsp"), delOnSDKStopInfoResponseCB);

//Finally, call Msg_SendTripStopInfoRequestJSON() to request the position:
                    Msg.Msg_SendStopInfoRequestJSON();

//The JSON representation of the itineraries stops will be received in the callback function.

Msg_MultiStopParse

Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH. Returns the message ID to be used with Msg_MultiStopGet* APIs

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

Use Msg_ParserDelete to free the memory when finished with ParserID.

Syntax (Prototyped in alkmsg.h)

long Msg_MultiStopParse (void *pBytes, unsigned long bytes);

Parameters

Parameter Description
pBytes The message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
bytes The size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions().

Return Value

Identifier

#define Msg_ID_GeocodeResultSet 0xf1000411

Msg_MultiStopGetHeader

Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH returns the header information including the number of stops

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

Syntax (Prototyped in alkmsg.h)

long Msg_MultiStopGetHeader (unsigned long lMultiStopMsgID,
                              long & rError,
                              unsigned long &rStopCount)

Parameters

Parameter Description
lMultiStopMsgId Message buffer handle returned by Msg_MultiStopParse.
rError Any error occurred during geocoding for requested stop otherwise 0.
rStopCount Number of stops in this message.

Return Value

  • 0 - Unable to find MultiStopMsgID from the cache list
  • 1 - Successful

Error code returns in rError:

-2 Not enough memory


Msg_MultiStopGetDetails

Used in conjunction with Msg_TripLoad with the parameter Msg_ACTOPT_RETMULTIMATCH returns the individual stop details.

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

Syntax (Prototyped in alkmsg.h)

long Msg_MultiStopGetDetails(unsigned long lMultiStopMsgId,
   unsigned long lIndex,
   char *pStreet,
   unsigned long lStreetLen,
   char *pCity,
   unsigned long lCityLen,
   char *pPostcode,
   unsigned long lPostcodeLen,
   char* pState,
   unsigned long lStateLen,
   char* pJuris,
   unsigned long lJurisLen,
   long &rLatitude,
   long &rLongitude);

Parameters

Parameter Description
lMultiStopMsgId Message buffer handle returned by Msg_SearchParse.
lIndex Index of the stop whose information is being retrieved.
pStreet A user-allocated buffer to store the name of the street.
lStreetLen The size of the user-allocated buffer pointed to by pStreet.
pCity A user-allocated buffer to store the city of the current location.
lCityLen The size of the user-allocated buffer pointed to by pCity.
pPostcode A user-allocated buffer to store the state of the postcode.
lPostcodeLen The size of the user-allocated buffer pointed to by pPostCode.
pState A user-allocated buffer to store the zip code of the current location.
lStateLen The size of the user-allocated buffer pointed to by pState.
pJuris A user-allocated buffer to store the jurisdiction of the current location.
lJurisLen The size of the user-allocated buffer pointed to by pJuris.
rLatitude Latitude of the given stop.
rLongitude Longitude of the given stop.

Return Value

  • 0 - Unable to find MultiStopMsgID

  • -1 - Invalid index value

  • 1 - Successful

Last updated January 10, 2024.