UI

Msg_SendWindowMode

Change the application window’s show state, including hide and topmost options. Sends a message to the CoPilot application GUI to request a change to the application window’s show state, activation, and Z-order from the host’s operating system.

Syntax (Prototyped in alkmsg.h)

long Msg_SendWindowMode(long wm,
                        long lDestID = CONN_ID_NONE);

Flags

WM_SH_HIDE Request that the show state be set to “HIDE”. WM_SH_SHOW Request that the show state be set to “SHOW”.

WM_Z_TOPMOST Request that the window be made topmost (always on top). WM_Z_NOTOPMOST Request that the window be made non-topmost.

Parameters

Return Value

• ≤ 0 - Failed

• 0 - Successful

//Use in Msg_SendWindowMode
#define WM_SH_NONE 0x00
#define WM_SH_HIDE 0x01
#define WM_SH_SHOW 0x02
#define WM_SH_MASK 0x03
#define WM_Z_NONE 0x0000
#define WM_Z_NOTOPMOST 0x0200
#define WM_Z_TOPMOST 0x0400
#define WM_Z_MASK 0x0700

Note

• Android Platform only supports WM_SH_HIDE. Rest identifiers are not supported in Android Platform.
• Please note that if a destination is set when CoPilot is the background application, it will continue to generate a route based upon the GPS, utilizing CPU resource.
• It is advisable if using ‘Hide’ CoPilot to clear destinations from the trip list before doing so. This can be done by sending a new blank destination into CoPilot.

Msg_ZoomToStop

CoPilot will zoom to a given location on the map. This is not added as a destination, but used to mark/search an area that is not the current location.

Syntax (Prototyped in alkmsg.h)

