Skip to content

Initialization

Msg_HasStarted

Determines whether the messaging layer has been initialized by a call to Msg_StartUp(). In most scenarios, this should the first API called.

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

Syntax (Prototyped in alkmsg.h)

long Msg_HasStarted(void);

Return Value

  • Less than 0 - Error
  • Greater than 0 - Messaging started
  • Equal to 0 - Messaging not yet started, need to call Msg_StartUp to start messaging

Notes

In most instances this will be the first API called. This API only starts the messaging component inside the SDK and does not provide status whether it is connected to CoPilot. The client application will need to use Msg_IsConnected to check whether SDK and CoPilot connection is established.


Msg_StartUp

Starts up messaging communications using user.cfg [ConnectionInfo1] file for Connection parameters

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

Syntax (Prototyped in alkmsg.h)

long Msg_StartUp (void* pCommCallback,
  callingConvention convention = convention_default);

Parameters

Parameter Description
pCommCallback Callback function to be called upon connection status changes/events. See CommCallback below.
pConfigDir Msg_StartUp looks in the DLL’s working directory.
bIsProLicensed Always pass true.
bIsSDKLicensed Always pass true.
bStartConnection Always pass true.
callingConvention Calling convention for callback functions, use default value.

Syntax (Prototyped in alkmsg.java)

long Msg_StartUp (String functionName,
   String configDir,
   boolean isProLicensed,
   boolean isSDKLicensed,
   boolean bStartConnection,
   int convention,
   Object callBackObj);
functionName: Name of the function to call when message arrives
configDir Always pass NULL
bIsProLicensed Always pass true.
bIsSDKLicensed Always pass true.
bStartConnection Always pass true.
convention Calling convention for callback functions, use default value. It is ignore for Android.
callBackObj Pass the object of the class which implemented functionName method so JNI layer will call this method once message arrived.

Return Value

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

Enum

enum callingConvention {
  convention_default,
  convention_cdecl,
  convention_stdcall
};

enum ConnEventType {
  // States
  CET_First,
  CET_Connecting = CET_First,
  CET_Connected,
  CET_Disconnecting,
  CET_Disconnected,

  // Activities
  CET_Receiving,
  CET_Sending
  CET_LoggedIn,
  CET_Forwarding,
  CET_Count
  };

Callback Function Syntax for C++

void CommCallback(ConnEventType status, unsigned long connID)

Callback Function Syntax for Java

void CommCallback(int status, int connID)

Parameters

status: Connection Status. See ConnEventType in alkmsg.h or alkmsg.java
connID: User ID who generated the connection event.

Notes

Following ConnEventType are not used by SDK, but are required for working with CoPilot. CET_LoggedIn, CET_Forwarding


Msg_IsConnected

Determines if the application layer is connected to the CoPilot application. Use this API to check that the application communication is established, after Msg_Startup has been called.

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

Syntax (Prototyped in alkmsg.h)

long Msg_IsConnected(void);

Return Value

  • Less than 0 - Error
  • Equal to 0 - Messaging not yet started
  • Greater than 0 - Messaging started

ALK_StartCoPilot

The call to launch CoPilot, this offers a simple launch with options to show/hide. This call does not initiate messaging between client application and CoPilot.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long ALK_StartCoPilot(const char *pszCoPilotDirectory, bool iShow, PM_PROCEVTFUNC pCoPilotProcEventCB, int iNumRestart);

Parameters

Parameter Description
pszCoPilotDirectory Fully qualified directory path of CoPilot.
iShow TRUE : Show CoPilot after launching. FALSE: Hide CoPilot after launching.
pCoPilotProcEventCB Pass NULL (Not used).
iNumRestart Pass 0 (Not Used).

Notes

The list of return values can be found in alkmsg.h.

Return Value

  • \< 0 - Failed
  • ≥ 0 - Successful

Return codes

// SDK process to monitor error messages

