Skip to main content

General Settings

Contents

Msg_SendGenericTextData

Sends a generic data message (Msg_ID_GenericTextData) to CoPilot.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_SendGenericTextData(long lIdentifier,
   long lPayload,
   char *strPayload = 0,
   long stringLen = 0,
   long lRequestID=0,
   long lDestID = CONN_ID_NONE,
   long lSrcID = CONN_ID_NONE,
   bool bAck = false);

Parameters

ParameterDescription
lIdentifierUnique identifier whose value is being sent.
lPayloadPayload of identifier
strPayloadString payload of identifier.
stringLenLength of the strPayLoad.
lRequestIDRequested ID, Always pass 0.
lDestIDDestination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lSrcIDUnique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
bAckUser acknowledgement, always pass false .

Return Value

  • ≤ 0 - Failed
  • Greater than 0 - Successful

Msg_GenericTextDataGet

Retrieves and decodes information received in a generic text data message (Msg_ID_GenericTextData).

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

char * Msg_GenericTextDataGet(void *pBuffer,
   unsigned long nBytes,
   long &lIdentifier,
   long &lPayload,
   long &lRequestID,
   long &lStrLen);

Parameters

ParameterDescription
pBufferRaw pointer to the buffer received by your callback function (previously set by Msg_UpdateOptions).
nBytesNumber of bytes in pBuffer
lIdentifierUnique identifier whose value is being extracted.
lPayloadPayload of identifier.
lRequestIDRequest ID, ignore this parameter.
lStrLenSize of the passing string.

Return Value

Valid char* if string is retrieved successfully otherwise NULL


GenericTextData Identifier Details

The following is a list of identifiers that can be used with this API:

#define Msg_ID_GenericTextData 0xf1000122
#define Msg_IDT_LOADPROFILE 0x0074L

Msg_IDT_LOADPROFILE

This API is use to load the profile. To retrieve all the profiles stored in CoPilot, use Msg_RequestGenericInformation with Msg_IDT_ROUTING_PROFILES.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request (Msg_IDT_LOADPROIFLE):

  • lPayload : Ignore

  • strPayload : Name of the profile to load. Profile must be present in CoPilot.

  • strLength : Length of the strPayload string

  • Once CoPilot received the load profile request, CoPilot will load the profile and provide acknowledgement by Msg_IDT_LOADPROFILE_RESULT.

Notes If profile does not exist in CoPilot, CoPilot will generate an error and send by

Msg_IDT_LOADPROFILE_RESULT.


Msg_RequestGenericInformation

Is the first message to be used in conjunction with Msg_GenericInformation* APIs. Requests information from CoPilot, Msg_ID_GenericInformation. Used to set/get the settings and request generic operation.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_RequestGenericInformation (unsigned long lIdentifier,
                                    long lPayload,
                                    long lDestID = CONN_ID_NONE,
                                    long lSrcID = CONN_ID_NONE);

Parameters

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

Return Value

  • < 0 - Failed to send message to CoPilot

  • 0 - Unable to send message as SDK did not find connection

  • 0 - Successful


Msg_GenericInformationParse

Decodes and retrieves the message ID from a generic information message buffer.

Use Msg_ParserDelete to free the memory when finished with ParserID.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
pBytesThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
bytesThe size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions().

Return Value

<0 - Unable to allocate message buffer ≥0 - Successful, Returned Message ID needed for subsequent calls to Msg_GenericinformationGetHeader and Msg_GenericinformationGetDetails


Msg_GenericInformationGetHeader

Decodes and retrieves the header information (item counts, message id etc.) from a generic information message buffer.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GenericInformationGetHeader (unsigned long lMsgId,
     unsigned long &rIdentifier,
     long &rError,
     unsigned long & rCount)

Parameters

ParameterDescription
lMsgIdMessage buffer handle returned by Msg_GenericInformationParse.
rIdentifierUnique identifier whose value is being received.
rErrorIf any error occurred during operation.
rCountTotal count.

Return Value

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

Msg_GenericInformationGetDetails

Decodes and retrieves the request specific information from a generic information message buffer.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_GenericInformationGetDetails (unsigned long lMsgId,
                                       unsigned long lIndex,
                                       long &rlInfo1,
                                       long rInfo2,
                                       double &rlInfo3,
                                       double &rInfo4,
                                       char *pInfo5,
                                       unsigned long lInfoLen5,
                                       char *pInfo6,
                                       unsigned long lInfoLen6)

Parameters

ParameterDescription
lMsgIdMessage buffer handle returned by Msg_GenericInformationParse.
lIndexIndex of the item.
rInfo1Returns (long) generic information related to the identifier.
rInfo2Returns (long) generic information related to the identifier.
rInfo3Returns (double) generic information related to the identifier.
rInfo4Returns (double) generic information related to the identifier.
pInfo5A user-allocated buffer to store generic information related to the identifier.
lInfo5The size of the user-allocated buffer pointed to by pInfo5.
pInfo6A user-allocated buffer to store generic information related to the identifier.
lInfo6The size of the user-allocated buffer pointed to by pInfo6.

Return Value

  • 1 - Unable to find MsgID from the cache list

  • -1 - Invalid index value

  • 1 - Successful


GenericInformation Identifier Details

lIdentifier

#define MSG_ID_GenericInformation    0xf1000125

#define MSG_IDT_MAPDATA              0x0001L
#define MSG_IDT_COUNTRIES            0x0002L
#define MSG_IDT_STATES               0x0003L
#define MSG_IDT_POICATEGORIES        0x0004L
#define MSG_IDT_ITINERARY            0x0005L
#define MSG_IDT_ETADIST              0x0006L
#define MSG_IDT_LANGVOICES           0x0007L
#define MSG_IDT_CURRENT_LANGVOICE    0x0008L
#define MSG_IDT_GEOCODE              0x0009L
#define MSG_IDT_CPVERSION            0x000AL
#define MSG_IDT_CPMEMORY             0x000BL
#define MSG_IDT_COMPLETE_ETADIST     0x000CL
#define MSG_IDT_CO2USAGE             0x000EL
#define MSG_IDT_POIDISPLAYLIST       0x000FL
#define MSG_IDT_ROUTING_PROFILES     0x0017L
#define MSG_IDT_ROUTING_LATLONLIST   0x0018L
#define MSG_IDT_WALKINGMODE          0x0019L
#define MSG_IDT_IMAGE_DRAWER         0x001AL

Msg_IDT_MAPDATA

Returns information which contains region name and their abbreviation.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo1, rInfo2, rInfo3, rInfo4 : Unused

  • pInfo5 : Region Abbreviation

  • pInfo6 : Region Name


Msg_IDT_COUNTRIES

Returns ID, name and ISO code for the map data countries within the region – this does not represent the installed country information.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo2, rInfo3, rInfo4 : Unused

  • rInfo1: Country ID

  • pInfo5: Country Name

  • pInfo6: Country ISO-2 code


Msg_IDT_STATES

Returns name and abbreviation for the map data states within the region – this does not represent the installed country information.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • lPayload would be the CountryID. User can get the CountryID by requesting country i.e Msg_IDT_COUNTRIES.

Response

  • rInfo1, rInfo2, rInfo3, rInfo4 : Unused

  • pInfo5: State Abbreviation

  • pInfo6: State Name


Msg_IDT_POICATEGORIES

Returns ID and name for the POI categories.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo2, rInfo3, rInfo4, pInfo6 : Unused

  • rInfo1: Category ID

  • pInfo5: Category Name


Msg_IDT_ITINERARY

