Navigation & Display Settings

Msg_SendGenericData

Sends a generic data message Msg_ID_GenericData to CoPilot. It will to use set/get the settings and request some generic operation.

Syntax (Prototyped in alkmsg.h)

long Msg_SendGenericData(long lIdentifier,
long lPayload,
long lDestID = CONN_ID_NONE,
long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• ≤ 0 - Failed

• Greater than 0 = Successful

Msg_GenericDataGet

Decodes and retrieves requested information through Msg_ID_GenericData. It is used to receive various types of information from CoPilot, for example, a start/stop trip message, various settings, geocoding result of a stop sent to CoPilot etc.

Syntax (Prototyped in alkmsg.h)

long Msg_GenericDataGet(void *pBuffer,
   long &lIdentifier,
   long &lPayload);

Parameters

Return Value

• ≤ 0 - Failed

• Greater than 0 - Successful

GenericData Identifier Details

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

#define MSG_ID_GenericData              0xf1000115
#define MSG_IDT_STARTTRIP               0x0002L
#define MSG_IDT_STOPTRIP                0x0003L
#define MSG_IDT_GEORESULT               0x0004L
#define MSG_IDT_REQMAPONCE              0x0005L
#define MSG_IDT_ZOOM                    0x0006L
#define MSG_IDT_REQDISTUNIT             0x0007L
#define MSG_IDT_DISTUNIT                0x0008L
#define MSG_IDT_LANGCHNG                0x0009L
#define MSG_IDT_LANG                    0x000AL
#define MSG_IDT_SPEECHCHNG              0x000BL
#define MSG_IDT_SPEECH                  0x000CL
#define MSG_IDT_VIEWMODE                0x000EL
#define MSG_IDT_ITINCLR                 0x0012L
#define MSG_IDT_MUTEALERTCHNG           0x0014L
#define MSG_IDT_ALRTSTATUS              0x0015L
#define MSG_IDT_MAPHEADINGCHNG          0x0016L
#define MSG_IDT_MAPHEADING              0x0017L
#define MSG_IDT_GPSCHNG                 0x001AL
#define MSG_IDT_GPS                     0x001BL
#define MSG_IDT_UICONTROLCHNG           0x001CL
#define MSG_IDT_UICONTROL               0x001DL
#define MSG_IDT_NAVMODECHNG             0x001EL
#define MSG_IDT_NAVMODE                 0x001FL
#define MSG_IDT_APPALERTOPTIONS         0x0022L
#define MSG_IDT_INFOBARCHNG             0x0025L
#define MSG_IDT_INFOBAR                 0x0026L
#define MSG_IDT_REPEATSPOKENINST        0x0028L
#define MSG_IDT_VOLUMECHNG              0x0029L
#define MSG_IDT_VOLUME                  0x002AL
#define MSG_IDT_DAYNIGHTMODECHNG        0x002DL
#define MSG_IDT_DAYNIGHTMODE            0x002EL
#define MSG_IDT_MAXTYPEAHEADCHNG        0x0035L
#define MSG_IDT_MAXTYPEAHEAD            0x0036L
#define MSG_IDT_CLEARPOISEARCH          0x0037L
#define MSG_IDT_CLEARADDRESSSEARCH      0x0038L
#define MSG_IDT_ROUTEFERRYAVOIDCHNG     0x003AL
#define MSG_IDT_ROUTEFERRYAVOID         0x003BL
#define MSG_IDT_VIEWEXTENDED2DMODE      0x003CL
#define MSG_IDT_SIPCONTROLCHNG          0x003EL
#define MSG_IDT_SIPCONTROL              0x003FL
#define MSG_IDT_RESETSPEEDVARZOOM       0x0040L
#define MSG_IDT_ROUTINECOMPLETED        0x0041L
#define MSG_IDT_TRIP_RESULT             0x0043L
#define MSG_IDT_SHOW_GUI                0x0044L
#define MSG_IDT_RELEASE_CACHEMEMORY     0x0045L
#define MSG_IDT_TOGGLESTOPORWAYPOINT    0x0046L
#define MSG_IDT_BACKLIGHT               0x0047L
#define MSG_IDT_SCREENORIENTATION       0x0048L
#define MSG_IDT_SPEEDLIMIT              0x004CL
#define MSG_IDT_COMPASS                 0x004DL
#define MSG_IDT_LIVELINK                0x004EL
#define MSG_IDT_REOPENGPSPORT           0x0050L
#define MSG_IDT_RESIZEMAP_COMPLETED     0x005CL
#define MSG_IDT_TRUCKWARNING            0x005DL
#define MSG_IDT_TRUCKWARNING_LOOKAHEAD  0x005FL
#define MSG_IDT_UTURNCOST               0x0060L
#define MSG_IDT_POIDISPLAY_OPTION       0x0061L
#define MSG_IDT_SHOWDESPITEDIST         0x0062L
#define MSG_IDT_TRUCKALERTS_TO_SDKONLY  0x0063L
#define MSG_IDT_ERASETRIP_ONEXIT        0x0064L
#define MSG_IDT_SETMAPDRAG              0x0072L
#define MSG_IDT_TURNINSTRUCTIONALERT    0x0073L
#define MSG_IDT_LOADPROFILE_RESULT      0x0074L
#define MSG_IDT_FAVORITES_SET_RESULT    0x0080L

Msg_IDT_GEORESULT

Returns result for geocoding success, including error codes for destination details that have failed to geocode. To be used following Msg_SendTrip

#define Msg_IDT_GEORESULT = 0x0004L

Request

• No Request.

• It will return as Geocoding result for each stop, once you use Msg_SendTrip function.

Response (Msg_IDT_GEORESULT):

• lPayload will contain error code results of stop geocoding

Trip Planning and Options

Msg_IDT_TOGGLESTOPORWAYPOINT

Use this function to toggle a Stop to a Waypoint and vice versa. Only intermediate Stops can be marked as a Waypoint so it is not possible to toggle the first or the last Stop in a Trip. Therefore, this API should only be used when more than two Stops exist in the Trip. This API should be used after a Stop has been added via Msg_AddStop() and Msg_TripSend().

#define Msg_IDT_TOGGLESTOPORWAYPOINT = 0x0046L

Request (MsgIDT TOGGLESTOPORWAYPOINT):

• Pass lPayload equal to the zero-based index of the Stop to toggle. The first Stop in the Trip has index 0, so the index passed should be greater than or equal to 1.

Response (Msg_IDT_TOGGLESTOPORWAYPOINT):

• Return value = 1

Msg_IDT_ITINCLR

Returns identifier once trip itinerary is cleared.

Response Response is received as generic identifier once trip itinerary is cleared.

Routing Profile

MSG_IDT_ADDROUTINGPROFILE

This identifier will provide a callback with the routing profile that has been added to CoPilot. This will include attributes such as vehicle type and profile name. The routing profile will be provided in a JSON format which can be modified and returned to amend the routing profile.

Msg_SetFlexCallback can be used to set the callback and Msg_SendGenericTextData should be used with MSG_IDT_ADDROUTINGPROFILE to create the profile within CoPilot.

Syntax (Prototyped in alkmsg.h)

public static native int Msg_SendGenericTextData(int lIdentifier, int lPayload, String strPayload, int lStringLen, int lRequestID, int lDestID, int lSrcID, boolean bAck);

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

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

Parameters

Return Value

Callback Function The function set in Msg_SetFlexCallback receives the newly created profile in JSON format

Return Codes

Sample Code

Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkRoutingProfileJsonRsp"), delOnRoutingProfileResponseCB);
  Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ADDROUTINGPROFILE,
  ConvertVehicleTypeDropBoxIndexToVehicleType(),
  strProfileName,
  strProfileName.length(), -1, -1, -1, false);

