Skip to main content

Initialization

Contents

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 SinceMinimum Operating System
CoPilot 9.2.0Windows 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
pCommCallbackCallback function to be called upon connection status changes/events. See CommCallback below.
pConfigDirMsg_StartUp looks in the DLL’s working directory.
bIsProLicensedAlways pass true.
bIsSDKLicensedAlways pass true.
bStartConnectionAlways pass true.
callingConventionCalling 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
configDirAlways pass NULL
bIsProLicensedAlways pass true.
bIsSDKLicensedAlways pass true.
bStartConnectionAlways pass true.
conventionCalling convention for callback functions, use default value. It is ignore for Android.
callBackObjPass 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
pszCoPilotDirectoryFully qualified directory path of CoPilot.
iShowTRUE : Show CoPilot after launching. FALSE: Hide CoPilot after launching.
pCoPilotProcEventCBPass NULL (Not used).
iNumRestartPass 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

ALK_StartCoPilotEx

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

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 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

ParameterDescription
pszCoPilotDirectoryFully qualified directory path of CoPilot.
iShowPass always TRUE to show CoPilot, FALSE to hide the CoPilot.
pCoPilotProcEventCBPass NULL (Not used).
iNumRestartPass 0 (Not used).
forcedimsForced 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
lConfirmUnused
lTimeoutUsed to specify timeout interval in milliseconds

Return Value

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

Error code

ParameterDescription
#define PM_OK0No Error
#define PM_FAILED-1Failed
#define PM_TIMEOUT1Message sent but not yet processed

ALK_GetCoPilotWindow

It will retrieve CoPilot window handle.

Supported SinceMinimum Operating System
CoPilot 9.2.0Windows 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10

Syntax (Prototyped in alkmsg.h)

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

Parameters

ParameterDescription
lConfirmUnused.
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.

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

ParameterDescription
MsgIDIdentifier for Message.
pfnProcessMsgAddress of function to call when message arrives.
pDescriptionBrief description of incoming message type. For example, “Response” for response message ID.
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_SetCallback(int MsgID,
   String callbackFunctionName,
   String description,
   int convention,
   Object callBackObj);

Parameters

ParameterDescription
MsgIDIdentifier for Message.
callbackFunctionNameName of the function to call when message arrives.
DescriptionBrief description of incoming message type. For example, “Response” for response message ID.
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.

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

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

Parameters

ParameterDescription
MsgIDIdentifier for Message.
bEnabledSpecifies whether the message is enabled or disabled. Pass this parameter as “true” to enable the message.
bQueueSpecifies whether the message is added to the message queue or not. If client application is using callback then pass this parameter false.
callbackFunctionNameName of the function to call when message arrives.
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.

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

ParameterDescription
msgIDThe 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.
lPosterIDDestination 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.
lMyIDUnique 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 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

ParameterDescription
msgIDThe 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.
lPosterIDDestination 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.
lMyIDUnique 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 SinceMinimum Operating System
CoPilot 9.2.0Windows 10, Android 4.1

Syntax (Prototyped in alkmsg.h)

void ParserDelete(long ID)

Parameters

ParameterDescription
IDMessage buffer handle created in the Msg_TextLoad, Msg_TripLoad, or other similar function.
Last updated November 23, 2021.
Contents