Returns information to the client application providing the itinerary of turn instructions and street names to the next destination.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1
enum ETurnCode
{
  EStraight = 0,
  ELeft,
  ERight,
  EBearLeft,
  EBearRight,
  ESharpLeft,
  ESharpRight,
  EUTurn,
  EWayPoint,
  EStartPoint,
  EEndPoint,
  EUKRoundAboutStraight,
  EUKRoundAboutLeft,
  EUKRoundAboutRight,
  EUKRoundAboutBearLeft,
  EUKRoundAboutBearRight,
  EUKRoundAboutSharpLeft,
  EUKRoundAboutSharpRight,
  EUKRoundAboutUTurn,
  ERoundAboutStraight,
  ERoundAboutLeft,
  ERoundAboutRight,
  ERoundAboutBearLeft,
  ERoundAboutBearRight,
  ERoundAboutSharpLeft,
  ERoundAboutSharpRight,
  ERoundAboutUTurn,
  ERightSideUTurn,
  EMergeLeft,
  EMergeRight,
  EEUOffRamp,
  EOffRamp,
  EIntermediateStop = 33
};

Request

  • No payload while requesting information

Response

  • rInfo4, pInfo6 : Unused

  • rInfo1: Stop No (-1 in it is not stop no.)

  • rInfo2: Turn code (Any value in ETurnCode)

  • rInfo3: Distance

  • pInfo5: Street name


Msg_IDT_ETADIST

Provides the complete ETA and distance for all destinations. This should be the first request for ETA and distance. For one destination or one off ETA/Dist, needs to use Msg_IDT_ETADIST

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • pInfo5, pInfo6 : Unused

  • rInfo1: Stop No

  • rInfo2: ETA (Absolute ETA in minutes since midnight)

  • rInfo3: ETA (Difference in minutes between current time and ETA)

  • rInfo4: Distance

For subsequent ETA and DIST, use Msg_IDT_COMPLETE_ETADIST

After the trip is completed, before you start a new trip, you no longer require the ETA and distance for the current trip. Use Msg_SendGenericData with Msg_IDT_RELEASE_CACHEMEMORY to release the memory.

Please note the Distance returned will be provided using the same Miles or Kilometers setting currently used within CoPilot. For current unit setting within CoPilot please refer to documentation setting Msg_IDT_DISTUNIT

Crossing Time Zones

All stops are given in local time. Therefore, for a route that contains two stops, and travels across time zones with stop A in time zone X and stop B in time zone Y, then:

  • The ETA for stop A is given in time zone X

  • The ETA for stop B is given in time zone Y


Msg_IDT_COMPLETE_ETADIST

Provides the ETA and distance for the next destination, and should be used for all subsequent requests for ETA and distance. We recommend using Msg_GetTurnDistances instead of Msg_IDT_COMPLETE_ETADIST

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • Response with Message ID “Msg_ID_ETADIST”

Msg_IDT_LANGVOICES

Returns the ID and name for all languages and voices available.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo3, rInfo4 : Unused
  • rInfo1: Language ID for the voice
  • rInfo2: Voice index
  • rInfo3: VoiceStorage (Voice is on device of not - Check eVoiceStorage in alkmsg.cs)
  • pInfo5: Language name
  • pInfo6: Voice Name

Msg_IDT_GEOCODE

If address is geocoded successfully, it will provide stop name, latitude, longitude, address errors, place errors for each geocode request or sending trip. If request is to delete the trip, lError will be Msg_GEORESULT_GENERAL.

If error in geocoding, it will provide stop name and geocode error.

This identifier will be send by CoPilot in the following 2 APIs. By using any of these API, CoPilot will send the Msg_IDT_GEOCODE along with all the description.

  1. Msg_RequestGeocode

  2. Msg_SendTrip

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10

