Map Data

Map Data Download - Overview

This section outlines a use case of CPIK Map Downloads, which illustrates how the APIs can be used to download data over the air via Wi-Fi or a wireless internet connection.

Note: To limit map downloads to only take place when connected to Wi-Fi the following config should be set within the user.cfg. This can be manually copied into the user.cfg file or passed via the configuration APIs. Note: This setting does not apply to Windows laptop versions of CoPilot, which cannot detect if a device is connected to the internet via Wi-Fi or a cellular network.

`[Download]` <br>
`"WiFiOnly"=1`

Tip: If you wish to blocklist or allowlist certain Wi-Fi hotspots these should be set under the configuration setting:
[User Settings]
“WifiFilterType”=#
“WifiHotSpotToken”=XX
“WifiAllowListToken”=XX
Further details on setting configuration values can be found under the Msg_ConfigSetIntVal API details.

Download a Map using CoPilot SDK APIs

Before you start the download of map data, be sure the device has enough storage for the download. When unpacking the installation files, CoPilot requires at least 1.5 times as much free disk space as the size of a map download. (For example, a 2.7 GB download of CoPilot map data for all of North America would require 4.05 GB of free space). After the installation of CoPilot, the unused space is released again.

We recommended that you initially download map data via Msg_MapActionRequestSpecific as this allows a specific data version to be requested, ensuring consistent map data is downloaded throughout all CoPilot deployments. It is also possible to use Msg_MapActionRequestGeneric to download the latest map data. The current download status can be found by passing RequestDownloadStatus via either of the above listed map download APIs.

Subsequent map updates should be completed using Msg_DownloadMap. Msg_DownloadMap overwrites the existing map data with new data, while Msg_MapActionRequestSpecific and Msg_MapActionRequestGeneric download new data into a separate folder.

Before a download is requested, we also recommend that you perform one of the following checks using the Msg_MapActionRequestSpecific or Msg_MapActionRequestGeneric.

If this is the first installation of map data

• In this scenario it is recommended that RequestLicensedMaps is called to check the map data sets that are licensed on CoPilot. From this list the desired region should be requested for download.

If this is an update to existing map data

• RequestInstalledMaps to receive the list of installed map data
• Then follow up with RequestUpdate to check if map data is available for update.
• If an update is available, RequestDownload should then be called to download the desired region and version.

Note: When updating map data for a single region, once locked to this region you can only update that data which is already present on the device and cannot be used in conjunction with other map regions.

If there is a download currently being processed

• Pause a download by using RequestPause. This will stop the download with the given MapSetID, but will not terminate it.
• Resume a download by using RequestResume. This will resume a paused download. For overwrite requests, resuming any of the downloads in the set, will resume the entire set.
• Cancel a download by using RequestCancel. This will stop the download and remove it from the download queue. For overwrite requests, cancelling any of the downloads in the set, will cancel the entire set.
• Get the status of a download by using RequestDownloadStatus. This will return the current status of a specified dataset.
  • DLStatusUnknown - Error Case
  • DLDownloading - Currently Downloading
  • DLSucceeded - Download finished successfully
  • DLFailed - Download Failed
  • DLPaused - Download is currently paused
  • DLNotInitiated - Download has not been started

Msg_MapActionRequestSpecific

Syntax (Prototyped in alkmsg.h)

Int Msg_MapActionRequestSpecific (EMapRequestType eType, EMapRegion iMapID,
                                  int iYear, int iQuarter);
enum EMapRequestType {
      RequestUnknown,       //Should not be used
      RequestPause,         //Used to request a map be paused
      RequestDownload,      //Request a map to start downloading
      RequestCancel,        //Request a map download to cancel
      RequestDelete,        //Request a map to be deleted
      RequestUpdate,        //Request to query for a map update
      RequestInstalledMaps, //Request to received installed maps
      RequestLicensedMaps,  //Request to received licensed maps
      RequestDownloadStatus //Request to receive a map download status
};

This API can be used to do send the following requests.