#define PM_E_UNKNOWN                 -2001  Unknown error
#define PM_E_PROC_CREATE_FAIL        -2003  Error starting process
#define PM_E_NAMETOOLONG             -2007  Process or directory name too long
#define PM_E_NOENT                   -2008  File or directory does not exist
#define PM_E_COPILOT_ALREADY_RUNNING -2009  Specific to SDK:Process already running
#define PM_E_INVALID_PARAM           -2012  Invalid parameters
#define PM_E_CMDTOOLONG              -2014  Command too long

Success:

#define PM_OK                        0       No Error

Monitor Process

If you want to monitor that CoPilot is running. This can be done with the following options within a Windows OS.

Sample Code

[DllImport("coredll.dll")]
public static extern int FindWindow(string CoPilotWndClass, string CoPilotTitle);

int cpWindow = FindWindow (CoPilot WndCls, CoPilot);

If(cpWindow == null)
 a. //CoPilot is not present
else
 b. //CoPilot is running
HWND cpWindow = ::FindWindow (LCoPilot WndCls, LCoPilot);

If(cpWindow == NULL)
 c. //CoPilot is not present
else
 d. //CoPilot is running

ALK_StartCoPilotEx

Launch CoPilot including show/hide mode but with advance option to define the window parameter CoPilot will run within.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long ALK_StartCoPilotEx(const char *pszCoPilotDirectory,
   bool bShow,
   PM_PROCEVTFUNC pClientCB,
   int iNumRestart,
   const char *forcedims=NULL,
   const char* listenerWnd = NULL,
   bool bSIPControl = false)

Parameters

Parameter Description
pszCoPilotDirectory Fully qualified directory path of CoPilot.
iShow Pass always TRUE to show CoPilot, FALSE to hide the CoPilot.
pCoPilotProcEventCB Pass NULL (Not used).
iNumRestart Pass 0 (Not used).
forcedims Forced dimension in following format “forcedims=top,left, height, width” e.g “forcedims=200,100,300,600”, It will force CoPilot to launch in given dimension.

Return Value

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

Error code

// SDK process to monitor error messages
#define PM_E_UNKNOWN                  -2001  Unknown error
#define PM_E_PROC_CREATE_FAIL         -2003  Error starting process
#define PM_E_NAMETOOLONG              -2007  Process or directory name too long
#define PM_E_NOENT                    -2008  File or directory does not exist
#define PM_E_COPILOT_ALREADY_RUNNING  -2009  Specific to SDK:Process already running
#define PM_E_INVALID_PARAM            -2012  Invalid parameters
#define PM_E_CMDTOOLONG               -2014  Command too long

Success

#define PM_OK  0   No Error

Notes

Please note CoPilot is not designed to launch into any window size.

The length and width should only be even numbers (odd number are not supported).

Also please set the following in user.cfg in copilot directory to enable image scaling based on your resolution (if not using standard resolution).

[Image]
"AllowSquish"=1

Please also refer to Msg_ResizeCoPilotReq documentation for more information on resizing the CoPilot window.

Monitor Process

If you want to monitor that CoPilot is running, this can be done with the following options within a Windows OS:

[DllImport("coredll.dll")]
public static extern int FindWindow(string CoPilotWndClass, string CoPilotTitle);

int cpWindow = FindWindow (CoPilot WndCls, CoPilot);

If(cpWindow == null)
a.  //CoPilot is not present
else
b.  //CoPilot is running

HWND cpWindow = ::FindWindow (LCoPilot WndCls, LCoPilot);

If(cpWindow == NULL)
c.  //CoPilot is not present
else
d.  //CoPilot is running

Launching twice

Some low end Windows devices launching CoPilot via the SDK, quickly minimizing CoPilot and trying to relaunch via the CoPilot icon can lead to an error with the second launch.


ALK_ExitCoPilot