Response

  • rInfo1 : Latitude of the stop (expressed as an integer value in millionths of a degree

  • rInfo2: Longitude of the stop (expressed as an integer value in millionths of a degree)

  • rInfo3: Place errors (It will provide detail information about parsing and mismatch of city/postcode and state). Please find the following table for detail error code.

  • rInfo4: Address errors (It will provide detail information about street parsing and lookup). Please find the following table for detail error code.

  • pInfo5: Stop Name

  • pInfo6 : Unused

Error code: Part of Msg_GenericInformationGetHeader, lError

IdentifierError CodeDescription
#define Msg_GEORESULT_GENERAL0x0000LNo error
#define Msg_GEORESULT_NODATA0x0001LNo data found
#define Msg_GEORESULT_INSUFPARAM0x0002LInsufficient parameter
#define Msg_GEORESULT_INVLDOSGRDPAR0x0003LInvalid OS grid parameter
#define Msg_GEORESULT_INVLDSTRTNAME0x0004LInvalid street name
#define Msg_GEORESULT_INVLDSTRTTYP0x0005LInvalid street type
#define Msg_GEORESULT_INVLDSTRTDIR0x0006LInvalid street directory
#define Msg_GEORESULT_INVLDSTABRV0x0007LInvalid state abbreviation
#define Msg_GEORESULT_INVLDSTZIP0x0008LInvalid state/ zip code
#define Msg_GEORESULT_INVLDCITYZIP0x0009LInvalid city /zip code
#define Msg_GEORESULT_NOTEXCTMATCH0x000ALNo exact match found
#define Msg_GEORESULT_NOMAPDATA0x000BLNo map data for given lat / long
#define Msg_GEORESULT_STATEONLY0x000CLNo city /zip
#define Msg_GEORESULT_BADZIP0x000DLPostal code in bad format
#define Msg_GEORESULT_UNKNOWNERROR0x000ELUnknown error
#define Msg_GEORESULT_DIFFADDRLATLONG0x0010LGiven Lat/long and address are >0.5 mile and CoPilot geocoded based on lat/long
#define Msg_GEORESULT_MULTIPLEMATCH0x00FFLMultiple match found, however CoPilot has chosen the best stop

Success Error code for Place errors (rInfo3):

IdentifierError ValueDescription
#define SDK_ERR_PLACE_PARSE_NOTOKEN(1<< 0)Input place is empty
#define SDK_ERR_PLACE_PARSE_STATEONLY(1<< 1)Input is missing a city and/or postal code, only has a state
#define SDK_ERR_PLACE_PARSE_BADZIP(1<< 2)Postal code in an unknown format
#define SDK_ERR_BADSTATE(1<< 3)State is in a bad format or is not found in region
#define SDK_ERR_PLACE_CALC_BADZIP(1<< 4)Postal code is in a bad format or not found in region
#define SDK_ERR_PLACE_CALC_BADCITY(1<< 5)City is in a bad format or not found in region
#define SDK_ERR_PLACE_CALC_STATEZIP(1<< 6)Postal code not found in input state/country
#define SDK_ERR_PLACE_CALC_CITYZIP(1<< 7)Postal code not found in input city
#define SDK_ERR_PLACE_CALC_NOEXACT(1<< 8)Exact match for city name not found
#define SDK_ERR_PLACE_CALC_NOZIPS(1<< 9)No postal code found for city, state/country
#define SDK_ERR_PLACE_CALC_NOGRIDS(1<<10)No addresses found for input place
#define SDK_ERR_PLACE_CALC_POBOXNOADDR(1<<11)Input has a PO box postal code but no address
#define SDK_ERR_PLACE_CALC_DIFFADDRLATLONG(1<<12)Input lat/lon is far from input address
#define SDK_ERR_PLACE_CALC_BADSPLC(1<<13)Input SPLC is bad or not found in region

Success Error code for Address errors (rInfo4):

IdentifierError ValueDescription
#define SDK_ERR_ADDR_PARSE_NOTOKEN(1 << 0)Input address is empty
#define SDK_ERR_ADDR_PARSE_NONUM(1 << 1)Input does not contain a house or building number
#define SDK_ERR_ADDR_PARSE_NONAME(1 << 2)Input does not contain a street name
#define SDK_ERR_ADDR_CALC_NUMRANGE(1 << 3)Location along street is approximate
#define SDK_ERR_ADDR_CALC_NUMPAR(1 << 4)Side of street is uncertain in location returned
#define SDK_ERR_ADDR_CALC_AFXBAD(1 << 5)Multiple errors regarding street prefix/suffix
#define SDK_ERR_ADDR_CALC_TYPBAD(1 << 6)Input street type differs from match
#define SDK_ERR_ADDR_CALC_NAMESPELL(1 << 7)Input street name spelling differs from match
#define SDK_ERR_ADDR_CALC_NAMEMATCH(1 << 8)No match found for input street name
#define SDK_ERR_ADDR_CALC_MULTOK(1 << 9)Multiple best matches found for input
#define SDK_ERR_ADDR_CALC_ZIPMATCH(1 << 10)Postal code differs from match
#define SDK_ERR_ADDR_CALC_ZIPCENT(1 << 11)Location is postal code centroid
#define SDK_ERR_ADDR_CALC_NUMUNKNOWN(1 << 12)Location along street returned is unknown

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.

  • If geocode successfully, lError will contain Msg_GEORESULT_GENERAL or Msg_GEORESULT_DIFFADDRLATLONG or Msg_GEORESULT_MULTIPLEMATCH as well contain the place errors and address errors.

  • If any error on geocode, lError will contain geocoding error except Msg_GEORESULT_GENERAL or Msg_GEORESULT_DIFFADDRLATLONG or Msg_GEORESULT_MULTIPLEMATCH. It will not contain any address or place error.


Msg_IDT_CPVERSION

Provides the CoPilot version number.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo1, rInfo2, rInfo3, rInfo4, pInfo6: Unused

  • pInfo5: CoPilot version string


Msg_IDT_CPMEMORY

Returns CoPilot memory usage information.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo4, pInfo5, pInfo6: Unused

  • rInfo1: Memory Load between 0 and 100 (0 indicates no memory consumption and 100 indicates full memory consumption)

  • rInfo2: Available physical memory(KB) to CoPilot

  • rInfo3: Available virtual memory(KB) to CoPilot

Example

//Request to retrieve county list
Msg_RequestGenericInformation(MSG_IDT_COUNTRIES, 0);

//Receiving side either by callback or through message queue //mechanism
if ( msgID == MSG_ID_MSG_ID_GenericInformation)
{
    long lMsgId = Msg_GenericInformationParse (pBytes,bytes);

    //Get Header information like identifier, error, count
    Msg_GenericInformationGetHeader (lMsgId, &rIdentifier, &rError, &rCount)

    switch (rIdentifier)
    {
        case MSG_IDT_MAPDATA;
        break;

        case MSG_IDT_STATES;
        break;

        case MSG_IDT_COUNTRIES:
        //Retrieve individual information
        for(int index=0; index<rCount; index++)
        {
            Msg_GenericInformationGetDetails(lMsgId, index,_.);
        }
        break;
    }
    Msg_ParserDelete(lMsgId);
}

Msg_IDT_ROUTING_PROFILES

Retrieve all the profiles in CoPilot. Use Msg_SendGenericTextData with Msg_IDT_LOADPROFILE to load the profile.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo1: Value 1 to show that current profile is active in CoPilot else -1

  • rInfo6: Name of the Routing Profile stored in CoPilot

  • rInfo2, rInfo3, rInfo4, rInfo6 : Unused


Msg_IDT_ROUTE_LATLONLIST

Retrieve lat/lon values (expressed as an integer value in millionths of a degree) for a calculated route in CoPilot. This could be used to plot the planned route onto an external mapping system for later review of CoPilot’s planned route.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Request

  • No payload while requesting information

Response

  • rInfo1: Latitude

  • rInfo2: longitude

  • rInfo3: Unused

  • rInfo4: Unused

  • pInfo5: Unused

  • pInfo6: Unused

Note

For a calculated long route, a high number of lat/lon pairs will be returned by CoPilot. It is recommended that one should not iterate through every lat/lon pair as it will not add value to the data representation and will negatively impact performance. For long routes one can programmatically iterate every nth lat/lon pair. The table below illustrates the number of lat/lon pairs returned for routes of varying distances.

This API can be use in coordination with Msg_SendManagedRoute. This API can retrieve lat/long for the given route which can be pass to Msg_SendManagedRoute to verify the that Msg_SendManagedRoute follows exactly same route for test environment.

TRIPTrip Calculation TimeMileage in milesETA in hoursLAT/LONG generatedTime to generate Lat/Long
London Bloomsbury to Hatton Garden2 s0.800:0343instantly
London to Glasgow10 s399.907:16239030 s
Berlin to Toulouse1 min1071.118:3950372 min

Msg_IDT_IMAGE_DRAWER

This identifier provides result of the API Msg_DrawImageAtCoordinates, Msg_DeleteAllCategory and Msg_DeleteCategory which uses to add/delete the image drawer category to the CoPilot.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10

Response

  • rInfo1: Error code. Please see the following description
  • rInfo2: Unused
  • rInfo3: Unused
  • rInfo4: Unused
  • pInfo5: Unused
  • pInfo6: Unused

Error codes

#define Msg_IMAGE_DRAWER_SUCCESS          0x0000L
#define Msg_IMAGE_DRAWER_FAILED           0x0001L
#define Msg_IMAGE_DRAWER_CATEGORY_EXIST   0x0002L
#define Msg_IMAGE_DRAWER_INVALID_CATEGORY 0x0003L
#define Msg_IMAGE_DRAWER_INVALID_POINTS   0x0004L
#define Msg_IMAGE_DRAWER_INVALID_IMAGE    0x0005L
Error CodeDescription
Msg_IMAGE_DRAWER_SUCCESSImage drawer category added/deleted successfully.
Msg_IMAGE_DRAWER_FAILEDCoPilot failed to delete single or all image drawer category.
Msg_IMAGE_DRAWER_CATEGORY_EXISTbOverWrite pass as a false and image drawer category is already exist, it will return this error code.
Msg_IMAGE_DRAWER_INVALID_CATEGORYCategory name is invalid or blank. For Msg_DeleteCategory, category is not exist in CoPilot.
Msg_IMAGE_DRAWER_INVALID_POINTSFormat of the lat/longs points are incorrect or lat/longs are not being passed
Msg_IMAGE_DRAWER_INVALID_IMAGEImage name is incorrect or not in proper format.

Msg_IDT_POLYGON_PROPERTY

This identifier provides result of the API Msg_GetPolygonSetProperty, Msg_GetPolygonProperty, Msg_SetPolygonSetProperty and Msg_SetPolygonProperty which uses to set/get the property of the PolygonSet and Individual Polygon.

Supported SinceMinimum Operating System
CoPilot 9.6Windows 10

Response

  • rInfo1: Identifier. Please see the following description.
  • rInfo2: Result of the operation. Please see the following description.
  • rInfo3: Unused
  • rInfo4: Unused
  • pInfo5:
  • pInfo6: Unused

Identifier

#define Msg_IDT_GETPOLYGONSETPROPERTY_RESULT   0x0001
#define Msg_IDT_GETPOLYGONPROPERTY_RESULT      0x0002
#define Msg_IDT_SETPOLYGONSETPROPERTY_RESULT   0x0003
#define Msg_IDT_SETPOLYGONPROPERTY_RESULT      0x0004
Error CodeDescription
Msg_IDT_GETPOLYGONSETPROPERTY_RESULTThis will be return in context of Msg_GetPolygonSetProperty.
Msg_IDT_GETPOLYGONPROPERTY_RESULTThis will be return in context of Msg_GetPolygonProperty.
Msg_IDT_SETPOLYGONSETPROPERTY_RESULTThis will be return in context of Msg_SetPolygonSetProperty.
Msg_IDT_SETPOLYGONPROPERTY_RESULTThis will be return in context of Msg_SetPolygonProperty.

Results

#define Msg_IDT_POLYGONSUCCESS           0
#define Msg_IDT_POLYGONOBJNOTFOUND      -1
#define Msg_IDT_POLYGONPROPNOTFOUND     -2
#define Msg_IDT_POLYGONPROPVALUEINVALID -3
Error CodeDescription
Msg_IDT_POLYGONSUCCESSSuccess
Msg_IDT_POLYGONOBJNOTFOUNDRequested polygon not found in CoPilot
Msg_IDT_POLYGONPROPNOTFOUNDRequested polygon property not found in CoPilot
Msg_IDT_POLYGONPROPVALUEINVALIDInvalid property value.

Msg_CreateGenericInformation

Creates a generic message with a particular ID to be sent from client application to CoPilot to change the current settings for language, voice, lane assist and POI categories to be displayed.

Create the generic data message (Msg_ID_GenericInformation) to be sent to CoPilot.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Note

This call should be followed by Msg_GenericInformationAddDetail and then by Msg_SendGenericInformation

Use Msg_ParserDelete to free the memory when finished with ParserID.

Syntax (Prototyped in alkmsg.h)

long Msg_CreateGenericInformation (unsigned long lIdentifier)

Parameters

lIdentifier: Unique identifier whose value is being sent.

Acceptable Values

Identifier:

#define Msg_IDT_LANEASSIST        0x0049L
#define Msg_IDT_SPEEDLIMIT        0x004CL
#define Msg_IDT_CURRENT_LANGVOICE 0x0008L
#define Msg_IDT_POIDISPLAYLIST    0x000FL
#define Msg_IDT_WALKINGMODE       0x0019L

Return Value

Long value (lMsgID) that is to be used in the Msg_GenericInformationAddDetail and Msg_SendGenericInformation call.


Msg_GenericInformationAddDetail

Encodes the information and adds it to the Msg ID returned from the Msg_CreateGenericInformation. Please note this API is Available within CoPilot V9 and CoPilot V10, further details are included within each parameter detailing the CoPilot versions that they are supported in.

Add details to the data buffer created using Msg_CreateGenericInformation.

Note

This call should be followed by Msg_SendGenericInformation.

Syntax (Prototyped in alkmsg.h)

long Msg_GenericInformationAddDetail(unsigned long lMsgId,
   long rInfo1,
   long rInfo2,
   double rInfo3,
   double rInfo4,
   const char *pInfo5,
   const char *pInfo6)

Parameters

ParameterDescription
lMsgIDSame ID that is returned by Msg_CreateGenericInformation
rInfo1Long value associated with the message (lMsgID)
rInfo2Long value associated with the message (lMsgID)
rInfo3Double value associated with the message (lMsgID)
rInfo4Double value associated with the message (lMsgID)
pInfo5Text value associated with the message (lMsgID)
pInfo6Text value associated with the message (lMsgID)

MSG_IDT_SPEEDLIMIT

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

rInfo1: Corresponds to show speed limit in CoPilot speed limit setting screen Query = -1 [Query the current setting] Turn Off = 0 [Don’t show speed limit] Turn On = 1 [Always Show Speed Limit]

rInfo2: Corresponds to show speed warning in CoPilot setting screen Query = -1 [Query the current setting] Turn Off = 0 [Don’t show speed limit warning] Turn On = 1 [Always Show Speed Limit warning]

rInfo3: Corresponds to allowed values for speed warning distance

rInfo4: Corresponds to Sound warning in CoPilot speed limit setting screen Query = -1 [Query the current setting] Turn Off = 0 [Don’t show speed limit sound warning] Turn On = 1 [Always Show Speed limit sound warning]

pInfo5, pInfo6: null (not used)

Return Value

Returns the message with Msg_IDT_SPEEDLIMIT identifier containing current settings.

Use Msg_GenericInformationParse, Msg_GenericInformationGetHeader, Msg_GenericInformationGetDetail and Msg_ParserDelete.

rInfo1: current speed limit settings in CoPilot

Turn Off = 0 [Don’t show speed limit] Turn On = 1 [Always Show Speed Limit]

rInfo2: current speed warning setting CoPilot

Turn Off = 0 [Don’t show speed limit warning] Turn On = 1 [Always Show Speed Limit warning] rInfo3: current speed limit threshold setting rInfo4: current speed limit Sound warning setting in CoPilot Turn Off = 0 [Don’t use speed limit sound warning] Turn On = 1 [Always use Speed limit sound warning]

pInfo5, pInfo6: null (not used)

Note

  1. if rInfo1, rInfo2 , rInfo3 or rInfo4 is -1 then it returns the current Settings

  2. Use Msg_Subscribe with (Msg_Id_OverSpeedLimitEvent) in the application to get the message as an event .

// For querying the acceptable value by CoPilot
uint lMsgID = (uint) Msg.Msg_CreateGenericInformation(Msg.MSG_IDT_SPEEDLIMIT);
Msg.Msg_GenericInformationAddDetail(lMsgID, -1, -1, -1, 0, null, null);
Msg.Msg_SendGenericInformation(lMsgID, -1, -1)
Msg.Msg_ParserDelete(lMsgID);

Please refer to the Sample Application for further explanation.


Msg_IDT_CURRENT_LANGVOICE

Enables the ability to change the current language and voice set within CoPilot.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Parameters

ParameterDescription
rInfo1language ID
rInfo2not used
rInfo3not used
rInfo4not used
rInfo5not used
rInfo6“voice name”

Error Codes

rError: -1 If user selected the voice which is not downloaded on device it will give this error rError: 0 Language/voice successfully set

Note

Use Msg_IDT_LANGVOICES for finding the acceptable values of language ID and “voice name” [Voice name is case sensitive]

Example –

Msg.Msg_RequestGenericInformation(Msg.MSG_IDT_LANGVOICES, -1, -1, -1);

Pass langID as -1 for querying current settings

Return Value

Use Msg_GenericInformationParse, Msg_GenericInformationGetHeader, Msg_GenericInformationGetDetail and Msg_ParserDelete. rInfo1: language ID rInfo2: voice ID rInfo3: not used rInfo4: not used rInfo5: “Language name” rInfo6: “voice name”

Example –

private void OnGenericInformation(uint pData, uint bytes)
{
    uint lMsgID = (uint)Msg.Msg_CreateGenericInformation(Msg.MSG_IDT_LANEASSIST);
    Msg.Msg_GenericInformationAddDetail(lMsgID, -1, 0, 0, 0, null, null);
    Msg.Msg_SendGenericInformation(lMsgID, -1, -1);
    Msg_ParserDelete(lMsgID);
}

Please refer to the Sample Application for further explanation.


Msg_IDT_LANEASSIST

Enables the ability to change the current setting to show or not show the Lane Assist information.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Parameters

Parameter for Msg_GenericInformationAddDetail

ParameterDescription
lMsgIDlMsgID returned by Msg_CreateGenericInformation (identifier Msg_IDT_LANEASSIST)
rInfo10 if don’t show lane assist 1 if show lane assist -1 it will return current lane assist settings
rInfo2not used (pass 0)
rInfo3Value for ShowLaneAssistDistances
rInfo4Value for HindLaneAssistDistances
rInfo5Not used (pass null)
rInfo6Not used (pass null)

Return Value

Returns the message with Msg_IDT_LANEASSIST identifier containing current settings

Use Msg_GenericInformationParse, Msg_GenericInformationGetHeader, Msg_GenericInformationGetDetail and Msg_ParserDelete.

rInfo1. rInfo3 and rInfo 4 will have the return value.

Note – For acceptable values of rInfo3 and rInfo4, use

private void OnGenericInformation(uint pData, uint bytes)
{
uint MsgID = (uint)Msg.Msg_GenericInformationParse(pData, (uint)bytes);
Msg.Msg_GenericInformationGetHeader(MsgID, out identifier, out error, out itemCount);
Msg.Msg_GenericInformationGetDetails(MsgID, 1, out languageVoice.languageID, out languageVoice.voiceID,
                                     out fTemp, out fTemp, language, 100, voice, 100);

Msg.Msg_ParserDelete(MsgID);
}

Please refer to the Sample Application for further explanation.


Msg_IDT_POIDISPLAYLIST

Enables the ability to change the current settings for POI categories being displayed on screen to the end user.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Parameters

Parameter for Msg_GenericInformationAddDetail

ParameterDescription
lMsgIDlMsgID returned by Msg_CreateGenericInformation (identifier Msg_IDT_LANEASSIST)
rInfo1POI Category ID
rInfo20 Don’t Display Category 1 Display Category
rInfo3Not used
rInfo4Not used
rInfo5Not used (pass null)
rInfo6Not used (pass null)

If the client application needs to query the current POI list being displayed, please do not use Msg_GenericInformationAddDetail. Instead you should use CreateGenericInformation followed by Msg_SendGenericInformation.

Return Value

returns the message with Msg_IDT_POIDISPLAYLIST identifier containing current settings

Use Msg_GenericInformationParse, Msg_GenericInformationGetHeader, Msg_GenericInformationGetDetail and Msg_ParserDelete.

Note

private void OnGenericInformation(uint pData, uint bytes)
{
    //Example: query current POI display list with flag
    uint lMsgID = (uint)Msg.Msg_CreateGenericInformation(Msg.MSG_IDT_POIDISPLAYLIST);
    Msg.Msg_GenericInformationAddDetail(lMsgID, 5, 1, 0, 0, null, null);
    Msg.Msg_SendGenericInformation(lMsgID, -1, -1);
    Msg.Msg_ParserDelete(lMsgID);
}

Please refer to the Sample Application for further explanation.


Msg_IDT_WALKINGMODE

This identifier allows to query the current state of walking mode as well set the walking mode in CoPilot.

Supported SinceMinimum Operating System
CoPilot 9.2, Deprecated CoPilot 10Windows 10, Android 4.1

Parameters

Parameter for Msg_GenericInformationAddDetail

ParameterDescription
lMsgIDlMsgID returned by Msg_CreateGenericInformation (identifier Msg_IDT_WALKINGMODE)
rInfo1Walking mode status -1 Query the current status 1 Set the CoPilot in walking mode
rInfo2Breadcrumb Status -1 Query the current status 0 Don’t Show walking Breadcrumb 1 Show walking Breadcrumb
rInfo3Not used
rInfo4Not used
rInfo5Not used (pass null)
rInfo6Not used (pass null)

Return Value

Returns the message with Msg_IDT_WALKINGMODE identifier containing current settings

Use Msg_GenericInformationParse, Msg_GenericInformationGetHeader, Msg_GenericInformationGetDetail and Msg_ParserDelete.

Note

You can not disable the walking mode. In order to change from walking mode to other profile, please use Msg_SendRoutingProfile or Msg_SendTruckRoutingProfileEx.

Please refer to the Sample Application for further explanation.


Msg_IDT_POI_ALERT_SETTINGS

This identifier allows to query the current state of poi alert settings as well as set POI alert settings in CoPilot.

Supported SinceMinimum Operating System
CoPilot 9.6Windows 10, Android 4.1

Parameters

Parameter for Msg_GenericInformationAddDetail

ParameterDescription
lMsgIDlMsgID returned by Msg_CreateGenericInformation (identifier Msg_IDT_POI_ALERT_SETTINGS)
rInfo1A POI category ID for which to enable POI alerts
rInfo2Whether POI alert settings are enabled or disabled -1 Query the current status 0 Disable POI alerts 1 Enable POI alerts
rInfo3Whether to alert of POIs along the route or near the route -1 Query the current status 0 On Route 1 Near Route
rInfo4The distance away a POI must be before an alert for it is sent -1 Query the current setting 0 2/10ths mile 1 ½ mile 2 1 mile 3 3 miles 4 10 miles 5 26 miles 6 ½ kilometer 7 1 kilometer 8 2 kilometers 9 5 kilometers 10 16 kilometers 11 40 kilometers
rInfo5Not used (pass null)
rInfo6Not used (pass null)

Return Value

Returns the message with Msg_IDT_POI_ALERT_SETTINGS identifier containing current settings

Use Msg_GenericInformationParse, Msg_GenericInformationGetHeader, Msg_GenericInformationGetDetail and Msg_ParserDelete.


Msg_IDT_SUSPEND_NAVIGATION

Suspends navigation in CoPilot. Guidance will stop and the current position will not be updated, but the GPS receiver will continue to run in the background.

Supported SinceMinimum Operating System
CoPilot 9.6Windows 10, Android 4.1
#define Msg_IDT_SUSPEND_NAVIGATION = 0x001DL

Parameters

Parameter for Msg_GenericInformationAddDetail

ParameterDescription
lMsgIDlMsgID returned by Msg_CreateGenericInformation (identifier Msg_IDT_SUSPEND_NAVIGATION)
rInfo10 to enable navigation, 1 to disable navigation

Map Feedback

Msg_IDT_MAPFEEDBACK_GET

This identifier will return map feedbacks stored on the device. It should be sent through Msg_SendGenericData and a return value will be returned through Msg_GenericTextDataGet.

The return codes are received by setting a callback with Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericTextData, true, false, delOnGenericTextData, Msg.callingConvention.concention_stdcall); and listening for MSG_IDT_MAP_FEEDBACK_GET and unwrapping the payload.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