1. Checking the availability of a specific map

• Msg_ MapActionRequestSpecific(RequestUpdate, ENORTH_AMERICA_South, 2014, 4);

2. Start/Pause/Resume/Cancel – download process

• Msg_ MapActionRequestSpecific(RequestDownload, ENORTH_AMERICA_South, 2014, 4);

• Msg_ MapActionRequestSpecific(RequestPause, ENORTH_AMERICA_South, 2014, 4);

Parameters

Return Value

• Will be -1 or some other positive value. Return value of -1 signifies that the API failed and message was not sent to CoPilot. Positive value signifies that the APIs executed successfully and request was sent.

• This does not verify that the client app is connected to CoPilot. Please use Msg_IsConnected to verify that you are connected.

Note: This API is to be used with Msg_MapAddActionRequestCallback to receive the notifications.

EMapRequestType Values

• RequestPause Pause a map download.
• RequestDownload Start downloading a map.
• RequestCancel Cancel a currently downloading map.
• RequestDelete Delete a non-downloading map.
• RequestUpdate Query if a map is available.
• RequestInstalledMaps Query for a list of installed maps.
• RequestLicensedMaps Query for a list of licensed maps.
• RequestDownloadStatus Query a map download status.

Msg_MapActionRequestGeneric

This API can be used to do send the following requests.

1. Checking the availability of a specific map. Since the year and quarter are not required, the latest available will be requested

• Msg_ MapActionRequestGeneric (RequestUpdate, ENORTH_AMERICA_South);

2. Start/Pause/Resume/Cancel download process. This will download the latest version map, if available.

   • Msg_ MapActionRequestGeneric (RequestDownload, ENORTH_AMERICA_South);
   • Msg_ MapActionRequestGeneric (RequestPause, ENORTH_AMERICA_South);
   • Msg_ MapActionRequestGeneric (RequestDownload, ENORTH_AMERICA_South);
   • Msg_ MapActionRequestGeneric (RequestCancel, ENORTH_AMERICA_South);

Syntax (Prototyped in alkmsg.h)

int Msg_MapActionRequestGeneric (EMapRequestType eType, EMapRegion iMapID);
enum EMapRequestType {
 RequestUnknown,       //Should not be used
 RequestPause,         //Used to request a map be paused
 RequestDownload,      //Request a map to start downloading
 RequestCancel,        //Request a map download to cancel
 RequestUpdate,        //Request to query for a map update
 RequestInstalledMaps, //Request to received installed maps
 RequestLicensedMaps,  //Request to received licensed maps
 RequestDownloadStatus //Request to receive a map download status
 RequestResume         //Request to resume a paused map download
};

Parameters

Return Value

• Will be -1 or some other positive value. Return value of -1 signifies that the API failed and message was not sent to CoPilot. Positive value signifies that the APIs executed successfully and request was sent.

• This does not verify that the client app is connected to CoPilot. Please use Msg_IsConnected to verify that you are connected.

Note: - This API is to be used with Msg_MapAddActionRequestCallback to receive the notifications. - Enum RequestDelete should not be used with this API, use MapActionRequestSpecific instead. It requires a specific quarter and year to be deleted. - Since the quarter and year are not required, the latest version will be requested for types RequestDownload and RequestUpdate. - If request type RequestInstalledMaps or RequestLicensedMaps is used, the remaining parameter, EMapRegion, is ignored, as it is unnecessary for this request type.

EMapRequestType Values

RequestPause Used to pause a map download. RequestDownload Used to have a map start downloading. RequestCancel Used to cancel a currently downloading map. RequestUpdate Used to query if a map is available. RequestInstalledMaps Used to query for a list of installed maps. RequestLicensedMaps Used to query for a list of licensed maps. RequestDownloadStatus Used to query a map download status. RequestResume Used to resume a paused map download

Msg_MapActionRequestDataList

Requests not related to RequestInstalledMaps and RequestLicensedMaps sent through this API will fail, as they require at least an eRegion to perform the request.