MSG_IDT_ROUTINGPROFILE_ACTION

MSG_IDT_ROUTINGPROFILE_REQUEST

This Identifier (MSG_IDT_ROUTINGPROFILE_ACTION) and Payload (MSG_IDT_ROUTINGPROFILE_REQUEST) pair requests the details of a specific routing profile, this identifier together with a string detailing the requested routing profile name should be passed. CoPilot routing profiles can be added, returned or amended by passing the routing profile JSON file.

To ensure this identifier is returned, Msg_SetFlexCallback should be set to ensure that a response is received.

Syntax (Prototyped in alkmsg.h)

public static native int Msg_SendGenericTextData(int lIdentifier, int lPayload, String strPayload, int lStringLen, int lRequestID, int lDestID, int lSrcID, boolean bAck);

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

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

Parameters

Return Value

Callback Function The function set in Msg_SetFlexCallback receives the newly created profile in JSON format

Return Codes

Sample Code

 Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkRoutingProfileJsonRsp"), delOnRoutingProfileResponseCB);
  Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ROUTINGPROFILE_ACTION,
    Msg.MSG_IDT_ROUTINGPROFILE_REQUEST,
    Util.ConvertString(txtBoxProfileName.Text),
    txtBoxProfileName.TextLength, -1, -1, -1, false);

MSG_IDT_REQUESTACTIVEPROFILE

This identifier (MSG_IDT_ROUTINGPROFILE_ACTION) and payload (MSG_IDT_REQUESTACTIVEPROFILE) pair requests the details of the active routing profile. CoPilot routing profiles can be added, returned or amended by passing the routing profile JSON file.

To ensure this identifier is returned, Msg_SetFlexCallback should be set to ensure that a response is received.

Syntax (Prototyped in alkmsg.h)