public static native int Msg_SendGenericData(int lIdentifier, int lPayload, int lDestID, int lSrcID);
long Msg_SendGenericData(long lIdentifier, long lPayload, long lDestID = CONN_ID_NONE, long lSrcID = CONN_ID_NONE);
  public static extern int Msg_SendGenericTextData(int lIdentifier, int lPayload, byte[] strPayload, int stringLen, int lRequestID, int lDestID, int lSrcID, bool bAck);

Parameters

ValueDescription
MSG_IDT_MAP_FEEDBACK_GETGet all cached map feedbacks from device

Return Values

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

Return Codes

ValueDescription
MSG_IDT_MAP_FEEDBACK_GET_SUCCESSSuccessfully get all cached map feedbacks
MSG_IDT_MAP_FEEDBACK_GET_JSON_PARSE_ERRORWhile retrieving cached map feedbacks, some json is invalid
MSG_IDT_MAP_FEEDBACK_GET_NO_FEEDBACK_CACHEDNo map feedbacks found on the device
MSG_IDT_MAP_FEEDBACK_GET_NO_GENERIC_ERRORAny error other than above three

Note: that even you receive MSG_IDT_MAP_FEEDBACK_GET_JSON_PARSE_ERROR, you may still get those feedbacks that are valid json. The returned json string will be delivered through Msg_GenericTextDataGet upon receiving the callback. See the sample code below to see how it works. The format of returned JSON string will be: {“mapfeedbacks”:[]} “mapfeedbacks” object contains an array of JSON map feedback requests you previously made