This API can be used to do send the following requests:

1. Get the currently installed maps.

• Msg_MapActionRequestDataList (RequestInstalledMaps);

2. Get the currently licensed maps.

• Msg_MapActionRequestDataList (RequestLicensedMaps);

Syntax (Prototyped in alkmsg.h)

Int Msg_MapActionRequestDataList (EMapRequestType eType);
enum EMapRequestType {
RequestUnknown,       //Should not be used
RequestInstalledMaps, //Request to received installed maps
RequestLicensedMaps,  //Request to received licensed maps
};

Parameters

• EMapRequestType - Should be one of RequestLicensedMaps or RequestInstalledMaps.

Return Value

• Will be -1 or some other positive value. Return value of -1 signifies that the API failed and message was not sent to CoPilot. Positive value signifies that the APIs executed successfully and request was sent.

• This does not verify that the client app is connected to CoPilot. Please use Msg_IsConnected to verify that you are connected.

Note

• This API is to be used with Msg_MapAddActionRequestCallback to receive the notifications.

• Any other request type other than RequestLicensedMaps or RequestInstalledMap will fail.

  EMapRequestType Values

• RequestInstalledMaps Used to query for a list of installed maps.
• RequestLicensedMaps Used to query for a list of licensed maps

Msg_MapAddActionRequestCallback

Syntax (Prototyped in alkmsg.h)

long Msg_MapAddActionRequestCallback (void *fnProcessMsg, callingConvention
convention = convention_default);

Parameters

Return Value

• -1 - Signifies that there was an error
• ≤0 - Signifies that value is set successfully

Enum

enum callingConvention {
convention_default,
convention_cdecl,
convention_stdcall
};

MapActionRequestCB

Note: In order to get more details about implementation of MapInfo, please refer to the SDK Sample Application. Implementation of .NET can be found in C# sample application.

Syntax (Prototyped in alkmsg.h)

typedef int (_CONVENTION * MapActionRequestCB) (EMapRequestType eType,
EDataRequestResult eStatus,const char* pMap, int numBytes);

Parameters

enum EMapRequestType {
  RequestUnknown,       //Should not be used
  RequestPause,         //Used to request a map be paused
  RequestDownload,      //Request a map to start downloading
  RequestCancel,        //Request a map download to cancel
  RequestUpdate,        //Request to query for a map update
  RequestInstalledMaps, //Request to received installed maps
  RequestLicensedMaps,  //Request to received licensed maps
  RequestDownloadStatus, //Request to receive a map download status
  RequestResume,         //Request to resume a paused map download
};

enum EDataRequestResult {
  DRM_REQUEST_UNKNOWN,
  DRM_REQUEST_SUCCESS,
  DRM_REQUEST_FAILURE_PREPROCESSING,
  DRM_REQUEST_FAILURE_VALIDATION,
  DRM_REQUEST_FAILURE_VERSION,
  DRM_REQUEST_FAILURE_INSTALLED,
  DRM_REQUEST_FAILURE_DOWNLOADING,
  DRM_REQUEST_FAILURE_DOWNLOADED,
  DRM_REQUEST_FAILURE_PAUSED,
  DRM_REQUEST_FAILURE_CANCELLED,
  DRM_REQUEST_FAILURE_UNLICENSED,
  DRM_REQUEST_FAILURE_ENQUEUE,
  DRM_REQUEST_FAILURE_INSUFFICIENT_DISK_SPACE,
  DRM_REQUEST_FAILURE};
}

Note

• Client Application will need to define its own callback function of the type “MapActionRequestCB”

• MAP_SUCCESS should be used as a general success case.

• If the request of either, RequestInstalledMaps or RequestLicensedMaps is sent, parameter const char* pMap will be an array of MapInfo structs. All other request types will return a single MapInfo struct.

Msg_MapAddDownloadStatusCallback

Syntax (Prototyped in alkmsg.h)

long Msg_MapAddDownloadStatusCallback (void *fnProcessMsg, callingConvention
convention = convention_default);