public static native int Msg_SendGenericTextData(int lIdentifier, int lPayload, String strPayload, int lStringLen, int lRequestID, int lDestID, int lSrcID, boolean bAck);

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

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

Parameters

Return Value

Callback Function The function set in Msg_SetFlexCallback receives the active profile in JSON format

Sample Code

 Msg.Msg_SetFlexCallback(Util.ConvertString("TSdkRoutingProfileJsonRsp"), delOnRoutingProfileResponseCB);
  Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ROUTINGPROFILE_ACTION,
    Msg.MSG_IDT_REQUESTACTIVEPROFILE,
    (byte[])null,0, -1, -1, -1, false);

MSG_IDT_ROUTINGPROFILE_DELETE

This identifier (MSG_IDT_ROUTINGPROFILE_ACTION) and payload (MSG_IDT_ROUTINGPROFILE_DELETE) pair, when passed with the name of a specific routing profile name will delete the specified routing profile.

To ensure this identifier is returned, Msg_SetFlexCallback should be set to ensure that a response is received.

Syntax (Prototyped in alkmsg.h)

public static native int Msg_SendGenericTextData(int lIdentifier, int lPayload, String strPayload, int lStringLen, int lRequestID, int lDestID, int lSrcID, boolean bAck);

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

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

Parameters

Return Value

Sample Code

Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ROUTINGPROFILE_ACTION,
  Msg.MSG_IDT_ROUTINGPROFILE_DELETE,
  Util.ConvertString(txtBoxProfileName.Text),
  txtBoxProfileName.TextLength, -1, -1, -1, false);

MSG_IDT_ROUTINGPROFILE_SETASACTIVE

This identifier/payload, when passed with a specific routing profile name, will set that profile as the active profile.

To ensure this identifier is returned, Msg_SetFlexCallback should be set to ensure that a response is received.

Syntax (Prototyped in alkmsg.h)

public static native int Msg_SendGenericTextData(int lIdentifier, int lPayload, String strPayload, int lStringLen, int lRequestID, int lDestID, int lSrcID, boolean bAck);

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

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

Parameters

Return Value

Sample Code

Msg.Msg_SendGenericTextData(Msg.MSG_IDT_ROUTINGPROFILE_ACTION,
  Msg.MSG_IDT_ROUTINGPROFILE_SETASACTIVE,
  Util.ConvertString(txtBoxProfileName.Text),
  txtBoxProfileName.TextLength, -1, -1, -1, false);

Street and POI Search

Msg_IDT_MAXTYPEAHEADCHNG

Msg_IDT_MAXTYPEAHEAD

Use this function in conjunction with Msg_SearchCity / Msg_SearchPostcode/Msg_SearchCityAndPostcode to set the number of results returned.

#define Msg_IDT_MAXTYPEAHEADCHNG = 0x0035L
#define Msg_IDT_MAXTYPEAHEAD = 0x0036L

Request (Msg_IDT_MAXTYPEAHEADCHNG):

• Pass lPayload = any positive value

• Pass lPayload = -1 to get current max type ahead value

Response (Msg_IDT_MAXTYPEAHEAD):

• lPayload will contain current maximum type ahead value

Msg_IDT_CLEARPOISEARCH

To be used in conjunction with Msg_SearchPOIEx, to clear the CoPilot cache memory. We recommend that you use Msg_ClearPOIResults.

#define Msg_IDT_CLEARPOISEARCH = 0x0037L

Request (Msg_IDT_CLEARPOISEARCH):

• lPayload = Any.

• Once received this message, CoPilot will free up POI search resources. This should be used once SDK client completes POI search functionality via SDK.

Msg_IDT_CLEARADDRESSSEARCH

To be used in conjunction with Msg_SearchCityAndPostcode, to clear the CoPilot cache memory. We recommend that you use Msg_ClearSearchResults

#define Msg_IDT_CLEARADDRESSSEARCH = 0x0038L

Request (Msg_IDT_CLEARADDRESSSEARCH):

• lPayload = Any.

• Once received this message, CoPilot will free up address search resources. This should be use once SDK client complete searching functionality via SDK.

Guidance Map

Msg_IDT_REQMAPONCE

To be used in conjunction with Msg_ID_GuidanceMap to provide the map image once.

#define Msg_IDT_REQMAPONCE = 0x0005L

Request (Msg_IDT_REQMAPONCE):

• Once received request, CoPilot will send the current guidance map through Msg_ID_GuidanceMap message.

Zoom levels and Settings

Msg_IDT_ZOOM

This API enables the client application to zoom in and out of the map image.

#define Msg_IDT_ZOOM = 0x0006L

Request (Msg_IDT_ZOOM):

• Pass lPayload = integer value

• When using Msg_IDT_ZOOM, the payload must be specified in the percentage format. For example, the following call would zoom in the map by 60%:

• Msg_SendGenericData(Msg_IDT_ZOOM, 40);

• Whereas, the following call would zoom out the map by 100%:

• Msg_SendGenericData(Msg_IDT_ZOOM, 200);

• Please note that the % zooming = (the zoom factor that you passed in) – 100, factors greater than 100 would zoom out the map and factors less than 100 would zoom in the map. A factor equal to 100 would do nothing.

Msg_IDT_RESETSPEEDVARZOOM

CoPilot in 3D mode will automatically zoom in and out of the map details based upon vehicle speed. Autozoom is currently switched on by default, until the user touches the zoom buttons, this then switches off the autozoom. Use this function to re-enable the autozoom.

#define Msg_IDT_RESETSPEEDVARZOOM = 0x0040L

Request (MsgIDT RESETSPEEDVARZOOM): - lPayload = Any value - It will reset the speed variable zoom.

Response (Msg_IDT_RESETSPEEDVARZOOM): - lPayload = Not applicable (Any value) - Once reset routine is completed, it will send the confirmation back to the calling application.

Distance Unit setting

Msg_IDT_REQDISTUNIT

Use to set and get the distance measurement unit set in CoPilot.

#define Msg_IDT_REQDISTUNIT = 0x0007L

Enum

enum TUnitsType

{
UT_Miles,
UT_KMs
};

Request (Msg_IDT_REQDISTUNIT):

• Pass lPayload = -1 to get distance unit used in CoPilot
• Pass lPayload = any of the value (Kms/Miles)

Response (Msg_IDT_DISTUNIT):

• lPayload will contain current distance unit used by CoPilot

Audio settings

Msg_IDT_MUTEALERTCHNG

Can be used to mute or unmute all audio alerts in CoPilot, including speech. To mute only speech, use Msg_IDT_SPEECHCHNG.

#define Msg_IDT_MUTEALERTCHNG = 0x0014L
#define Msg_ALERT_MUTE = 0
#define Msg_ALERT_UNMUTE = 1

Request (Msg_IDT_MUTEALERTCHNG):

• Set lPayload = -1 to check if alerts are currently muted or not. Set lPayload = Msg_ALRT_MUTE to mute alerts in CoPilot.

• Set lPayload = Msg_ALRT_UNMUTE to unmute alerts in CoPilot.

Response (Msg_IDT_ALRTSTATUS):

• lPayload will indicate whether sounds are muted in CoPilot or not.

Msg_IDT_ALRTSTATUS

Received from CoPilot in response to a Msg_IDT_MUTEALRTCHNG request to mute or unmute alerts including speech. The payload indicates whether alters are currently muted or not. This refers to all alerts including speech, for speech only use MsgIDT SPEECHCHNG.

#define MSG_IDT_ALRTSTATUS = 0x0015L
#define MSG_ALERT_MUTE       0
#define MSG_ALERT_UNMUTE     1

Response (Msg_IDT_ALRTSTATUS): lPayload will contain current status of the alert.

Msg_IDT_REPEATSPOKENINST

CoPilot will play the last spoken instruction.

#define Msg_IDT_REPEATSPOKENINST = 0x0028L

Request(Msg_IDT_REPEATSPOKENINST):

• lPayload = Unused

• CoPilot will play the last spoken instruction

Msg_IDT_VOLUMECHNG

Msg_IDT_VOLUME

This will change the volume setting within CoPilot. We recommend using Msg_IDT_VOLUME instead of Msg_IDT_SPEECH . For Android, CoPilot also update the system volume while all other platform volume is independent of system volume.

#define MSG_IDT_VOLUMECHNG = 0x0029L
#define MSG_IDT_VOLUME = 0x002AL

Request (Msg_IDT_VOLUMECHNG): - Pass lPayload = 0 to 5 (0-Mute, 5-Max) + 1 (if device can vibrate) - Pass lPayload = -1 to get current volume level

Example:

if (device can vibrate)
    if (lPayload >= 1)
        Volume = lpayload - 1
        Vibration is on
    else if (lPayload == 0)
        Volume = 0
        Vibration is off
else if (device cannot vibrate)
    Volume = lPayload

Response (Msg_IDT_VOLUME):

• lPayload will contain current volume level of CoPilot

Msg_IDT_TURNINSTRUCTIONALERT

This identifier enables CoPilot to send an event notification to the client application to provide a pre-notification of a navigational audio alert (this will not include any user interaction or menu selection audio) but does include all turn instructions and other notifications provided to the driver from the navigation. The pre-notification alert time is configurable to milliseconds. Once set, the CoPilot SDK will provide a notification that in X time an audio notification will play. Once CoPilot finishes playing the voice instruction, it again sends a notification to the client application that the instruction is finished.

This identifier is useful if playing CoPilot audio instructions via the vehicle audio system and requires this to be muted, enabling the instruction to be heard. Or if multiple applications share the audio output this notification can ensure there is no conflict.