Sample Code

// Set up GenericTextData callback
Msg.delCallback delOnGenericTextData;
delOnGenericTextData = new Msg.delCallback(OnGenericTextData);
Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericTextData, true, false, delOnGenericTextData,    Msg.callingConvention.convention_stdcall);

// Send a request of getting map feedbacks
Msg.Msg_SendGenericData(Msg.MSG_IDT_MAP_FEEDBACK_GET, -1, -1, -1);

// Process the callback
void OnGenericTextData(uint pData, uint bytes)
{
  int identifier;
  int payload;
  int iRequestID;
  int iStrLen;

   string genText = Msg.Msg_GenericTextDataGet(pData, bytes, out identifier, out payload, out iRequestID, out iStrLen);

  switch (identifier)
  {
    case Msg.MSG_IDT_MAP_FEEDBACK_GET:
    {
      if (payload == Msg.MSG_IDT_MAP_FEEDBACK_GET_SUCCESS || payload == Msg.MSG_IDT_MAP_FEEDBACK_GET_JSON_PARSE_ERRO)
      {
        // genText is your returned map feedbacks
        DoSomething()
      }
    }
    break;
    default:
    break;
  };
}

Msg_IDT_MAP_FEEDBACK_CLEAR

This API is used to delete map feedback stored on a device.