Parameters

Return Value

• -1 - Signifies that there was an error
• ≤0 - Signifies that value is set successfully

Enum

enum callingConvention {
convention_default,
convention_cdecl,
convention_stdcall
};

MapDownloadStatusCB

Notes: In order to get more details about implementation of MapInfo, please refer to the SDK Sample Application. Implementation of .NET can be found in C# sample application

Syntax (Prototyped in alkmsg.h)

typedef long (_CONVENTION * 0.122805StatusCB) (EDownloadStatus eStatus, const
char* pMap, int numBytes);

Parameters

enum EDownloadStatus {
DLStatusUnknown //Error case
DLDownloading   //Currently downloading
DLSucceeded     //Download finished successfully
DLCanceled      //Download was canceled
DLFailed        //Download failed
DLPaused        //Download is currently paused
DLNotInitiated  //Download has no been started
};

Note: * Client Application will need to define its own callback function of the type MapDownloadStatusCB

Msg_DownloadMap

Syntax (Prototyped in alkmsg.h)

Int Msg_DownloadMap (EMapRegion[] mapRegionList, int mapRegionListLen, EMapDataComponent[] disabledComponentList, int disabledComponentListLen, int iYear, int iQuarter, byte[] mapDataVersionString, bool bOverwriteExistingMaps);

enum EMapDataComponent

{
  COMPONENT_POI,
  COMPONENT_TRAFFIC,
  COMPONENT_SPEEDLIMIT
};

Parameters

• mapRegionList - List of map regions to include in the download.

• mapRegionListLen – The length of the map region list.

• disabledComponentList – A list of components NOT to download with the map data.

• disabledComponentListLen – The length of the disabled component list.

• iYear – A specific year to download. If this is included, the quarter must also be included. To get the most recent maps, rather than specifying a specific version, pass -1.

• iQuarter – A specific quarter tpo download. If this is included, the year must also be included. To get the most recent maps, rather than specifying a specific version, pass -1.

• mapDataVersionString – A specific grid version to download. If this parameter is used, both year and quarter must also be used. To get the most recent maps, pass empty string for this parameter.

• bOverwriteExistingMaps – If this is true, the currently installed maps will be overwritten by the downloaded maps when the download completes. If false, the newly downloaded maps will be installed alongside any existing maps.

Return Value

• Will be -1 or some other positive value. Return value of -1 signifies that the API failed and message was not sent to CoPilot. Positive value signifies that the APIs executed successfully and request was sent.

• This does not verify that the client app is connected to CoPilot. Please use Msg_IsConnected to verify that you are connected.

Note

This API is to be used with Msg_MapAddActionRequestCallback to receive the notifications.

Msg_MapUpdate

Syntax (Prototyped in alkmsg.h)

long Msg_MapUpdate(EFunction efunc,
   EProcess eProcess);

enum EFunction {
DD_NONE = 0, //Send with P_QUERY and P_SWITCH request only
DD_START,    //Send to start/resume the downloading/patching process
DD_PAUSE,    //Send to pause the downloading/patching process
DD_CANCEL    //Send to cancel the downloading/patching process
};

enum EProcess {
P_NONE = 0, //Should never be used
P_QUERY,    //Send this message when sending a query status request
P_DOWNLOAD, //Send this message when sending a download request
P_PATCHING, //Send this message when sending a patching request
P_SWITCH    //Send this message when sending a switching request
};

Description

This API can be used to do send the following requests.

1. Checking the availability of the map update

• Msg_MapUpdate(DD_NONE , P_QUERY);

2. Start/Pause/Resume/Cancel – download process

• Msg_MapUpdate(DD_START, P_DOWNLOADING);
• Msg_MapUpdate(DD_PAUSE, P_DOWNLOADING);
• Msg_MapUpdate(DD_CANCEL, P_DOWNLOADING);

3. Start/Pause/Resume/Cancel – patch process