Send message for CoPilot to exit properly within timeout period if messaging is connected. If messaging is not connected or CoPilot does not exit within timeout period, then it will close the CoPilot process forcefully.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long ALK_ExitCoPilot(long lConfirm,
                     long lTimeout = 15000);

Parameters

Parameter Description
lConfirm Unused
lTimeout Used to specify timeout interval in milliseconds

Return Value

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

Error code

Parameter Description
#define PM_OK 0
#define PM_FAILED -1
#define PM_TIMEOUT 1

ALK_GetCoPilotWindow

It will retrieve CoPilot window handle.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

unsigned long ALK_GetCoPilotWindow();

Return Value

  • Less than or equal to 0 - Failed
  • Greater than 0 - Window handle of CoPilot. Cast it accordingly

Msg_SendAppExit

Send message to CoPilot to exit the application properly. If it is not possible to exit properly, CoPilot will not exit. We recommend using ALK_ExitCoPilot rather than this API.

Supported Since Minimum Operating System
CoPilot 9.2.0 Windows 10

Syntax (Prototyped in alkmsg.h)

long Msg_SendAppExit(long lConfirm = 1,
   long lDestID = CONN_ID_NONE);

Parameters

Parameter Description
lConfirm Unused.
lDestID Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

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

Msg_Shutdown

Shuts down the messaging communications between the two applications. This function must be the last function before the client application exits.

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

Syntax (Prototyped in alkmsg.h)

long Msg_Shutdown (void)

Return Value

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

Notes

Do not call any other SDK API after calling Msg_ShutDown.

This should be the last SDK call that the client application makes before it exits, as this will clean up resources.


Msg_SetCallback

Set a callback function for a particular message type. Used in conjunction with subscription-based messages. We recommend using Msg_UpdateOptions instead of Msg_SetCallback.

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

Syntax (Prototyped in alkmsg.h )

long Msg_SetCallback(unsigned long MsgID,
   void *pfnProcessMsg,
   char *pDescription = NULL,
   callingConvention convention = convention_default);

Parameters

Parameter Description
MsgID Identifier for Message.
pfnProcessMsg Address of function to call when message arrives.
pDescription Brief description of incoming message type. For example, “Response” for response message ID.
convention Calling 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_SetCallback(int MsgID,
   String callbackFunctionName,
   String description,
   int convention,
   Object callBackObj);

Parameters

Parameter Description
MsgID Identifier for Message.
callbackFunctionName Name of the function to call when message arrives.
Description Brief description of incoming message type. For example, “Response” for response message ID.
convention Calling convention. Should use convention_default.
callBackObj Pass the object of the class which implemented CallbackFunctionName method so JNI layer will call this method once message arrived.

Callback Function Syntax for C++

void (*pfnProcessMsg)(const char *pBuf, const unsigned long lBufLen)
Callback Function Syntax for Java Client
void CallbackFunctionName (int buffer, int len)

Return Value

  • Less than or equal to 0 - Failed

  • Greater than 0 - Successful

enum callingConvention {
  convention_default,
  convention_cdecl,
  convention_stdcall
};

Msg_UpdateOptions

Updates the options for different ALK messages. Primarily used for setting callback function. Using Msg_UpdateOptions is recommended instead of Msg_SetCallback.

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

Syntax (Prototyped in alkmsg.h)

long Msg_UpdateOptions(unsigned long MsgID,
    bool bEnabled,
    bool bQueue,
    void *pfnProccesMsg,
    callingConvention convention = convention_default);

Parameters

Parameter Description
MsgID Identifier for Message.
bEnabled Specifies whether the message is enabled or disabled. Pass this parameter as “true” to enable the message.
bQueue Specifies whether the message is added to the message queue or not. If client application is using callback then pass this parameter false.
pfnProccesMsg Callback function to be called upon message receipt.
Convention Calling 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_**UpdateOptions** (**unsigned long** MsgID,
   boolean bEnabled,
   Boolean bQueue,
   String callbackFunctionName,
   int convention,
   Object callBackObj);