The return codes are received by setting a callback with Msg.Msg_UpdateOptions(Msg.MSG_ID_GenericTextData, true, false, delOnGenericTextData, Msg.callingConvention.concention_stdcall); and listening for MSG_IDT_MAP_FEEDBACK_GET and unwrapping the payload.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

public static native int Msg_SendGenericData(int lIdentifier, int lPayload, int lDestID, int lSrcID);
long Msg_SendGenericData(long lIdentifier, long lPayload, long lDestID = CONN_ID_NONE, long lSrcID = CONN_ID_NONE);
alkmsg.cs
public static extern int Msg_SendGenericData(int lIdentifier, int lPayload, int lDestID, int lSrcID);

Parameters

ValueDescription
MSG_IDT_MAP_FEEDBACK_CLEARClear all cached map feedbacks from device

Return Values

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

Return Codes

ValueDescription
MSG_IDT_MAP_FEEDBACK_CLEAR_SUCCESSSuccessfully delete all cached map feedbacks
MSG_IDT_MAP_FEEDBACK_CLEAR_FAILFailed to delete cached map feedbacks

Sample Code

Msg.Msg_SendGenericData(Msg.MSG_IDT_MAP_FEEDBACK_CLEAR, -1, -1, -1);

Motion Lock

Msg_IDT_MOTIONLOCK

Motion lock is enabled when traveling above a set speed the interaction with the CoPilot UI is restricted. Different modes dictate the level of restriction which is enforced when traveling above a defined threshold speed.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

int Msg_SendGenericData(int lIdentifier, int lPayload, int lDestID, int lSrcID);

Parameters

ParameterValueDescription
lIdentifierMSG_IDT_MOTIONLOCK_MODECHNGChange the motion lock mode
lIdentifierMSG_IDT_MOTIONLOCK_MODEGet current motion lock mode
lIdentifierMSG_IDT_MOTIONLOCK_SPEEDTHRESHOLDCHNGChange the motion lock engage speed limit
lIdentifierMSG_IDT_MOTIONLOCK_SPEEDTHRESHOLDGet current motion lock engage speed limit
lPayloadALL_UI_UNLOCKUnlock all UI, do not lock any UI elements when traveling above the threshold speed.
lPayload
lPayload
lPayload
lPayload
ModeDescription
ALL_UI_UNLOCKUnlock all UI, do not lock any UI elements when traveling above the threshold speed.
ALL_UI_LOCKLock all UI when traveling above the defined threshold speed. This will also disable all pop ups except for the destination arrival pop up. All action required pop-ups have a default decision which will be followed if they are shown.
ONLY_DRIVING_UI_ACCESSOnly allow access to driving functions. This will Lock access to the entire UI with the exception of the following:

Driving Menu → 2D/3D
Driving menu → Directions/Safety
Driving Menu → Clear Destination
Driving Menu → Close
Zoom buttons on map
Reset to current location button on map
POI Alert button on map
Popups
Map drag/swipe/pan/multi touch
Sound mute button
Mapsure button on navigation dialog

This is the default mode available within the CoPilot UI.

ONLY_DRIVING_UI_ACCESS_EXTENDONLY_DRIVING_UI_ACCESS plus access to the following (disable keyboard):

Driving Menu → Find POIs
Main POI categories
Search All
More Categories
Driving Menu → My Route → Alternate
Go (Green circular button on plan trip screen)
Traffic Bar and traffic refresh button
Buttons in flow traffic map except for the setting button

PASSENGER_MODEAllow a temporary disablement of Motion Lock when used by a passenger. Motion Lock settings should be resumed upon restarting CoPilot.
When this mode is set, all UI will be unlocked. Once the application is re-launched CoPilot will resume in the previous MotionLock mode.
To enable this mode the following configuration is required to be set within the user.cfg:

[User Settings]
“EnablePassengerMode”=1

Once this is set this mode being passed will replicate the user selecting the passenger mode button within the UI.


Msg_SendGenericInformation

Sends a generic message with a particular ID to be sent from client application to CoPilot to change the current settings for language, voice, lane assist and POI categories to be displayed.

Sends the data buffer created by Msg_CreateGenericInformation

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_SendGenericInformation(unsigned long lMsgId,
                                long lDestID,
                                long lSrcID)

Parameters

ParameterDescription
lMsgIdSame ID that is returned by Msg_CreateGenericInformation
lDestID-1
lSrcID-1

Return Value = 1 if successful otherwise 0

Note

This should be used with Msg_CreateGenericInformation and Msg_GenericInformationAddDetail

Example

private void OnGenericInformation(uint pData, uint bytes)
{
    uint lMsgID = (uint)Msg.Msg_CreateGenericInformation(Msg.MSG_IDT_LANEASSIST);
    Msg.Msg_GenericInformationAddDetail(lMsgID, -1, 0, 0, 0, null, null);
    Msg.Msg_SendGenericInformation(lMsgID, -1, -1);
    Msg_ParserDelete(lMsgID);
}

Please refer to the Sample Application for further explanation.


Msg_ConfigSetIntVal

To configure CoPilot settings that are saved as a file in user.cfg – contained in program files/copilot folder. This API is used to set the integer or boolean variables values. For Boolean use 0 or 1

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ConfigSetIntVal(const char* pSection,
   const char* pVariable,
   int iValue);

Parameters

ParameterDescription
pSectionName of the section
pVariableName of the variable
iValueString Value of the variable that needs to be set.

Example

Msg_ConfigSetIntVal(“SDK”, “AutomateMapUpdate”, 0);

This will appear in user.cfg as follows

[SDK]

“AutomateMapUpdate”=0

Return Value

  • -1 (Signifies Error in sending);

Any Positive values signifies success.

To receive a response from CoPilot use Msg_AddConfigCallback.


Msg_ConfigSetStrVal

In order to configure CoPilot settings that are saved as a file in user.cfg – contained in program files/CoPilot folder. This API is used to set the string variables value.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ConfigSetStrVal(const char* pSection,
   const char* pVariable,
   const char* sValue);

Parameters

ParameterDescription
pSectionName of the section
pVariableName of the variable
sValueString Value of the variable that needs to be set.

Return Value

  • -1 (Signifies Error in sending);

Any Positive values signifies success.

To receive a response from the CoPilot use Msg_AddConfigCallback.


Msg_ConfigGetIntVal

In order to configure CoPilot settings that are saved as a file in user.cfg – contained in program files/CoPilot folder. This API is used to retrieve the integer or boolean variables values.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ConfigGetIntVal(const char* pSection, const char* pVariable);

Parameters

ParameterDescription
pSectionName of the section
pVariableName of the variable

Return Value

  • -1 (Signifies Error);

Any Positive values signifies success.

Client Application will need to set the callback function to using Msg_AddConfigCallback to receive response from CoPilot.


Msg_ConfigGetStrVal

In order to configure CoPilot settings that are saved in user.cfg – contained in program files/CoPilot folder. This API is used to retrieve the string variables value.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_ConfigGetStrVal(const char* pSection, const char* pVariable);

Parameters

ParameterDescription
pSectionName of the section
pVariableName of the variable

Return Value

  • -1 (Signifies Error);

Any Positive values signifies success.

Client Application will need to set the callback function to using Msg_AddConfigCallback to receive response from CoPilot.


Msg_AddConfigCallback

This is used to add a callback to receive the messages from CoPilot when setting or getting the values using Msg_ConfigSetIntVal, Msg_ConfigSetStrVal, Msg_ConfigGetIntVal, Msg_ConfigGetStrVal.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_AddConfigCallback (void *fnProcessMsg, callingConvention convention =
convention_default);

Parameters

ParameterDescription
pfnProcessMsgcallback function of type MsgConfigRspCallback
conventionCalling convention Managed Apps (.Net client application) should use convention_stdcall Other apps including native should use convention_default

For Android and using JNI layer