CoPilot will signal the following event. As global event is being used, it will only support the Win32 platform.

Event Name: CoPilotAudioStart

Description When CoPilot is about to play an instruction, it will signal this event. The event is auto reset so client application does not need to reset it.

Event Name: CoPilotAudioCompleted

Description When CoPilot has finished playing the instruction, it will signal this event. The event is auto reset so client application does not need to reset it.

#define Msg_IDT_TURNINSTRUCTIONALERT = 0x00073L

Request (Msg_IDT_TURNUINSTRUCTIONALERT):

• lPayload > 0, values are in milliseconds. CoPilot provides notification based upon the lPayload value in milliseconds before playing the instruction. CoPilot pre-notification is based upon logic to look ahead on the current route and provide notification based upon current speed and velocity to calculate the pre-notification time. This may mean in some instances, the timing may not be 100% accurate.

• lPayload = 0 to disable the turn instruction alert notification

• lPayload = -1 to request current value set for turn instruction alert notification

Response (Msg_IDT_TURNUINSTRUCTIONALERT):

• Payload will contain current setting in Milliseconds

Using Msg_IDT_TURNUINSTRUCTIONALERT in SDK Sample Application

User can change the Turn Instruction Alert using the SDK Sample Application by using OptionsSettings Turn Audio Alert.

settings

Alert_Settings

User can monitor the audio notification by using OptionsEventsAudio Alert Recorder

Audio_Alert

AudioNotification

View / Day and Night mode

Msg_IDT_VIEWMODE

Changes the current view mode within CoPilot.

#define Msg_IDT_VIEWMODE = 0x000EL

 enum ENavView
 {
    CV_Nav = 0,        // Safety View
    CV_Map_WAMI,       // 2D view and snaps to current location
    CV_Map_NextTurn,   // Next Turn view
    CV_Map_NextStop,   // Next stop view
    CV_Map_3D,         // 3D view
    CV_Map_LastStop,   // Last stop view
    CV_Map_StartStop,  // Start stop view
    CV_Map_Trip,       // Trip view
    CV_Itinerary,      // Itinerary view
    CV_Nav_Map,        // Map view
    V_Map_Hybrid,      // Map and Only for wide screen
    CV_LaneAssist,     // Shows the LaneAssist View
    CV_MapViewer       // Show Map Viewer mode
 };

Request (Msg_IDT_VIEWMODE):

• Pass lPayload = Any of the above enum value to set the navigation view
• CV_Map_Hybrid will only support in Wide and Extra Wideorientation
• CV_LaneAssist will only support in Wide, Extra Wide & Landscapemode.
• Note Please note that existing popup message in front of nav dialog will get closed when client application requests change view mode.

Msg_IDT_MAPHEADINGCHNG

Msg_IDT_MAPHEADING

Changes the current heading setting within the view, north up or heading up.

#define MSG_IDT_MAPHEADINGCHNG = 0x0016L
#define MSG_IDT_MAPHEADING     = 0x0017L

#define  MSG_MAPHEADING_NORTHUP    0
#define MSG_MAPHEADING_DIRUP      1

Request (Msg_IDT_MAPHEADINGCHNG):

• Pass lPayload = any of the value(Northup/Up) while setting the option (you must be in 2D map mode as 3D map view does not support this feature)
• Pass lPayload = -1 to get current map rotation

Response (Msg_IDT_MAPHEADING): - lPayload will contain current map rotation value

Msg_IDT_VIEWEXTENDED2DMODE

Extends the 2D view to include current or last known position and next stop within the stop list.

#define Msg_IDT_VIEWEXTENDED2DMODE = 0x003CL

Request (MsgIDT VIEWEXTENDED2DMODE):

• Pass lPayload = Not applicable
• It will show the 2D map with the current or last known position and next stop in the itinerary.

Msg_IDT_DAYNIGHTMODECHNG

Msg_IDT_DAYNIGHTMODE

Changes the setting of day and night mode within CoPilot.

#define Msg_IDT_DAYNIGHTMODECHNG = 0x002DL
#define Msg_IDT_DAYNIGHTMODE = 0x002EL

enum EMapDayNightMode

{
EDay = 0,
ENight,
EAuto
};

Request (Msg_IDT_DAYNIGHTMODECHNG):

• Pass lPayload = any of the EMapDayNightMode while setting the option
• Pass lPayload = -1 to get current DayNightMode value

Response (Msg_IDT_DAYNIGHTMODE):

• lPayload will contain current status of DayNightMode

UI / Information Bar / SIP Control

Msg_IDT_UICONTROLCHNG

Msg_IDT_UICONTROL

Enables the client application to lock the menu within CoPilot, so that the user is not able to access menu options. Often used in conjunction with monitoring vehicle movement to enhance driver safety. To monitor vehicle movement, use Msg_SendGPSPositionRequest.

