Skip to content

MapDataMgr

Note

All React Native methods are async functions.

This class details APIs available to Trimble MAPS partners and customers to manage the map data on a device. The map data that will be available to you is linked to the license that is active on the device.


MapDataMgr

Overview
Description A class that helps determine what, if any, map data is installed or licensed. It also processes map download requests. The list of Map regions can be found by using the native constant MapRegion.
Supported on React Native Since Version 10.14
Type Class

Methods

Method Name Return Type Description
getInstalledMaps() List<​MapInfo> Returns a list of the map data sets that are currently installed on the device.
getLicensedMapList () List< MapRegion > Returns a list of Map Regions that are currently licensed on a device.
checkMapUpdate(MapRegion set) MapInfo Checks if there is a download available for a specific map region.
downloadMap(List<​MapRegion> mapRegionList, List<​MapDataComponent> disabledComponents, int year, int quarter, String mapDataVersionString, boolean bOverwriteExistingMaps) MapDownloadResponse This API will allow users to download a map set based on a specified list of map regions, years and quarters, and disabled components
pauseMapDownload (MapRegion set) MapDownloadResponse Pauses the map download of a specific MapRegion once its download has begun.
resumeMapDownload(MapRegion set) MapDownloadResponse Resumes a paused map download of a specific MapRegion.
cancelMapDownload (MapRegion set) MapDownloadResponse This API cancels the active download of the specific MapRegion.
deleteMap (MapRegion set) MapDownloadResponse This API deletes a specific installed MapRegion from the device.
getMapSureOverride(boolean inc) void This API will cause CoPilot to trigger a override sync from MapExact, our licensed online map-editing tool. This process will check for, download, and integrate any available updates from the associated MapExact account.
resetAndDeleteMapSureOverride() void This API will result in CoPilot removing any MapExact overrides that have been locally integrated.

Map Download Overview

This section outlines a use case of SDK Libraries Map Downloads, which illustrates how the APIs can be used.

The process flow below indicates the logic present within CoPilot for map downloads. (Click to enlarge.)

OTA Map Download

When a map download is requested, notifications become available. To receive the callback notifications, registerForMapDataUpdates must be used to register for the callbacks. This returns relevant information regarding the download request’s status. The statuses that may be returned are:

  • Downloading
  • Cancelled
  • Paused

To limit map downloads to only take place when connected to Wi-Fi the following configuration setting should be set within the user.cfg. This can be manually copied into the user.cfg file or the configuration setting APIs can be used with the value MAP_DOWNLOADS_WIFI_ONLY.

[Download]
"WiFiOnly"=1

In order to black list certain Wi-Fi hotspots, these should be set under the configuration setting WIFI_HOTSPOT_TOKEN. Further details on setting configuration values can be found under the CopilotMgr API class.

Please note the default value for this setting will allow for download of map data over Wi-Fi or mobile data connection.

Use Case

Before you start the download of map data, the following steps should be performed to check if the map data should be overwritten or downloaded alongside the current map data. To carry out these functions MapDataMgr.downloadMap should be used.

Step 1: Determine if a map data download should overwrite existing data or add to it. In the case where existing maps should be overwritten, bOverwriteExistingMaps should be set to true; if the downloaded maps should add to the existing map data this flag should be set to false.

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.

Step 2: Determine components to be disabled for the transaction. Components that currently support disabling are POIs, Speed Limit data, and Traffic data.

Step 3: Perform Download. Depending on the setting of bOverwriteExistingMaps there can be a series of outcomes.

  1. bOverwriteExistingMaps set to true:

    1. If there is a map currently downloading with bOverwriteExistingMaps set to true, the current map download is canceled and replaced with the new request, also with bOverwriteExistingMaps set to true.

    2. If there is a map currently downloading with bOverwriteExistingMaps set to false, the new request with bOverwriteExistingMaps set to true fails. All requests must be processed before continuing.

  2. bOverwriteExistingMaps set to false:

    1. If there is a map currently downloading with bOverwriteExistingMaps set to true, the new request with bOverwriteExistingMaps set to false fails. All requests must be processed before continuing.

    2. If there is a map currently downloading with bOverwriteExistingMaps set to false, the new request with bOverwriteExistingMaps set to false is placed into a queue and will download after the current download finishes.

Step 4: Once the set finishes download and the device is in an idle state, CoPilot will perform the data switch. CoPilot is in an idle state when there is no active route and it is on the navigation window or on the download page.

Note that once an overwrite request has been committed it has to be finished before any other download action can be taken. This includes downloading without overwriting, pausing, resuming or deleting any maps.

Network Detection

The network a device is connected to may be switched during the map data download. Depending on the connection speed and the size of the file, the download may take some time. If the network does change during the download the behavior is detailed below.

Network Switch (From – To) Behavior
Wi-Fi to Cellular Data If WiFiOnly = 1, pause download, else continue
MiFi to Cellular Data If WiFiOnly = 1, pause download, else continue
Cellular Data to Wi-Fi Continue downloading
Cellular Data to MiFi If WiFiOnly = 1, pause download, else continue
Wi-Fi to MiFi If WiFiOnly = 1, pause download, else continue
MiFi to Wi-Fi Continue downloading
WiFi to Wi-Fi Continue downloading
MiFi to MiFi If WiFiOnly = 1, pause download, else continue