Syntax (Prototyped in AlkMsg.java)

long Msg_AddConfigCallback (String callbackFunctionName,
   int convention,
   Object callBackObj);

Parameters

ParameterDescription
callbackFunctionNamecallback function name of type MsgConfigRspCallback
conventionCalling convention. Should use convention_default.
callBackObjPass the object of the class which implemented CallbackFunctionName method so JNI layer will call this method once message arrived.

Return Value

  • -1 - (Signifies that there was an error);

  • 0 or any positive value (Signifies that value is set successfully)

Enum

enum callingConvention
{
convention_default,
convention_cdecl,
convention_stdcall
};

Msg_ConfigRspCallback

This is the definition of the callback function for receiving response from CoPilot when using Msg_ConfigSetIntVal, Msg_ConfigSetStrVal, Msg_ConfigGetIntVal, Msg_ConfigGetStrVal

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

typedef void (_CONVENTION *MsgConfigRspCallback) (const char* pSection,
   const char* pVariable,
   const int iValue,
   const char* pValue);

For Android and using JNI layer

Syntax (Prototyped in AlkMsg.java)

void MsgConfigRspCallback ( String pSection,
   String pVariable,
   int iValue,
   String pValue);

Parameters

ParameterDescription
pSectionName of the section (Should be same as used by Msg_ConfigSetIntVal, Msg_ConfigSetStrVal, Msg_ConfigGetIntVal, Msg_ConfigGetStrVal while sending request to CoPilot)
pVariableName of the variable (Should be same as used by Msg_ConfigSetIntVal, Msg_ConfigSetStrVal, Msg_ConfigGetIntVal, Msg_ConfigGetStrVal while sending request to CoPilot)
iValueCurrent value (will be -1 if the request is for string value)
pValueCurrent Value (will be empty if the request is for int/bool value)

Possible Values that can be set using Config APIs

DescriptionSection HeaderSection StringDefault ValueOptionsAdditional Information
Hide Button[Application]“ButtonStateHide”=0disable=1, hide=2
Quit Button[Application]“ButtonStateQuit”=0disable=1, hide=2
Quickstart Launch menu[Application]“HomeScreen2”=popup_startmenu“#default” to disable
Disable warning pop up messages[User Settings]“ShowPopups”=TRUE=0 to disable
Sign Post view[User Settings]“SignPostView”=1=0 to disable the signpost information
Safety Cameras[Safetycam]“Enabled”=0=1 to enable
Speed Limit display[Speed Warnings]“DisplaySpeedLimit”=0=2 always display
Speed Limit over speed warning[Speed Warnings]“SpeedWarningThreshold”=10= mph/kph above the speed limit warning to be displayed
Imperial / Metric[User Settings]“DistUnits”=0=1 metric
[Graphics]“SpriteAnimations”=1=0 To disable
Vehicle Type at Launch[User Settings]“TruckModeAtLaunch”=0=1 To always launch in Truck
CoPilot position X[Graphics]“ScreenXPos”=0Only required for CoPilot Laptop version. Other platforms use ALK_StartCoPilotEx
CoPilot position Y[Graphics]“ScreenYPos”=0Only required for CoPilot Laptop version. Other platforms use ALK_StartCoPilotEx
Screen resolution X[Graphics]“ForceScreenX”=240Only required for CoPilot Laptop version. Other platforms use ALK_StartCoPilotEx
Screen resolution Y[Graphics]“ForceScreenY”=320Only required for CoPilot Laptop version. Other platforms use ALK_StartCoPilotEx
GPS Port Number[GPSInfo]“PortNum”=
GPS Baud rate[GPSInfo]“BaudRate”=
Audio announcement ‘Welcome to CoPilot’[Application]“PlayWelcome”=1=0 disable
Disable automatic downloads of map updates[SDK]“AutomateMapUpdate”=1=0 disable
Boolean
Provide notification once user is X distance away from destination[SDK]“NotificationXDist”=0= N N is going to be any integer value in multiplication of 10.If user want to have notification at 0.3 miles away from destination, user need to set 3 If user want to have notification at 1 mile away from destination then user need to pass 10.
Backlight control[User Settings]“Backlight”=0ON WITH GPS= 0, ON ALWAYS = 1 ON NEAR TURN =2 NEVER ON =3

Msg_GetVersionInfo

Decodes the version information received from CoPilot in response to a Msg_RequestVersionInfo() call. In order to receive a response from Msg_RequestVersionInfo(), establish a callback using Msg_UpdateOptions() with message ID Msg_ID_VersionInfo, and then use this API to decode the version information.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

SDK_EXPORT long _CONVENTION Msg_GetVersionInfo(const void *pBuffer,
   unsigned long lBufLen,
   char *pCopilotVersion,
   unsigned long lCopilotVersionLen,
   char* pDataVersion,
   unsigned long lDataVersionLen,
   char *pCityVersion,
   unsigned long lCityVersionLen,
   char *pPOIVersion,
   unsigned long lPOIVersion);

Parameters

ParameterDescription
pBufferThe message buffer passed by the system to the user-specified callback function, set by Msg_UpdateOptions().
lBufLenThe size of the message buffer in bytes, passed by the system to the user specified callback function, set by Msg_UpdateOptions().
pCopilotVersionA user-allocated buffer to store CoPilot version
lCopilotVersionLenLength of the buffer to hold CoPilot version
pDataVersionA user-allocated buffer to store data version
lDataVersionLenLength of buffer to hold data version
pCityVersionA user-allocated buffer to store city version
lCityVersionLenLength of buffer to hold city version
pPOIVersionA user-allocated buffer to store POI version
lPOIVersionLenLength of buffer to hold POI Version

Return Value

  • = 0 Failed

  • 0 Success


Msg_RequestVersionInfo

This API is used to request CoPilot, Data, City and POI version information. To receive the response, establish a callback using Msg_UpdateOptions() for message ID Msg_ID_VersionInfo, and then within the callback use Msg_GetVersionInfo() to decode the version information.

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
lDestIDAlways use CONN_ID_NONE
lSrcIDAlways use CONN_ID_NONE

Return Value

  • = 0 - Failed

  • 0 - Success


Msg_ID_VoiceEvent

Related to Msg_Subscribe . Raises an event with message identifier Msg_ID_VoiceEvent, when CoPilot voice instruction is being played. See also Msg_IDT_TURNINSTRUCTIONALERT

Supported SinceMinimum Operating System
CoPilot 9.2Windows 10, Android 4.1

Msg_IntegrateCustomPOI

This API is used to draw custom POIs in JSON format on the map.

Supported SinceMinimum Operating System
CoPilot 10.9.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

long Msg_IntegrateCustomPOI(const char* pJson);
alkmsg.cs
  public static extern int Msg_IntegrateCustomPOI (byte[] json);

Parameters

ValueDescription
pJsonComplete contents of a JSON message describing CoPilot POI sets. This will expect preprocessed POI images for each of the categories.

JSON Example

[
  {
    "Name": "my set name",
    "Persist": false,
    "Replace": true,
    "Categories": [
      {
        "Name": "Custom Fuel",
        "MaxZoomLevel": 4,
        "Options": 21
      },
      {
        "Name": "Custom Restaurant",
        "MaxZoomLevel": 4,
        "Options": 21
      }
    ],
    "Places": [
      {
        "Address": {
          "StreetAddress": "14807 Crain Hwy",
          "City": "Clinton",
          "Zip": "20735",
          "State": "MD",
          "County": null
        },
        "Coords": {
          "Lat": "38.6825",
          "Lon": "-76.87278"
        },
        "PlaceName": "My Restaurant",
        "CategoryName": "Custom Restaurant",
        "Phone": ""
      },
      {
        "Address": {
          "StreetAddress": "1720 Route 309",
          "City": "Coopersburg",
          "Zip": "18036",
          "State": "PA",
          "County": null
        },
        "Coords": {
          "Lat": "40.50306",
          "Lon": "-75.38667"
        },
        "PlaceName": "My Fuel Stop",
        "CategoryName": "Custom Fuel",
        "Info": "",
        "Phone": ""
      }
    ]
  }
]

