MapDataMgr (React Native)

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

Methods

List<​MapInfo>

List< MapRegion>

MapInfo

MapDownloadResponse

MapDownloadResponse

MapDownloadResponse

MapDownloadResponse

MapDownloadResponse

Map 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.

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

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

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

Copilot can blocklist or allowlist certain Wi-Fi hotspots. These should be set under the configuration setting WIFI_HOTSPOT_TOKEN for blocklisted hotspots and WIFI_ALLOWLIST_TOKEN for allowlisted hotspots. The type of Wi-Fi SSID filtering must be specified in the configuration setting WIFI_FILTER_TYPE with the values WIFI_FILTER_NOT_CONFIGURED, WIFI_FILTER_HOTSPOT_TOKEN (Default value), or WIFI_FILTER_ALLOWLIST_TOKEN. Only one of these filters is can be enabled at a time.

Use Case

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.

The following steps should also 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.

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.

MapDataMgr.getInstalledMaps

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.

MapDataMgr.getLicensedMapList

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.

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

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.

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

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.

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.

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
);