#define Msg_IDT_UICONTROLCHNG = 0x001CL
#define Msg_IDT_UICONTROL = 0x001DL

#define Msg_COPILOT_LOCK_CONTROL 0
#define Msg_COPILOT_UNLOCK_CONTROL 1

Request (Msg_IDT_UICONTROLCHNG):

• Pass lPayload = 0/1 to lock/unlock the menu button. Once lock only “Hide” button is enabled on the CoPilot menu.

• Pass lPayload = -1 to get current status of the UI Control

Response (Msg_IDT_UICONTROL):

• lPayload will contain current status of the UI control

Please note that CoPilot has a feature for Motion Lock, which is handled directly by CoPilot without the need for the SDK. CoPilot will monitor the speed and when above the required threshold will disable interaction with the UI for the user similar to the above description.

GPS

Msg_IDT_GPSCHNG

Msg_IDT_GPS

Provides the ability to disable / enable GPS within CoPilot.

#define Msg_IDT_GPSCHNG = 0x001AL
#define Msg_IDT_GPS = 0x001BL

#define Msg_GPS_OFF 0
#define Msg_GPS_ON 1

Request (Msg_IDT_GPSCHNG):

• Pass lPayload = 0/1 to disable/enable the GPS connection
• Pass lPayload = -1 to get current status of the GPS connection

Response (Msg_IDT_GPS):

• lPayload will contain current GPS connection status

Msg_IDT_REOPENGPSPORT

Re-open GPS port to be used in after Msg_SendNMEA if you want to re-use the default GPS port.

#define Msg_IDT_REOPENGPSPORT = 0x0050L

Request (Msg_IDT_REOPENGPSPORT):

• lPayload = Any value
• This message must send after client application stops to send NMEA message and wants to use the GPS receiver which is already configured in CoPilot. If user will not send this message, then CoPilot is always waiting for NMEA message via SDK.

Response (Msg_IDT_REOPENGPSPORT):

• lPayload = Not applicable
• Once message is received by CoPilot, it will send back Msg_IDT_REOPENGPSPORT as a confirmation.

Navigation Mode

Msg_IDT_NAVMODECHNG

Msg_IDT_NAVMODE

Provides the ability to change the routing type. We recommend using Msg_SendRoutingProfile API instead.

#define Msg_IDT_NAVMODECHNG = 0x001EL
#define Msg_IDT_NAVMODE = 0x001FL

enum RoutingType

{
   RTE_Quickest = 0,
   RTE_Shortest,
   RTE_AvoidMajorRoads,
   RTE_Scenic
};

Request (Msg_IDT_NAVMODECHNG):

• Pass lPayload = Any of the value from the Routing Type
• Pass lPayload = -1 to get current routing type

Response (Msg_IDT_NAVMODE):

• lPayload will contain current routing type

Routing / Ferry

Msg_IDT_ROUTEFERRYAVOIDCHNG

Msg_IDT_ROUTEFERRYAVOID

Ability to avoid Ferries.

#define Msg_IDT_ROUTEFERRYAVOIDCHNG = 0x003AL
#define Msg_IDT_ROUTEFERRYAVOID     = 0x003BL

Request (MsgIDT ROUTEFERRYAVOIDCHNG):

• Pass lPayload = 0 to make routing avoid ferry to false
• Pass lPayload = 1 to make routing avoid ferry to true
• Pass lPayload = -1 to get avoid ferry value

Response (MsgIDT ROUTEFERRYAVOID):

• lPayload will contain current avoid ferry value

Window and Screen Orientation

Msg_IDT_ROUTINECOMPLETED

To be used in conjunction with Msg_ID_WindowMode and Msg_ID_ResizeCoPilot to return when the function has completed.

#define Msg_IDT_ROUTINECOMPLETED = 0x0041L

Response (Msg_IDT_ROUTINECOMPLETED):

• lPayload = 0 once Msg_ID_WindowMode routine completed.
• lPayload = 1 once Msg_ID_ResizeCoPilot routine completed.
• lPayload = 2 once Msg_Subscribe with Msg_ID_GuidanceMap routine completed.
• lPayload = 3 once Msg_Unsubscribe with Msg_ID_GuidanceMap routine completed.

Msg_IDT_SCREENORIENTATION

Toggles the screen orientation from Portrait to Landscape and vice versa.

#define Msg_IDT_SCREENORIENTATION = 0x0048L

Request (Msg_IDT_SCREENORIENTATION):

• Pass lPayload = -1 to query current screen orientation
• 0 = Portrait
• 1 = Landscape
• 2 = Use Device’s Settings

Response (Msg_IDT_SCREENORIENTATION):

• lPayload will contain value of current setting

Memory

Msg_IDT_RELEASE_CACHEMEMOR