Return Values

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

To receive return codes the 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_IMPORTPOISET_RESULT, the return values are the payload for that callback.

Return Codes

ValueDescription
MSG_IMPORT_POI_SET_SUCCESSSuccessful in sending the request to CoPilot.
MSG_IMPORT_POI_SET_JSON_PARSE_ERRORJSON parsing failed - ensure a valid json object is being passed
MSG_IMPORT_POI_SET_INVALID_POI_JSONJSON has missing/incomplete fields required for POI integration
MSG_IMPORT_POI_SET_FAILEDGeneral fail code if POI set did not import

POI JSON field description

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

  • Set - (array)
    • Name - (string) - The unique set name; not visible anywhere in CoPilot, used for organizational purposes.
    • Persist - (bool) Whether the place set and all its data will be serialized to disk and persist through a restart of the CoPilot application. Setting this to false will keep the set in-memory only, and significantly improve the performance of this API by eliminating disk I/O.
    • Replace - (bool) Whether an existing set with this name will be replaced (all places will be deleted before adding the new places) or whether the new places will be appended to the current set.
    • Deleted - (bool) Will delete a current set with the same name.
    • Categories - (array)
      • Name - (string) The name of the POI category. Visible in CoPilot in the POI Search dialog as long as at least one place mapped to this category exists on the device.
      • Icon - (string; optional) The name of the alk place category icon that will be used when display this category. If this value is not provided, CoPilot will search user provided images for one with the category name.
      • MaxZoomLevel - (integer) The maximum zoom level that POIs of this category will be visible on the map. Range is 0 (zoomed in to a very small portion of the map) to 7 (zoomed out to a much larger portion of the map.)
      • Options - (integer) Bitwise OR of three possible values. Use 21 to enable all options.
        • 1 - Display on Map
        • 4 - Searchable Whether this category appears in the POI search dialog
        • 16 - Alertable Whether this category appears in the POI alert settings
    • Places - (array)
      • Address - (object) Displayed when viewing the POI
        • StreetAddress - (string; optional; 128 char max)
        • City - (string; optional; 128 char max)
        • Zip - (string; optional; 16 char max)
        • State - (string; optional; 4 char max) State (US) or Country (EU) abbreviation
        • County - (string; optional; 64 char max)
      • Coords - (object) Used to draw the POI on the map, and when routing to the POI
        • Lat - (string) decimal degrees, positive for North, negative for South
        • Lon - (string) decimal degrees, positive for East, negative for West
      • CategoryName - (string) Assigns this POI to a category (category name must exist in the category array described above for this set).
      • PlaceName - (string; 128 char max); Displayed when viewing the POI.
      • Phone - (string; optional; 64 char max) Displayed when viewing the POI.

Msg_ImportPOISet

This API is used to send xml files that contain POI set details to import into CocPilot using Msg_SendGenericTextData API

Supported SinceMinimum Operating System
CoPilot 9.6.8Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

int Msg_ImportPOISet(int setid, char* data, int strlength);

Parameters

ValueDescription
setidMessaging identifier e.g. MSG_IDT_IMPORTPOISET
dataXml file content
strlengthThe length of the xml file content
functionNameName of the function to call when message arrives
Msg_SendGenericTextDataMsg_SendGenericTextData is calling/invoking with messaging Identifier “MSG_IDT_IMPORTPOISET”, xml content and the length.

Return Value

  • Equal to or less than 0 - Failed
  • Greater than 0 - Successful

Sample Code


Msg_DeletePOISet

This API is used to delete POI set. This API is used to send xml file contains POI set details to be deleting using Msg_SendGenericTextData API.

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

int Msg_DeletePOISet(char* data, int strlength);

Parameters

ValueDescription
dataXml file content
strlengthThe length of the xml file content
functionNameName of the function to call when message arrives
Msg_SendGenericTextDataMsg_SendGenericTextData is calling/invoking with messaging Identifier “MSG_IDT_IMPORTPOISET”, xml content and the length.

Return Value

  • Equal to or less than 0 - Failed
  • Greater than 0 - Successful

Sample Code

Msg_SendMapFeedbackJSON

This API is used to send map feedback to the MapSure service in JSON format.

Supported in following CoPilot VersionMinimum Version Supported
CoPilot v10.9.0Windows 10
Android 4.1

Syntax (Prototyped in alkmsg.h)

Parameters

ValueDescription
pJsonJson format which will allow users to send map feedback to MapSure

Example JSON

{
  "coPilotVersion": "10.6.0.5",
  "dataVersion": "GRD_ALK.NA-base-4.2017.02.13.11.1.3",
  "description": "",
  "heading": 0,
  "speed": 0,
  "timeStamp": 1504724835,
  "issueType": 1,
  "feedbackLocation": {
    "Address": {
      "StreetAddress": "124 North Nassau Street  (NJ-27)",
      "City": "Princeton",
      "State": "NJ",
      "Zip": "08542",
      "County": "Mercer",
      "Country": ""
    },
    "Coords": {
      "Lat": "40.350010",
      "Lon": "-74.658530"
    }
  },
  "customFields": {
    "StopType": 1,
    "showUI": true,
    "ReturnMapPickUp": true
  }
}

Notes

Return Value

ValueDescription
MSG_IDT_MAP_FEEDBACK_SEND_SUCCESSSuccessful in sending the request to CoPilot
MSG_IDT_MAP_FEEDBACK_SEND_JSON_PARSE_ERRORJSON parsing failed - ensure a valid json object is being passed
MSG_IDT_MAP_FEEDBACK_SEND_INVALID_POI_JSONJSON has missing/incomplete fields required for map feedback
MSG_IDT_MAP_FEEDBACK_SEND_STOPINFO_NOT_PROVIDEDStop Type required feedback location but missing in JSON

Information on further information can be found below.

StopType: Integer

ValueDescription
0Last Stop
1Current location
2 (default)Choose Stop
3Pick point on the map

For value 2, you have to provide a feedback stop, otherwise FAILURE_STOPINFO_NOT_PROVIDED error will be provided.

showUI: boolean

ValueDescription
TrueWill display the map feedback UI flow in CoPilot
FalseSubmit the map feedback json without UI flow

If timeStamp is included and the report is submitted through the UI flow, the timeStamp will be overwritten when submitted through the UI. The timeStamp will not be overwritten if showUI is set to false.

If showUI is set to be true, issueType is provided and so is a description, we will ignore these two fields as the issue type has been selected and/or description in the map feedback CoPilot UI flow.

If your StopType is PICK_ON_MAP but you set showUI to be false, you will end up getting FAILURE_INVALID_POI_JSON. So be careful about the combination of those options.

ReturnMapPickUp: boolean

ValueDescription
TrueReturn the picked feedback location to the calling application and stay on the map location pickup view
FalseProceed CoPilot feedback UI flow after picking up the location

The picked location will be returned from the callback through the generic data identifier MSG_ID_Feedback_Location. This callback is under MapDataListener.

issueType:

ValueDescription
0Missing Address
1Address Location Error
2Height Restriction
3Weight Restriction
4Truck Restriction
5Hazmat Restriction
6Missing Street
7Exit Sign Post Correction
8One Way Street Error
9Speed Limit Error
10Road Closure
11Turn Restriction
12Road Name Error
13Other

The API will either send the feedback to the ALK MapSure web service or cache it in local device. The decision is made by the following config:

[Mapsure]
"SendMapFeedbackOTA"=1

Setting the config to true (=1) will result in the API will sending the feedback to web service and not caching it on device. MapDataMgr.getMapFeedback() API should be used when set to =0 to send the information back to ALK. This can be used at certain times when you want to send the information to CoPilot.

Last updated April 12, 2023.