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.

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

Syntax (Prototyped in alkmsg.h)

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

Parameters

Syntax (Prototyped in alkmsg.java)

long Msg_StartUp (String functionName,
   String configDir,
   boolean isProLicensed,
   boolean isSDKLicensed,
   boolean bStartConnection,
   int convention,
   Object callBackObj);

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.

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.

Syntax (Prototyped in alkmsg.h)

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

Parameters

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 (L“CoPilot WndCls”, L“CoPilot”);

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.

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

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 (L“CoPilot WndCls”, L“CoPilot”);

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.

Syntax (Prototyped in alkmsg.h)

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

Parameters

Return Value

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

Error code

ALK_GetCoPilotWindow

It will retrieve CoPilot window handle.

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.

Syntax (Prototyped in alkmsg.h)

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

Parameters

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.

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.

Syntax (Prototyped in alkmsg.h )

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

Parameters

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

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.

Syntax (Prototyped in alkmsg.h)

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

Parameters

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

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.

Syntax (Prototyped in alkmsg.h)

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

Parameters

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.

Syntax (Prototyped in alkmsg.h)

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

Parameters

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.

Syntax (Prototyped in alkmsg.h)

void ParserDelete(long ID)

Parameters