If the hardware requires more memory, you can call this to free up all cache memory of CoPilot.

#define Msg_IDT_RELEASE_CACHEMEMORY = 0x0045L

Response (Msg_IDT_RELEASE_CACHEMEMORY):

• lPayload = Ignore, Once received CoPilot will free up cache memory.

Backlight

Msg_IDT_BACKLIGHT

Sets the backlight status.

#define Msg_IDT_BACKLIGHT = 0x0047L

Request (Msg_IDT_BACKLIGHT):

• Pass lPayload = -1 to return current settings
• Pass lPayload = 0 to make backlight “On With GPS”
• Pass lPayload = 1 to set backlight as “Always On”
• Pass lPayload = 2 to set backlight as “On Near Turn”
• Pass lPayload = 3 to set backlight as “Use Device’s Settings”

Response (Msg_IDT_BACKLIGHT):

• lPayload will contain current status of the backlight.

Compass

Msg_IDT_COMPASS

Options to display or remove the compass from the screen.

#define Msg_IDT_COMPASS = 0x004DL

Request (Msg_IDT_COMPASS):

• Pass lPayload = -1 to return current setting
• Pass lPayload = 0 to hide Compass
• Pass lPayload = 1 to Show Heading
• Pass lPayload = 2 to show compass heading towards Mecca (Only if language is Arabic otherwise behaves as 1)

Response (Msg_IDT_COMPASS):

• lPayload will contain current setting for compass.

LiveLink

Msg_IDT_LIVELINK

To enable the live features such as friend link and traffic.

#define Msg_IDT_LIVELINK = 0x004EL

Request (Msg_IDT_LIVELINK):

• Pass lPayload = -1 to return current setting
• Pass lPayload = 1 to toggle current connection

Response (Msg_IDT_LIVELINK):

Returns current settings

• lPayload 0 if live connection is disabled
• lPayload 1 if live connection is enabled

Truck Warning

Msg_IDT_TRUCKWARNING

Controls the setting for truck warning and alerts.

#define Msg_IDT_TRUCKWARNING = 0x005DL

Request (Msg_IDT_TRUCKWARNING):

• lPayload = -1 [Query Current Setting]
• lPayload = 0 [Disable Current Setting]
• lPayload = 1 [Enable Current Setting]

Response (Msg_IDT_TRUCKWARNING):

• lPayload = Contains Current Setting.

Msg_IDT_TRUCKWARNING_LOOKAHEAD

Controls the setting for the lookahead distance for truck warning.

#define Msg_IDT_TRUCKWARNING_LOOKAHEAD= 0x005FL

Request (Msg_IDT_TRUCKWARNING_LOOKAHEAD):

• lPayload = 0 Off
• lPayload = 1 Distance set to 250
• lPayload = 2 Distance set to 500
• lPayload = 3 Distance set to 750
• lPayload = 4 Distance set to 1000
• lPayload = 5 Distance set to 1250

These distances are set in the unit set within CoPilot. For example if CoPilot units of measurements are set to Meters, these distances will be meters. The default is set to IPayload = 4.

Response (Msg_IDT_TRUCKWARNING_LOOKAHEAD):

• lPayload = Contains Current Setting.

Miscellaneous

Msg_IDT_UTURNCOST

Provides the ability to amend the cost associated with u-turns.

#define Msg_IDT_UTURNCOST = 0x0060L

Request (Msg_IDT_UTURNCOST):

• Pass lPayload = any positive value
• Pass lPayload = -1 to request current cost for U-Turn for all modes
• Pass lPayload = any negative value other than -1, to force CoPilot to use default values.

Response (Msg_IDT_UTURNCOST):

• Payload will contain current cost for U-Turn for all modes

Notes

• Please note the cost of 1000 is approximately equal to 1 mile, 500 = half a mile, etc. The cost of 1 mile means that if CoPilot cannot find a suitable alternative route which is less than 1 mile around the block it will instruct the driver to turn around.

• Setting the value to -2, will force CoPilot to use the default values.

• Setting the value to any positive value will change the u-turn cost associated with all vehicles.

• If this value is modified, please modify u-turn cost value to a suitable value when changing vehicle type.

Msg_IDT_POIDISPLAY_OPTION

Provides the ability to display or remove PO’s from the screen.

#define Msg_IDT_POIDISPLAY_OPTION = 0x0061L

Request (Msg_IDT_POIDISPLAY_OPTION):

• lPayload = -1 [Query Current Setting]
• lPayload = 0 [Never show POI on map]
• lPayload = 1 [Show POI on Map when stopped]
• lPayload = 2 [Always show POI on Map]

Response (Msg_IDT_POIDISPLAY_OPTION):

• lPayload = Contains Current Setting.

Msg_IDT_DESPITEDIST

