Skip to main content

MapDataMgr (React Native)

Contents

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
DescriptionA 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 Version10.14
TypeClass

Methods

Method NameReturn TypeDescription
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.

Map Download Overview

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

The process flow below indicates the logic present within CoPilot for map downloads.

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. 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]
"WiFiOnly"=1

In order to blocklist 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 DataIf WiFiOnly = 1, pause download, else continue
MiFi to Cellular DataIf WiFiOnly = 1, pause download, else continue
Cellular Data to Wi-FiContinue downloading
Cellular Data to MiFiIf WiFiOnly = 1, pause download, else continue
Wi-Fi to MiFiIf WiFiOnly = 1, pause download, else continue
MiFi to Wi-FiContinue downloading
WiFi to Wi-FiContinue downloading
MiFi to MiFiIf 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 CodeDescription
SUCCESSRequest successfully enqueued.
FAILURE_INVALID_CONNECTIONDevice is using cellular data, but the “WiFiOnly” option is enabled.
FAILURE_INVALID_ARGUMENTArguments are invalid. Either the map set IDs are not valid, URL doesn’t exist or the input list is empty.
FAILURE_MANAGER_BUSYLimitations of certain operations allow for only one request to be processed at a time.
FAILURE_PREPROCESSINGDialed to retrieve URL, inputs were invalid, the connection was invalid, or the manager is handling an operation. Check log for details.
FAILURE_VALIDATIONFailed to validate request. This flag gets expanded on the codes below.
FAILURE_VERSIONThere was a version mismatch with what is being downloaded and the new request, or if performing a map addition, what is already installed.
FAILURE_INSTALLEDThe requested set is already installed. Please note this is only returned if all members of a set are installed.
FAILURE_DOWNLOADINGThe requested set is already downloading.
FAILURE_DOWNLOADEDThe requested set is already downloaded, pending installation.
FAILURE_PAUSEDThe requested set is paused.
FAILURE_CANCELLEDThe requested set is cancelled.
FAILURE_UNLICENSEDThe requested set is unlicensed for the user.
FAILURE_ENQUEUEFailed to add download to the download queue.
FAILURE_INSUFFICIENT_DISK_SPACEInsufficient disk space for the triggered download.
FAILURE_PREINSTALLEDAttempted download request with pre-installed data.
FAILED_GENERIC_ERRORGeneric error, which should not be triggered unless no additional information could be collected.

MapDataMgr.getInstalledMaps

Overview
DescriptionThis 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 Version10.14
TypeMethod

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
DescriptionThis 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 Version10.14
TypeMethod

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
DescriptionThis 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 Version10.14
TypeMethod

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

Overview
DescriptionIf 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 Version10.14
TypeMethod

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
DescriptionResumes a paused download of a specific MapRegion.
Supported on React Native Since Version10.14
TypeMethod

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
DescriptionIf 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 Version10.14
TypeMethod

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
DescriptionThis 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 Version10.14
TypeMethod

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
DescriptionThis 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 Version10.14
TypeMethod

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 updated September 5, 2022.
Contents