Map Download controls

If there is a download currently processing, the following actions can be performed:

  • Pause a download using pauseMapDownload. This will stop the download with the given MapSetID but will not terminate it.

  • Resume a download by using resumeMapDownload. This will resume a paused download.

  • Cancel a download by using cancelMapDownload. This will stop the download and remove it from the download queue.

Return Code Description
SUCCESS Request successfully enqueued.
FAILURE_INVALID_CONNECTION Device is using cellular data, but the “WiFiOnly” option is enabled.
FAILURE_INVALID_ARGUMENT Arguments are invalid. Either the map set IDs are not valid, URL doesn’t exist or the input list is empty.
FAILURE_MANAGER_BUSY Limitations of certain operations allow for only one request to be processed at a time.
FAILURE_PREPROCESSING Dialed to retrieve URL, inputs were invalid, the connection was invalid, or the manager is handling an operation. Check log for details.
FAILURE_VALIDATION Failed to validate request. This flag gets expanded on the codes below.
FAILURE_VERSION There was a version mismatch with what is being downloaded and the new request, or if performing a map addition, what is already installed.
FAILURE_INSTALLED The requested set is already installed. Please note this is only returned if all members of a set are installed.
FAILURE_DOWNLOADING The requested set is already downloading.
FAILURE_DOWNLOADED The requested set is already downloaded, pending installation.
FAILURE_PAUSED The requested set is paused.
FAILURE_CANCELLED The requested set is cancelled.
FAILURE_UNLICENSED The requested set is unlicensed for the user.
FAILURE_ENQUEUE Failed to add download to the download queue.
FAILURE_INSUFFICIENT_DISK_SPACE Insufficient disk space for the triggered download.
FAILURE_PREINSTALLED Attempted download request with pre-installed data.
FAILED_GENERIC_ERROR Generic error, which should not be triggered unless no additional information could be collected.

MapDataMgr.getInstalledMaps

Overview
Description This method returns a list the map data sets that are currently installed on a device. All information will be displayed within a list. If no data is provided this indicates that no maps are currently installed on the device.
Supported on React Native Since Version 10.14
Type Method

Syntax

JSONArray getInstalledMaps()

Parameters

None

Return Value

Returns a JSON array of MapInfo JSON objects that detail the year, quarter, filename, download size, etc.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
var installedMaps = await MapDataMgr.getInstalledMaps();

Hooks and Callbacks

Hooks and Callbacks related to Map Data can be found below.

MapDataListener
onMapdataUpdate
selectMapRegion
onMapSureOverrideSyncStarted
onMapSureOverrideSyncFailed
onMapSureOverrideSyncSuccess
onReadyToDownloadInitialMapData

MapDataMgr.getLicensedMapList

Overview
Description This method returns a list of Map Regions currently licensed on a device. If the list is empty, licensing for maps has not been set.
Supported on React Native Since Version 10.14
Type Method

Syntax

constant getLicensedMapList()

Parameters

None

Return Value

Returns a list of MapRegion.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
var installedMaps = await MapDataMgr.getLicensedMapList();

MapDataMgr.checkMapUpdate

Note

This call performs a synchronous web call and should be done on a separate thread so execution is not halted.

Overview
Description This method checks if there is a download available for a map region. It returns the latest version of the map if it is available, but will not initiate a download. If a map region update is available, information about the region including the map data year, and quarter can be provided.

This action can only be performed if there is sufficient storage space on the device. If a user does not have sufficient space, we recommend manually removing the data folders from the device and then using the API to download the maps.

Supported on React Native Since Version 10.14
Type Method

Syntax

JSONObject checkMapUpdate(set, year, quarter)

Parameters

set - A MapRegion to query for update.

year - Int value for the year

quarter - Int value for the quarter

Return Value

MapInfo JSON object containing the newest year and quarter available will be returned. If there is no map data available for the specified region, null wil be returned.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
const MapRegion = NativeModules.MapRegion;

var mapInfo = await MapDataMgr.checkMapUpdate(
  MapRegion.NORTH_AMERICA_Eastern,
  2018,
  4
);

MapDataMgr.pauseMapDownload

Note

This API is not useable when a download uses the bOverwriteExistingMaps parameter set to true. If this API is used when the parameter is set to true, the error FAILURE_MANAGER_BUSY will be returned. This API is only available when downloading a map update not an initial install or when the map data is being overwritten.

Overview
Description If the download of a specific MapRegion is in currently in progress, this API can be used to pause the download. If the download is not in progress, calling this API will have no effect.
Supported on React Native Since Version 10.14
Type Method

Syntax

constant pauseMapDownload(set)

Parameters

set - The MapRegion to pause.

Return Value

Returns a MapDownloadResponse with the download status.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
const MapRegion = NativeModules.MapRegion;

var response = await MapDataMgr.pauseMapDownload(
  MapRegion.NORTH_AMERICA_Eastern
);