long Msg_ZoomToStop(char *pName,
                    char *pAddress,
                    char *pCity,
                    char *pState,
                    char *pZip,
                    char *pJurisdiction,
                    long lLat,
                    long lLon,
                    char *pNorthing = NULL,
                    char *pEasting = NULL,
                    char *pGridSQ = NULL,
                    long lDestID = CONN_ID_NONE,
                    long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• ≤ 0 - Failed

• 0 - Successful

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 passed as -122805 longitude & 51518220 latitude.

• This API is not responsible for adding the stops as destination. If stop is not being added, pName parameter is not used and should be passed as NULL. For adding the stop, please look at the Msg_TripLoad, Msg_TripAddStop, Msg_TripAddStopWithHouseNum and Msg_SendTrip.

• All the flags which were passed using Msg_ZoomToStop can be removed in CoPilot by using the same API with lLat and LLon as a -1.

Msg_SendResizeCoPilot

Request to resize CoPilot window after CoPilot is already launched.

Syntax (Prototyped in alkmsg.h)

long Msg_SendResizeCoPilot(unsigned long lLeft,
   unsigned long lTop,
   unsigned long lHeight,
   unsigned long lWidth,
   long lDestID = CONN_ID_NONE,
   long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• < 0 0 Failed to send message to CoPilot
• 0 0 Unable to send message as SDK didn’t find connection

• 0 - Successful

Note

To achieve this functionality, users must start CoPilot using forcedims parameter in ALK_StartCoPilotEx function. If the user starts CoPilot without using forcedims parameters then the Resize functionality will not work.

• 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

Msg_ResizeCoPilotReq

Request to resize CoPilot window after CoPilot is already launched.

Syntax (Prototyped in alkmsg.h)

long Msg_ResizeCoPilotReq(unsigned long lLeft,
                          unsigned long lTop,
                          unsigned long lHeight,
                          unsigned long lWidth,
                          unsigned long lDPI,
                          long lDestID = CONN_ID_NONE,
                          long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• < 0 - Failed to send message to CoPilot
• 0 | Unable to send message as SDK didn’t find connection

• 0 - Successful

Note

To achieve this functionality, users must start CoPilot using forcedims parameter in ALK_StartCoPilotEx function. If the user starts CoPilot without using forcedims parameters, then the Resize functionality will not work.

• 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

Msg_SetMapPan

Request to pan the map view in a specified direction and by a specified factor.

Syntax (Prototyped in alkmsg.h)

long Msg_SetMapPan(long lPanDirection,
                  long lPanFactor,
                  long lDestID = CONN_ID_NONE,
                  long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• ≤ 0 - Failed

• 0 - Successful

Pan Direction Macro

#define MAP_PAN_UP        0
#define MAP_PAN_UPRIGHT   1
#define MAP_PAN_RIGHT     2
#define MAP_PAN_DOWNRIGHT 3
#define MAP_PAN_DOWN      4
#define MAP_PAN_DOWNLEFT  5
#define MAP_PAN_LEFT      6
#define MAP_PAN_UPLEFT    7
#define MAP_PAN_NORTH     8
#define MAP_PAN_NORTHEAST 9
#define MAP_PAN_EAST      10
#define MAP_PAN_SOUTHEAST 11
#define MAP_PAN_SOUTH     12
#define MAP_PAN_SOUTHWEST 13
#define MAP_PAN_WEST      14
#define MAP_PAN_NORTHWEST 15

Msg_POIAlertParse

Required to retrieve results of a POI Alert callback. Decodes and retrieves the message ID from a POI alert message buffer.

Use Msg_ParserDelete to free the memory when finished with ParserID.

Syntax (Prototyped in alkmsg.h)

long lPOIAlertMsgId = Msg_POIAlertParse (void *pBytes,
                                  unsigned long bytes);

Parameters

Return Value

• < 0 - Unable to allocate message buffer
• ≥ 0 - Successful, Returned Message ID needed for subsequent calls to Msg_POIAlterGetHeader and Msg_POIAlertGetDetail

Msg_POIAlertGetHeader

Required to retrieve results of a POI Alert callback. Decodes and retrieves the message ID from a POI alert message buffer.

Syntax (Prototyped in alkmsg.h)

long Msg_POIAlertGetHeader (unsigned long lPOIMsgId,
   long & rError,
   unsigned long & rPOIAlertCount)

Parameters

Return Value

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

Error code returns in rError:

• -1 - Unable to get current alters
• -2 - Not enough memory

Msg_POIAlertGetDetails

Required to retrieve results of a POI Alert callback. Decodes and retrieves the message ID from a POI alert message buffer.

Syntax (Prototyped in alkmsg.h)

long Msg_POIAlertGetDetails(unsigned long lPOIAlertMsgId,
   unsigned long lIndex,
   char *pName,
   unsigned long lNameLen,
   double &distOffRoute,
   double &distanceToDest,
   double &distFromCurrent,
   double &dLat,
   double &dLon,
   unsigned long &lHeading,
   int &typeID);

Parameters

Return Value

• 0 - Unable to find POIAlterMsgID from the cache list
• -1 - Invalid index value
• 1 - Successful

Msg_ShowGUI

Request to show a specific page within CoPilot. Can be used to hide specific options until no other option available. For example show destination entry menu.

Syntax (Prototyped in alkmsg.h)

long Msg_ShowGUI(long lIdentifier,
   char *strPayload=NULL,
   long lPayloadLen=0,
   long lDestID = CONN_ID_NONE,
   long lSrcID = CONN_ID_NONE);

Parameters

Return Value

• ≤ 0 - Failed

• 0 - Successful

Identifiers for Msg_ShowGUI

#define Msg_IDT_MENU                 0x0001L
#define Msg_IDT_HOME                 0x0002L
#define Msg_IDT_RECENT               0x0003L
#define Msg_IDT_FAVORITE             0x0004L
#define Msg_IDT_DESTINATION_ADDRESS  0x0005L
#define Msg_IDT_START_MENU           0x0006L
#define Msg_IDT_START_ROUTEDEMO      0x0007L
#define Msg_IDT_START_ROUTINGWIZARD  0x0008L
#define Msg_IDT_SHOW_ROUTINGPROFILE  0x0009L
#define Msg_IDT_SHOW_PLANEDITTRIP    0x000AL
#define Msg_IDT_SHOW_WARNING         0x000BL
#define Msg_IDT_SHOWROUTE            0x000CL
#define Msg_IDT_POI                  0x000DL
#define Msg_IDT_NOMAPDATA_WARNING    0x000EL
#define STOP_ROUTEDEMO               0x000FL

Response (Msg_IDT_SHOW_GUI) : lPayload will contain value of above listed identifier.

Msg_IDT_MENU

Shows the Quick Menu available through the navigation screen.

Request (Msg_IDT_MENU):

• Once a request is received, CoPilot will show main menu.

Msg_IDT_HOME

Passes a new destination saved within CoPilot as the Favorite - Home. If no home address is set it will display address entry to add Home address.

Request (Msg_IDT_HOME):

• Once received, CoPilot will add the home to the destination and show route preview screen.

• If favorite is not added as a Home then CoPilot will show add destination screen.

Msg_IDT_RECENT

Shows the Recent history of destinations entered.

Request (Msg_IDT_RECENT):

• Once a request is received, CoPilot will show the recent destination screen.

Msg_IDT_FAVORITE

Shows the Favorite List saved within CoPilot.

Request (Msg_IDT_FAVORITE):

• Once a request is received, CoPilot will show the favorite screen.

Msg_IDT_DESTINATION_ADDRESS

This will show the Address Entry screen allowing the user to input a destination and geocode an address.

Request (Msg_IDT_DESTINATION_ADDRESS):

• Once a request is received, CoPilot will show address entry screen.

Msg_IDT_START_MENU

Shows the Short Cut menu shown at the start of CoPilot.

Request (Msg_IDT_START_MENU):

• Once a request is received, CoPilot will start welcome menu dialog box.

Msg_IDT_START_ROUTEDEMO

Starts a Demo Trip running.

Request (Msg_IDT_START_ROUTEDEMO):

• Once a request is received, CoPilot will show the route demo.

• This requires that CoPilot should have a trip with at least 2 stops.

Note The above command is not used to show CoPilot. If the user wants to show CoPilot, then they will be required to call Msg_SendWindowMode(WM_SH_SHOW) along with the above command.

Msg_IDT_START_ROUTINGWIZARD

Shows the current route that has been calculated by CoPilot.

Request (Msg_IDT_START_ROUTINGWIZARD):

• Once a request is received, CoPilot will show the routing wizard.

Note The command above is not used to show CoPilot. If the user wants to show CoPilot, then they will be requited to call Msg_SendWindowMode(WM_SH_SHOW) along with the command above.

MSG_IDT_SHOW_ROUTINGPROFILE

Shows the Routing Profile menu screens within CoPilot.

Request (Msg_IDT_SHOW_ROUTINGPROFILE):

• Once the request is received, CoPilot will show the route profile.

Note The command above is not used to show CoPilot. If the user wants to show CoPilot, then they will be requited to call Msg_SendWindowMode(WM_SH_SHOW) along with the command above.

Msg_IDT_SHOW_PLANEDITTRIP

Shows the Plan Edit Trip screens.

Request (Msg_IDT_SHOW_PLANEDITTRIP):

• Once the request is received, CoPilot will show the plan-edit trip screen

Note Above command is not used to show CoPilot. If the user wants to show CoPilot, then they will be requited to call Msg_SendWindowMode(WM_SH_SHOW) along with the command above.

Msg_IDT_SHOW_WARNING

Displays the End User License Agreement acceptance screen.

Request (Msg_IDT_SHOW_WARNING):

• Once a request is received, CoPilot will show the legal warning message.

Note: Above command is not used to show CoPilot. If the user wants to show CoPilot, then they will be requited to call Msg_SendWindowMode(WM_SH_SHOW) along with the command above.

Msg_IDT_SHOWROUTE

Calculates and Shows the Route.

Request (Msg_IDT_SHOWROUTE):

• Once a request is received, CoPilot will calculate and show a route.

Note: Above command is not used to show CoPilot. If the user wants to show CoPilot, then they will be requited to call Msg_SendWindowMode(WM_SH_SHOW) along with the command above.

Msg_IDT_POI

Shows the POI page.

Request (Msg_IDT_POI):

• Once a request is received, CoPilot will show the POI page.

Note: Above command is not used to show CoPilot. If the user wants to show CoPilot, then they will be required to call Msg_SendWindowMode(WM_SH_SHOW) along with the command above.

Msg_IDT_NOMAPDATA_WARNING

Shows the No Map Data Warning pop-up.

Request (Msg_IDT_NOMAPDATA_WARNING):

• Once a request is received, CoPilot will show message the “There is no map data on the latitude/longitude you entered. Please try again”.

Msg_IDT_STOP_ROUTEDEMO

Stops the route demo.

Request (Msg_IDT_STOP_ROUTEDEMO):

• Once a request is received, CoPilot will stop the route demo if it is being played.

• This requires that CoPilot should have a trip with at least 2 stops.

Msg_GetGuidanceMapSize

Returns the size of the guidance map contained in a message buffer received through a subscription to Msg_ID_GuidanceMap.

Syntax (Prototyped in alkmsg.h)

long Msg_GetGuidanceMapSize(const char *pBuf,
                            const long lBufLen);

Parameters

Return Value

• ≤ 0 - Failed

• 0 | Amount of memory required, in bytes, to store the map GIF buffer.

Note

• This should be used with Msg_GetGuidanceMap

• If you are planning to use this message, please contact SDK team at and please refer to Msg_GetGuidanceMapSizeSharedMem and Msg_GetGuidanceMapSharedMem for requesting maps from the running instance of CoPilot. These methods are faster.

• Type of Image that will be sent from CoPilot.

• In user.cfg (in CoPilot directory) for gif

    [User Settings]
    MapImageFormat=”gif”

• In user.cfg (in CoPilot directory) for png

    [User Settings]
    MapImageFormat=”png”

• In user.cfg (in CoPilot directory) for bmp

    [User Settings]
    MapImageFormat=”bmp”

• By default it is set to png.

Msg_GetGuidanceMap

Decodes and retrieves the guidance map (GIF image) contained in a message buffer received through a subscription to Msg_ID_GuidanceMap.

Syntax (Prototyped in alkmsg.h)

long Msg_GetGuidanceMap(const char *pBuf,
   const long lBufLen,
   char *pMapBuf,
   long lMapBufLen);

Parameters

Return Value

• ≤ 0 - Failed

• 0 - Successful

Note

• If you are planning to use this message, please contact the SDK team a and please refer to Msg_GetGuidanceMapSizeSharedMem and Msg_GetGuidanceMapSharedMem for requesting maps from the running instance of CoPilot. These methods are faster.

• Type of Image that will be sent from CoPilot.

• In user.cfg (in CoPilot directory) for gif

   [User Settings]
   MapImageFormat=”gif”

• In user.cfg (in CoPilot directory) for png

   [User Settings]
   MapImageFormat=”png”

• In user.cfg (in CoPilot directory) for bmp

   [User Settings]
   MapImageFormat=”bmp”

• By default it is set to png.

Msg_GetGuidanceMapSizeSharedMem

Msg_SharedMem APIs are to be used when you want to add a CoPilot window within your client application. Allocates a text message buffer and return its buffer handle Extracts the size of the incoming map image. Dependency on Msg_Subscribe (Msg_ID_GetGuidanceMapSize).

Syntax (Prototyped in alkmsg.h)

long Msg_GetGuidanceMapSizeSharedMem(long &lSize, long &lFormat, long
&lBytesPerPixel);

Parameters

Return Value

Size of map image coming from CoPilot

enum EPixelFormat
{
 EPIXELFORMAT_UNKNOWN = -1, //Pixel Format is not set
 EPIXELFORMAT_323,          //8bpp, colormap or rgb
 EPIXELFORMAT_555,          //15 bpp
 EPIXELFORMAT_565,          //16 bpp
 EPIXELFORMAT_888,          //24 bpp
 EPIXELFORMAT_888BGR,       //24 bpp
 EPIXELFORMAT_RGBA,         //32 bpp
 EPIXELFORMAT_BGRA,         //32 bpp
}

Note

• This should be used with Msg_SharedMemNotifierWaitForEvent, Msg_GetGuidanceMapSharedMem and Msg_SharedMemNotifierClearEvent.

• Type of Image that will be sent from CoPilot.

• In user.cfg (in copilot directory) for gif

   [User Settings]
   MapImageFormat=”gif”

• In user.cfg (in CoPilot directory) for png

   [User Settings]
   MapImageFormat=”png”

• In user.cfg (in CoPilot directory) for bmp

   [User Settings]
   MapImageFormat=”bmp”

• In user.cfg (in CoPilot directory) for raw (pixel data)

   [User Settings]
   MapImageFormat=”raw”

• By default it is set to raw. (We recommend using this format because of performance issues related to conversion of image to other formats).

• Also please refer to “requesting maps via sdk v9.pdf” for detailed explanation.

Msg_SendDevProjCoordinationReq

If the client application also contains a mapping application, this API will help to match the CoPilot location and zoom level to the inbuilt map – providing the user with smooth switching of maps. It is used to request the device projection coordination. This response is received as Msg_ID_DevProjCoordinate. The user needs to setup a callback function using Msg_UpdateCallback to receive and process the message with message id Msg_ID_DevProjCoordinate.

Syntax (Prototyped in alkmsg.h)

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

Parameters

Return Value

• 0 - Error

• 0 - Success

Msg_DevProjCoordinateGet

This API is used to parse the message which is returned with message Msg_ID_DevProjCoordinate. This is returned when called via Msg_SendDevProjCoordinationReq and the information matching the in build map location is requested.

Syntax (Prototyped in alkmsg.h)

long Msg_DevProjCoordinateGet(void *pMsg,
                              long &lTopLeftLat,
                              long &lTopLeftLon,
                              long &lBottomRightLat,
                              long &lBottomRightLon,
                              long &lLeft,
                              long &lTop,
                              long &lRight,
                              long &lBottom);

Parameters

Return Value

• ≤ 0 - Failed

• 0 - Success