Parameters

Parameter Description
MsgID Identifier for Message.
bEnabled Specifies whether the message is enabled or disabled. Pass this parameter as “true” to enable the message.
bQueue Specifies whether the message is added to the message queue or not. If client application is using callback then pass this parameter false.
callbackFunctionName Name of the function to call when message arrives.
convention Calling convention. Should use convention_default.
callBackObj Pass the object of the class which implemented CallbackFunctionName method so JNI layer will call this method once message arrived.

Callback Function Syntax for C++

void (*pfnProcessMsg)(const char *pBuf, const unsigned long lBufLen)
Callback Function Syntax for Java Client
void CallbackFunctionName (int buffer, int len)

Return Value

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

Enum

enum callingConvention {
  convention_default,
  convention_cdecl,
  convention_stdcall
};

Msg_Subscribe

Subscribe to event-based notification of real-time information from the CoPilot application. Registers a subscription with the remote process for the specified message type. Msg_Subscribe() should be used in conjunction with Msg_UpdateOptions() to set an event handler. Within the handler function, the appropriate parsing function (Msg_Getxxx()) should be used to extract data from the message buffer.

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

Syntax (Prototyped in alkmsg.h)

long Msg_Subscribe(unsigned long msgID,
   long lPosterID = CONN_ID_NONE,
   long lMyID = CONN_ID_NONE);

Parameters

Parameter Description
msgID The message to which you are subscribing. Valid values are Msg_ID_TurnDist, Msg_ID_TurnInstructions, Msg_ID_GuidanceMap, Msg_ID_RoutingEvents, Msg_ID_GenericEvent , Msg_ID_TruckWarning, Msg_ID_TruckAlert, Msg_ID_OverSpeedLimitEvent, Msg_ID_CurrentSpeedLimitEvent, Msg_ID_CountryBorderEvent, Msg_ID_VoiceEvent and Msg_ID_GeofenceRoutingEvent.
lPosterID Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lMyID Unique ID of the sender of the message Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

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

Note

Special case for the Msg_ID_OverSpeedLimitEvent, Msg_ID_CurrentSpeedLimitEvent and Msg_ID_VoiceEvent


Msg_Unsubscribe

Unsubscribe to event-based notification of real-time information from CoPilot application.

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

Syntax (Prototyped in alkmsg.h)

long Msg_Unsubscribe(unsigned long msgID,
   long lPosterID = CONN_ID_NONE,
   long lMyID = CONN_ID_NONE);

Parameters

Parameter Description
msgID The message to which you are un-subscribing. Valid values are Msg_ID_TurnDist, Msg_ID_TurnInstructions, Msg_ID_GuidanceMap, Msg_ID_RoutingEvents, Msg_ID_GenericEvent, Msg_ID_TruckWarning, Msg_ID_TruckAlert, Msg_ID_OverSpeedLimitEvent,Msg_ID_VoiceEvent and Msg_ID_GeofenceRoutingEvent.
lPosterID Destination ID received in the callback function established for handling connection event change messages (this callback function is the first parameter passed to Msg_Startup call). Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.
lMyID Unique ID of the sender of the message. Omit or set to CONN_ID_NONE when sending CoPilot control commands to same local machine.

Return Value

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

Msg_ParserDelete

Delete a previously-allocated message buffer handle and free associated resources. Frees resources associated with a previously allocated message handle created by Msg_TextLoad, Msg_TripLoad, Msg_CreateGenericInformation, Msg_GenericInformationParse, Msg_POIParse, Msg_SearchParse, Msg_MultiStopParse.

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

Syntax (Prototyped in alkmsg.h)

void ParserDelete(long ID)

Parameters

Parameter Description
ID Message buffer handle created in the Msg_TextLoad, Msg_TripLoad, or other similar function.

Last update: August 24, 2020