MapDataMgr (CPIK Libraries)

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

Methods

List<MapInfo>

List< MapRegion >

MapInfo

MapInfo

MapDownloadResponse

MapDownloadResponse

MapDownloadResponse

MapDownloadResponse

MapDownloadResponse

MapDownloadResponse

void

void

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.

This setting depends on what map data you have on a device and what you plan to download. For example:

• If you have New Jersey maps on a device and want to add Pennsylvania maps, set bOverwriteExistingMaps to false. (Maps of both states must be the same data version.)
• If you have New Jersey maps on a device and want to replace them with Pennsylvania maps, set bOverwriteExistingMaps to true.
• If you have New Jersey maps and want to replace them with a newer version of New Jersey maps, set bOverwriteExistingMaps to true.

Note: MapDataMgr.DownloadMap will not download existing map data on a device if it is provided as part of the Arraylist for download, the overwrite flag is set to true, and it is the same year and quarter as the existing data. For example, if New Jersey 2022 Q2 is on a device and New Jersey 2022 Q2 + Pennsylvania 2022 Q2 + New York 2022 Q2 are the map regions requested for download, CoPilot will recognize NJ 2022 Q2 is installed and proceed to download and then install only PA and NY 2022 Q2.

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.

Note: Previous to version 9.6.8.1451 these actions are disabled for instances where the download overwrite flag is set to true.

MapDataMgr.getInstalledMaps

Syntax

List <MapInfo> getInstalledMaps()

NSArray *List = [MapDataMgr getInstalledMaps]

Return Value

Returns a List object of MapInfo which contains MapInfo details year, quarter, filename, download size, etc.

Sample Code

// Print all map data sets that are currently installed
List<MapInfo> mapList = MapDataMgr.getInstalledMaps();
for (MapInfo dataSet : mapList) {
  System.out.println("Map Name " + dataSet.getName());
  System.out.println("Map Version " + dataSet.getVersion());
  System.out.println("Map Region " + dataSet.getRegion());
  System.out.println("Map Year " + dataSet.getYear());
  System.out.println("Map Quarter " + dataSet.getQuarter());
  //to print full information about the map. we can use below code
  System.out.println("Map full Information " + dataSet.toString());
}

NSArray *mapList = [MapDataMgr getInstalledMaps];
MapInfo *mapInfo = [[MapInfo alloc] init];
for(mapInfo in mapList)
{
//do something
}

MapDataMgr.getLicensedMapList

Syntax

List<MapRegion> getLicensedMapList ()

(NSArray*) getLicensedMapList

Return Value

Returns a List of MapRegion.

Sample Code

// Print all map data sets that are currently licensed
List<MapRegion> mapList = MapDataMgr. getLicensedMapList();
for (MapRegion dataSet : mapList) {
  System.out.println("LicenseMap set " + dataSet.toString());
  System.out.println("LicenseMap Description " + dataSet.getDescription());
}

NSArray *mapList = [MapDataMgr getLicensedMapList];
MapRegion *mapRegion = [[MapRegion alloc] init];
for(mapRegion in mapList)
{
//do something
}

MapDataMgr.checkMapUpdate (Specific map data)

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

Syntax

MapInfo checkMapUpdate(MapRegion set, int year, int quarter)

(MapInfo*) checkMapUpdate:(MapRegion*)set withyear:(int)year withquarter:(int)quarter

Parameters

Return Value

Returns a MapInfo object if there is an update, null otherwise. This API will also return null if the specified year and quarter is not newer than the map data already installed on the device.

Sample Code

int mYear = 2022;// Year 2022
int mQuarter = 4; // 4th quarter
MapInfo response = MapDataMgr.checkMapUpdate(MapRegion.NORTH_AMERICA_Eastern, mYear, mQuarter);
if(response != null)
  System.out.println("Map Available");
else
  System.out.println("Map Unavailable");

MapRegion *set =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapInfo *response =
[MapDataMgr checkMapUpdate:set withyear:2022, withquarter:4];
if(response != nil)
 NSLog(@"Map Available ");
else
 NSLog(@"Map Unavailable");

MapDataMgr.checkMapUpdate

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

Syntax

MapInfo checkMapUpdate (MapRegion set)

(MapInfo*) checkMapUpdate:(MapRegion *)set

Parameters

Return Value

MapInfo containing the newest year and quarter available will be returned. If there is no map data available for the specified region, null will be returned. Prior to CoPilot 10.14.0.368, this API would also return null if the device did not already have map data installed.

Sample Code

MapInfo response = MapDataMgr.checkMapUpdate(MapRegion.NORTH_AMERICA_Eastern);
if(response != null)
  System.out.println("Map Available");
else
  System.out.println("Map Unavailable");

MapRegion *set =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapInfo *response = [MapDataMgr checkMapUpdate:set];
if(response != nil)
 NSLog(@"Map Available ");