• Msg_MapUpdate(DD_START, P_PATCHING);
• Msg_MapUpdate(DD_PAUSE, P_PATCHING);
• Msg_MapUpdate(DD_CANCEL, P_PATCHING);

4. Start the switch process.

• Msg_MapUpdate(DD_NONE, P_SWITCHING);

Parameters

• EFunction - Should be one of the values of enum EFunction (Not used with Switching process).
• EProcess - Should be one of the values of enum EProcess.

Return Value

• Will be -1 or some other positive value. Return value of -1 signifies that the API failed and message was not sent to CoPilot. Positive value signifies that the APIs executed successfully and request was sent.

• This does not verify that the client app is connected to CoPilot. Please use Msg_IsConnected to verify that you are connected.

Note

EFunction Values (Controls the behavior of Downloading/Patching Process)

• DD_START – will Start/Resume the corresponding process.
• DD_PAUSE – will Pause the corresponding process.
• DD_CANCEL – will Cancel the process and delete the files.

EProcess Values

• P_QUERY – request the status of the map update process.
• P_DOWNLOADING – will take the action defined by EFunction for the

Downloading Process.

• P_PATCHING – will take the action defined by EFunction for the Patching Process.
• P_SWITCH – will request the CoPilot to Switch to a new data.
• For P_QUERY and P_SWITCH – only DD_NONE should be used.
• For Downloading/Patching process – every Pause and Cancel Call should be preceded by a corresponding Start call.
• Download Process should precede the Patching Process.
• This API is to be used with Msg_AddMapUpdateCallback to receive the notifications.
• Please refer to “mapupdate_flowchart.pdf” for sequence of calls and what action to take.

Msg_AddMapUpdateCallback

Syntax (Prototyped in alkmsg.h)

long Msg_AddMapUpdateCallback (void *fnProcessMsg, callingConvention
convention = convention_default);

Parameters

For Android and using JNI layer

Syntax (Prototyped in AlkMsg.java)

long Msg_AddMapUpdateCallback (String callbackFunctionName,
   int convention,
   Object callBackObj);

Parameters

Return Value

• -1 - Signifies that there was an error

• ≤0 - Signifies that value is set successfully

Enum

enum callingConvention{
  convention_default,
  convention_cdecl,
  convention_stdcall
};

MsgHandlerMapUpdate

Syntax (Prototyped in alkmsg.h)

typedef long (_CONVENTION *MsgHandlerMapUpdate) (const char* pFlexName,
   EFunction efunc,
   EProcess eProcess,
   int iResponse,
   int iCurrent,
   int iTotal);

For Android and using JNI layer

Syntax (Prototyped in AlkMsg.java)

void MsgHandlerMapUpdate(String pFlexName,
   int efunc,
   int eProcess,
   int iResponse,
   int iCurrent,
   int iTotal);

Parameters

enum EDiffStatus {
  EUnknown = 0,
  ENoUpdate,
  EUpdateAvailable,
  EDownloading,
  EDownloadPaused,
  EDownloadCompleted,
  EDownloadError,
  EDownloadCancelled,
  EPatching,
  EPatchCompleted,
  EPatchError,
  EPatchPaused,
  EPatchCancelled,
  ESwitching,
  ESwitchCompleted,
  ESwitchError
};

Note

• Client Application will need to define its own callback function of the type “MsgHandlerMapUpdate”
• “iResponse” Parameter of “MsgHandlerMapUpdate” will return one of the status from the “EDiffStatus”
• If P_QUERY – process returns the EUpdateAvailable, then next step should be to request CoPilot to download the update using Msg_MapUpdate(DD_START, P_DOWNLOADING);
• “Patching” process can only be started once “EDownloadCompleted” Status is received.
• “Switch” process can only be started once “EPatchCompleted” Status is received.

Note

• Before using Map Update APIs, please set the following config value in CoPilot user.cfg –

[SDK] "AutomateMapUpdate"=0

This can be done using

Msg_ConfigSetIntVal("SDK", "AutomateMapUpdate", 0);