To stop any potential driver interruption when they are close to a turn CoPilot will cue any messages until after the turn has been completed. Use this in order to disable this setting.

This flag is critical for message process time. In order to avoid distraction, CoPilot does not prompt message and process SDK message in 0.3 miles from a turn. Most SDK customers want CoPilot to process all the SDK messages in real-time without 0.3 miles provision. By setting this flag, you can override this behavior.

#define Msg_IDT_DESPITEDIST = 0x00062L

Request (Msg_IDT_DESPITEDIST):

• Pass lPayload = -1 to get current status

• Pass lPayload = 1/0

  • 1 (Process all the message even user is within 0.3 miles of turn)
  • 0 (Process all the message except user is within 0.3 miles of turn, these messages are put into queue and process once user pass the turn)

Response (Msg_IDT_DESPITEDIST):

• lPayload will contain current status of the flag

Msg_IDT_TRUCKALERTS_TO_SDKONLY

Use this to enable / disable truck alerts from the CoPilot application and to provide them only to the client application.

#define Msg_IDT_TRUCKALERTS_TO_SDKONLY = 0x00063L

Request (Msg_IDT_TRUCKALERTS_TO_SDKONLY):

• Pass lPayload = -1 to get current status

• Pass lPayload = 1/0

  • 1 (Truck alerts are passing to SDK client only if it subscribes for truck alert. It will not display alerts to CoPilot)

  • 0 (Truck alerts are passing to SDK client only if it subscribes for truck alerts. It will also display alerts in CoPilot)

Response (Msg_IDT_TRUCKALERTS_TO_SDKONLY):

• lPayload will contain current status of the flag

Note

This flag only usable of Msg_IDT_TRUCKWARNING is 1. If Msg_IDT_TRUCKWARNING is false then then this flag will be unavailable to use.

Msg_IDT_ERASETRIP_ONEXIT

This will ensure that all trip/destination information is deleted each time CoPilot is exited.

#define Msg_IDT_ERASETRIP_ONEXIT = 0x00064L

Request (Msg_IDT_ERASETRIP_ONEXIT):

• Pass lPayload = -1 to get current status

• Pass lPayload = 1/0

  • 1 (CoPilot erase the trip before exit )
  • 0 (CoPilot does not erase the trip so same trip will be available after CoPilot starts)

Response (Msg_IDT_ERASETRIP_ONEXIT):

• lPayload will contain current status of the flag

Msg_IDT_SETMAPDRAG

CoPilot automatically moves the position to the current GPS location. To disable this and allow the user to drag the map and view other locations, this is usually required when using Msg_SetMapPan and Msg_ZoomToStop.

Allows the toggling between enabling and disabling the ability to drag the map during active guidance. CoPilot default will not allow the user to move around the map while an active moving guidance is running.

#define Msg_IDT_SETMAPDRAG= 0x0072L

Request (Msg_IDT_SETMAPDRAG):

• Pass lPayload = 0 to disable the map dragging
• Pass lPayload = -1 to request current information
• Pass lPayload = 1 to allow map dragging.

Response (Msg_IDT_SETMAPDRAG):

• Payload will contain current setting (either 0 or 1)

Msg_IDT_LOADPROFILE_RESULT

This message provides acknowledgement for Msg_IDT_LOADPROFILE message. Client can load the profile using Msg_SendGenericTextData with identifier (Msg_IDT_LOADPROFILE) and this message will provide acknowledgement.

#define Msg_IDT_LOADPROFILE_RESULT = 0x0075L

Response (Msg_IDT_LOADPROFILE_RESULT):

• Payload will contain 0 or 1.

• 0 indicates that CoPilot failed to load the profile as CoPilot could not find it.

• 1 indicates that CoPilot loaded profile successfully.

Msg_IDT_FAVORITES_SET_RESULT

This message provides acknowledgement for Msg_SetFavoritesStopInfo API. Following is the success and failure code.

#define Msg_IDT_FAVORITES_SET_RESULT = 0x0080L

Response (Msg_IDT_FAVORITES_SET_RESULT):

• It will contain one of the following return code.

#define Msg_FAVORITES_SET_SUCCESS 0 // Success
#define Msg_FAVORITES_SET_FAILED -1 // Standard failed
#define Msg_FAVORITES_SET_GEOCODE_ERROR 1 // Stop failed due to geocode

Msg_IDT_HIDE

This message provides notification when CoPilot is hidden. This is a notification only message and will be sent by CoPilot when the user presses the hide button.

#define Msg_IDT_HIDE = 0x000DL

Response (Msg_IDT_HIDE):

• Ignore payload

Comment:

Instead of relying on this notification, the following can use the platform API to check whether CoPilot is hidden or not. It is only available for Windows 10 platform.

bool IsCoPilotInForeground()
{
  return (HWND)ALK_GetCoPilotWindow() == GetForegroundWindow();
}