else
 NSLog(@"Map Unavailable");
else
 NSLog(@"Map could not be downloaded");

MapDataMgr.pauseMapDownload

Syntax

MapDownloadResponse pauseMapDownload (MapRegion set)

(enum MapDownloadResponse)pauseMapDownload:(MapRegion *)set

Parameters

Return Value

Returns a MapDownloadResponse object containing the map’s download status.

Sample Code

MapDownloadResponse response = MapDataMgr.pauseMapDownload(MapRegion.NORTH_AMERICA_Eastern);
if(response == MapDownloadResponse.SUCCESS)
  System.out.println("Map paused");
else
  System.out.println("Map could not be paused");

MapRegion *set = [[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapDownloadResponse response = [MapDataMgr pauseMapDownload:set];
if(response == CP_SUCCESS)
 NSLog(@“Map paused”);
else
 NSLog(@”Map could not be paused”);

MapDataMgr.resumeMapDownload

Syntax

MapDownloadResponse resumeMapDownload (MapRegion set)

(enum MapDownloadResponse)resumeMapDownload:(MapRegion *)set

Parameters

Return Value

Returns a MapDownloadResponse object that contains a map download status.

Sample Code

MapDownloadResponse response = MapDataMgr.resumeMapDownload(MapRegion.NORTH_AMERICA_Eastern);
if(response == MapDownloadResponse.SUCCESS)
  System.out.println("Map download resumed");
else
  System.out.println("Map download could not be resumed");

MapRegion *set =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapDownloadResponse response =
[MapDataMgr resumeMapDownload:set];
if(response == CP_SUCCESS)
 NSLog(@“Map download resumed”);
else
 NSLog(@”Map download could not be resumed”);

MapDataMgr.cancelMapDownload

Syntax

MapDownloadResponse cancelMapDownload (MapRegion set)

(enum MapDownloadResponse) cancelMapDownload:(MapRegion *)set;

Parameters

Return Value

Returns a MapDownloadResponse object that contains the map’s download status.

Sample Code

MapDownloadResponse response = MapDataMgr.cancelMapDownload (MapRegion.NORTH_AMERICA_Eastern);
if(response == MapDownloadResponse.SUCCESS)
  System.out.println("Map cancelled");
else
  System.out.println("Map could not be cancelled");

MapRegion *set =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapDownloadResponse response =
[MapDataMgr cancelMapDownload:set];
if(response == CP_SUCCESS)
 NSLog(@”Map cancelled”);
else
 NSLog(@”Map could not be cancelled”)

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

MapDownloadResponse deleteMap (MapRegion set)

(enum MapDownloadResponse) deleteMap:(MapRegion *)set

Parameters

Return Value

Returns a MapDownloadResponse object containing the map’s download status.

Sample Code

MapDownloadResponse response = MapDataMgr. deleteMap (MapRegion.NORTH_AMERICA_Eastern);
if(response == MapDownloadResponse.SUCCESS)
  System.out.println(“Map deleted”);
else
  System.out.println(“Map could not be deleted”);

MapRegion *set =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapDownloadResponse response =
[MapDataMgr deleteMap:set withyear:2022 withquarter:4];
if(response == CP_SUCCESS)
 NSLog(@”Map deleted”);
else
 NSLog(@”Map could not be deleted”)

MapDataMgr.downloadMap (Specific Map Data)

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

MapDownloadResponse downloadMap(List<MapRegion> mapRegionList, List<MapDataComponent> disabledComponents, int year, int quarter, String mapDataVersionString, boolean bOverwriteExistingMaps)

Parameters

Return Value

Return MapDownloadResponse object contains map download status

Sample Code

int mYear = 2022;// Year 2022
int mQuarter = 4; // 4th quarter
String mapDataVersionString = "1.1.1.1";
boolean bOverwriteExistingMaps =true;

ArrayList<MapRegion> mapRegionList = new ArrayList<MapRegion>();
mapRegionList.add(MapRegion.NORTH_AMERICA_Eastern);
mapRegionList.add(MapRegion.NORTH_AMERICA_South);

ArrayList<MapDataComponent> disabledComponentsList = new ArrayList<MapDataComponent >();
disabledComponentsList.add(MapDataComponent.COMPONENT_POI);

MapDownloadResponse response = MapDataMgr.downloadMap(mapRegionList, disabledComponentsList, mYear, mQuarter, mapDataVersionString, bOverwriteExistingMaps);
if(response == MapDownloadResponse.SUCCESS)
  System.out.println("Map downloading");
else
  System.out.println("Map could not be downloaded");

NSMutableArray * maplist = [[NSMutableArray alloc] init];
MapRegion *set1 =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapRegion *set2 =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_South];
[maplist addObject:set1];
[maplist addObject:set2];
NSMutableArray * cpList = [[NSMutableArray alloc] init];
NSNumber *component = [[NSNumber alloc] initWithInt:COMPONENT_POI];
[cpList addObject:component];
enum MapDownloadResponse resp = [MapDataMgr downloadMap:maplist
withdisabledComponents:cpList withyear:2016 withquarter:2
withmapdataversion:@”1.1.1.1” withOverwriteExistingMaps:true];
if(response == CP_SUCCESS)
 NSLog(@“Map Downloading”);
else
 NSLog(@”Map could not be downloaded”);

MapDataMgr.downloadMap

Note: 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 true, only one download request can be handled at a time. If the bOverwriteExistingMaps parameter is true, only one download request can be handled at a time.

Syntax

MapDownloadResponse downloadMap(List<MapRegion> mapRegionList, List<MapDataComponent> disabledComponents, boolean bOverwriteExistingMaps)

Parameters

Return Value

Return MapDownloadResponse object contains maps download status.

Sample Code

boolean bOverwriteExistingMaps =true;
ArrayList<MapRegion> mapRegionList = new ArrayList<MapRegion>();
mapRegionList.add(MapRegion.NORTH_AMERICA_Eastern);
mapRegionList.add(MapRegion.NORTH_AMERICA_South);

ArrayList<MapDataComponent> disabledComponentsList = new ArrayList<MapDataComponent>();
disabledComponentsList.add(MapDataComponent.COMPONENT_POI);

MapDownloadResponse response = MapDataMgr.downloadMap(mapRegionList,disabledComponentsList, bOverwriteExistingMaps);

if(response == MapDownloadResponse.SUCCESS)
  System.out.println("Map downloading");
else
  System.out.println("Map could not be downloaded");

NSMutableArray * maplist = [[NSMutableArray alloc] init];
MapRegion *set1 =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_Eastern];
MapRegion *set2 =
[[MapRegion alloc] initWithMapId:NORTH_AMERICA_South];
[maplist addObject:set1];
[maplist addObject:set2];
NSMutableArray * cpList = [[NSMutableArray alloc] init];
NSNumber *component = [[NSNumber alloc] initWithInt:COMPONENT_POI];
[cpList addObject:component];
enum MapDownloadResponse resp = [MapDataMgr downloadMap:maplist
withdisabledComponents:cpList withOverwriteExistingMaps:true];
if(response == CP_SUCCESS)
 NSLog(@"Map Downloading");