MapDataMgr.resumeMapDownload

Note

This API is not useable when a download uses the bOverwriteExistingMaps parameter set to true. If this API is used when the parameter is set to true, the error FAILURE_MANAGER_BUSY will be returned.

Overview
Description Resumes a paused download of a specific MapRegion.
Supported on React Native Since Version 10.14
Type Method

Syntax

constant resumeMapDownload(set)

Parameters

set - The MapRegion to resume downloading.

Return Value

Returns a MapDownloadResponse with the download status.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
const MapRegion = NativeModules.MapRegion;

var response = await MapDataMgr.resumeMapDownload(
  MapRegion.NORTH_AMERICA_Eastern
);

MapDataMgr.cancelMapDownload

Note

This API is not useable when a download uses the bOverwriteExistingMaps parameter set to true. If this API is used when the parameter is set to true, the error FAILURE_MANAGER_BUSY will be returned.

Overview
Description If a specific map region is downloading, this API can be used to cancel the download. It will only be successful if the correct map region is selected and the map is currently downloading. If the download has completed and needs to be deleted from the device, MapDataMgr.deleteMap should be used.
Supported on React Native Since Version 10.14
Type Method

Syntax

constant cancelMapDownload(set)

Parameters

set - The MapRegion to cancel downloading.

Return Value

Returns a MapDownloadResponse with the download status.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
const MapRegion = NativeModules.MapRegion;

var response = await MapDataMgr.cancelMapDownload(
  MapRegion.NORTH_AMERICA_Eastern
);

MapDataMgr.deleteMap

Note

This API is not useable when a download uses the bOverwriteExistingMaps parameter set to true. If this API is used when the parameter is set to true, the error FAILURE_MANAGER_BUSY will be returned.

Overview
Description This API can be used to delete a specific MapRegion from a device. If the selected MapRegion is currently downloading, the download will not be deleted or paused. If a download should be canceled, use MapDataMgr.cancelMapDownload instead.
Supported on React Native Since Version 10.14
Type Method

Syntax

constant deleteMap(set)

Parameters

set - The MapRegion to delete.

Return Value

Returns a MapDownloadResponse with the download status.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
const MapRegion = NativeModules.MapRegion;

var response = await MapDataMgr.deleteMap(MapRegion.NORTH_AMERICA_Eastern);

MapDataMgr.downloadMap

Notes

This call performs a synchronous web call and should be done on a separate thread so execution is not halted.

If the bOverwriteExistingMaps parameter is false, the version of the new data to be downloaded alongside the existing map data must be identical to the version already installed on the device.

If the bOverwriteExistingMaps parameter is true, only one download request can be handled at a time.

Overview
Description This API downloads a map set. Beforehand, this API validates the request against the current license, and if there is enough space to download the specified map, it will initiate the download.

This API can be used to download the most recent data available or to request a specific year, quarter, or version string is required, depending on the parameters you enter.

Supported on React Native Since Version 10.14
Type Method

Syntax

constant downloadMap(mapRegionList, disabledComponentsList, year, quarter, mapVersionString, bOverwriteExistingMaps)

Parameters

mapRegionList - Array of MapRegion. The parameter is required.

disabledComponentsList - The list of components to disable as an array of MapDataComponent. These components will not be downloaded with the map data. This parameter is required.

year - An int value for the year of the map to download. If this parameter is provided, the quarter must also be provided. This parameter is optional if you do not want to specify the date, and simply want to request most recent map data available. However, you must enter a value as a placeholder. (See sample code below.)

quarter - An int value quarter of the map to download. If this parameter is provided, the year must also be provided. This parameter is optional if you do not want to specify the date, and simply want to request most recent map data available. However, you must enter a value as a placeholder. (See sample code below.)

mapDataVersionString - The specific grid version string to download. If this parameter is provided, year and quarter must also be provided. This parameter is optional if you do not want to specify the date, and simply want to request most recent map data available. However, you must enter a value as a placeholder. (See sample code below.)

bOverwriteExistingMaps - A boolean value for whether to download the new maps in addition to the existing maps or to replace the existing maps with the new maps.

Return Value

Returns a MapDownloadResponse with the map's download status.

Sample Code

const MapDataMgr = NativeModules.MapDataMgr;
const MapRegion = NativeModules.MapRegion;
const MapDataComponent = NativeModules.MapDataComponent;

var mapRegionList = [];
mapRegionList.push(MapRegion.NORTH_AMERICA_Eastern);
mapRegionList.push(MapRegion.NORTH_AMERICA_South);

var disabledComponentsList = [];
comps.push(MapDataComponent.COMPONENT_POI);

//Use the format below to request map data from a specific time period
var response = await MapDataMgr.downloadMap(
  mapRegionList,
  disabledComponentsList,
  2015,
  4,
  "1.1.1.1",
  true
);

//Use this format to request most recent map data available
var response = await MapDataMgr.downloadMap(
  mapRegionList,
  disabledComponentsList,
  -1,
  -1,
  null,
  true
);

Last update: September 1, 2020