else
 NSLog(@"Map could not be downloaded");

MapRegion

Android Values

iOS Properties

MapInfo

Methods

String

String

int

long

long

int

Objective-C Properties

MapRegion

NSString

NSString

int

long

long

int

Example Output

Region: EUROPE Name: Europe Version: GRD_NT.EU.2014.01.2.2.1.2 Year: 2014 Quarter: 2

Sample Code

List<MapInfo> mapList = MapDataMgr.getInstalledMaps();
for(MapInfo dataSet : mapList) {
  MapRegion dataSetRegion = dataSet.getRegion();
  String dataSetName = dataSet.getName();
  String dataSetVersion = dataSet.getVersion();
  int dataSetYear = dataSet.getYear();
  int dataSetQuarter = dataSet.getQuarter();
  System.out.println("Data set info: " + "Region: " + dataSetRegion.toString() + "\\n" + "Name: " + dataSetName + "\\n" + "Version: " + dataSetVersion + "\\n" + "Release: Q" +String.valueOf(dataSetQuarter) + " " + String.valueOf(dataSetYear));
}

MapInfo *dataSet = [[MapDataMgr getInstalledMaps] objectAtIndex:0]
MapRegion *dataSetRegion = dataSet.set;
NSString *dataSetName = dataSet.name;
NSString *dataSetVersion = dataSet.versionString;
int dataSetYear = dataSet.year;
int dataSetQuarter = dataSet.quarter;

MapDownloadResponse

Android Values

iOS Values

MapDataComponent

Values

DownloadStatus

Values

MapDataMgr.setAutomaticUpdateRequest

Syntax

void  setAutomaticUpdateRequest (List<MapRegion> mapRegionList, List<MapDataComponent> disabledComponents)

Parameters

Sample Code

// Add two map regions to automatically download
ArrayList<MapRegion> mapRegionList = new ArrayList<MapRegion>();
mapRegionList.add(MapRegion.NORTH_AMERICA_Eastern);
mapRegionList.add(MapRegion.NORTH_AMERICA_South);
// Add pois as a disabled component
ArrayList<MapDataComponent> disabledComponents = new ArrayList< MapDataComponent >();
disabledComponents .add(MapDataComponent.COMPONENT_POI);

MapDataMgr. setAutomaticUpdateRequest (mapRegionList, disabledComponents );