Skip to content

MapDataMgr

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 Enum MapRegion.
Supported on Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Class
Package com.alk.cpik.mapdata

Methods

Method Name Return Type Description
getInstalledMaps() List 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, int year, int quarter) MapInfo A check performed to see if there is a download available for a specific map data set, year, and quarter.
checkMapUpdate(MapRegion set) MapInfo Checks if there is a download available for a specific map region.
downloadMap(List mapRegionList, List 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
downloadMap(List mapRegionList, List disabledComponents, boolean bOverwriteExistingMaps) MapDownloadResponse This API will allow users to download a map set based on a specified list of map regions and a list of 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 MapExact Override sync. 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 Use Case

This section outlines a use case of CPIK 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 WiFi 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.

Note

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

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 Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

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

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 Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

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.

Overview
Description Calling this method performs a check to see if there is a download available for a specific map data set, year, and quarter. If the specified data set is available, a MapInfo object containing the details is returned. If the data is not available, null will be returned.

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 Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

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

Parameters

Parameter Description
set MapRegion to query for update.
year The specific map set year to check for update.
quarter The specific map set quarter to check for update.

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 = 2015;// Year 2015
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:2015, 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.

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 Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

MapInfo checkMapUpdate (MapRegion set)
(MapInfo*) checkMapUpdate:(MapRegion *)set

Parameters

Parameter Description
set The object of MapRegion to query for update.

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

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 Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

MapDownloadResponse pauseMapDownload (MapRegion set)
(enum MapDownloadResponse)pauseMapDownload:(MapRegion *)set

Parameters

Parameter Description
set Object ofMapRegion to pause.

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

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 Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

MapDownloadResponse resumeMapDownload (MapRegion set)
(enum MapDownloadResponse)resumeMapDownload:(MapRegion *)set

Parameters

Parameter Description
set Object of MapRegion

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

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 Android Since Version 9.6.8.645
Supported on iOS Since Version Android, Linux
Type Method
Package com.alk.cpik.mapdata

Syntax

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

Parameters

Parameter Description
set Object of MapRegion

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.

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 Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

MapDownloadResponse deleteMap (MapRegion set)
(enum MapDownloadResponse) deleteMap:(MapRegion *)set

Parameters

Parameter Description
set Object of MapRegion

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:2015 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.

Overview
Description This API downloads a map set based on a list of MapRegions, list of components to disable, year, quarter, version string, and whether or not data should be overwritten. 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 should only be used when a specific year, quarter, or version string is required. Otherwise, use MapDataMgr.downloadMap(List<​MapRegion>, List<​MapDataComponent>, boolean) to obtain the latest map data.

The version string should only be used when a specific version of a map data release is required. To download the latest version of a map set from a specific year and quarter, the version string is not required.

Supported on Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

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

Parameters

Parameter Description
mapRegionList List of map regions to download.
disabledComponents List of components to disable. These components will not be downloaded with the map data.
year The year of the map to download. If this parameter is provided, the quarter must also be provided. If you do not want to specify the year, please use the API call MapDataMgr.downloadMap(List<​MapRegion> mapRegionList, List<​MapDataComponent> disabledComponents, boolean bOverwriteExistingMaps) to obtain the most recent maps.
quarter The quarter of the map to download. If this parameter is provided, the year must also be provided. If you do not want to specify the quarter, please use the API call MapDataMgr.downloadMap(List<​MapRegion> mapRegionList, List<​MapDataComponent> disabledComponents, boolean bOverwriteExistingMaps) to obtain the most recent maps.
mapDataVersionString A specific grid version string to download. If this parameter is provided, year and quarter must also be provided. Data version will be four numbers each separated by a decimal point, e.g 1.7.1.1.
bOverwriteExistingMaps Whether to download the new maps in addition to the existing maps or to replace the existing maps with the new maps.

Return Value

Return MapDownloadResponse object contains map download status

Sample Code

int mYear = 2015;// Year 2015
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.

Overview
Description This API downloads a map set based on a list of MapRegions, list of components to disable, and whether or not data should be overwritten. 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. When this API is used, the most recent available map data will be downloaded.
Supported on Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

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

Parameters

Parameter Description
mapRegionList List of map regions to download.
disabledComponents List of components to disable. These components will not be downloaded with the map data.
bOverwriteExistingMaps Whether to download the new maps in addition to the existing maps or to replace the existing maps with the new maps.

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

Overview
Description This is an enum that corresponds to a particular map data region. Once this information has been requested, the result can be used to identify a map data region.
Supported on Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik

Android Values

Value Description
Error Returns error for any MapRegion error.
AFRICA_Southern_Africa Returns MapRegion for Southern Africa.
ASIA_Southeast_Asia Returns MapRegion for South East Asia.
ASIA_India Returns MapRegion for India.
AUSTRALASIA_Australasia Returns MapRegion for Australasia.
AUSTRALASIA_Australia Returns MapRegion for Australia.
AUSTRALASIA_New_Zealand Returns MapRegion for New Zealand.
CENTRAL_AND_SOUTH_AMERICA_Brazil Returns MapRegion for Brazil.
EUROPE_Europe Returns MapRegion for Europe.
EUROPE_Eastern_Europe Returns MapRegion for Eastern Europe.
EUROPE_Western_Europe Returns MapRegion for Western Europe
EUROPE_UK_and_Ireland Returns MapRegion for UK and Ireland.
EUROPE_Balkans Returns MapRegion for Balkans.
EUROPE_BeNeLux Returns MapRegion for Belgium Netherlands and Luxembourg.
EUROPE_Central_Eastern_Europe Returns MapRegion for Central Eastern Europe.
EUROPE_DACH Returns MapRegion for Germany, Austria, Switzerland and Liechtenstein.
EUROPE_France Returns MapRegion for France.
EUROPE_Greece Returns MapRegion for Greece.
EUROPE_Iberia Returns MapRegion for Iberia.
EUROPE_Italy Returns MapRegion for Italy.
EUROPE_Nordics Returns MapRegion for Nordics.
EUROPE_Poland Returns MapRegion for Poland.
EUROPE_Romania Returns MapRegion for Romania.
EUROPE_Russia Returns MapRegion for Russia.
EUROPE_Turkey Returns MapRegion for Turkey.
EUROPE_Ukraine Returns MapRegion for Ukraine.
MIDDLE_EAST_Middle_East Returns MapRegion for Middle East.
NORTH_AMERICA_North_America Returns MapRegion for North America.
NORTH_AMERICA_United_States Returns MapRegion for United States.
NORTH_AMERICA_Canada Returns MapRegion for Canada.
NORTH_AMERICA_Eastern Returns MapRegion for Eastern.
NORTH_AMERICA_South Returns MapRegion for South.
NORTH_AMERICA_Midwest Returns MapRegion for Midwest.
NORTH_AMERICA_Plains_and_Rockies Returns MapRegion for Plains And Rockies.
NORTH_AMERICA_Southwest Returns MapRegion for South West.
NORTH_AMERICA_Northwest Returns MapRegion for North West.
NORTH_AMERICA_Alaska Returns MapRegion for Alaska.
NORTH_AMERICA_Hawaii Returns MapRegion for Hawaii.
NORTH_AMERICA_Puerto_Rico Returns MapRegion for Puerto Rico.

iOS Properties

Property Type
Descriptions NSString
mapid Enum CPMapIDs

MapInfo

Overview
Description This is an object that contains information about a particular set of map data. This includes the region, name, version, year and quarter that is currently downloaded and in use on a device.
Supported Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Object
Package com.alk.cpik

Methods

Method Name Return Type Description
getRegion() MapRegion Returns the MapRegion
getName() String Returns the name
getVersion() String Returns the version
getYear() int Returns the year
getMapFileSize() long Returns the map file size in bytes
getDownloadedCount() long Returns download count
getQuarter() int Returns quarter

Objective-C Properties

Property Type Description
set MapRegion Returns the MapRegion
name NSString Returns the name
versionString NSString Returns the version
year int Returns the year
fileSize long Returns the map file size in bytes
downloadedSize long Returns download count
quarter int Returns quarter

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

Overview
Description This is a response enum from a request to download, pause, cancel, or delete a map. Responses provide information about the request’s result including specific reasons if it fails.
Supported on Android Since Version 9.6.8.645
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik

Android Values

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.

iOS Values

Value Description
CP_SUCCESS The map download was successful.
CP_FAILURE_PREPROCESSING Dialed to retrieve URL, inputs were invalid, the connection was invalid or the manager is handling an operation. Check log for details
CP_FAILURE_VALIDATION Failed to validate request. This flag gets expanded on the codes below.
CP_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.
CP_FAILURE_INSTALLED Failed, already installed.
CP_FAILURE_DOWNLOADING Failed, already downloading.
CP_FAILURE_DOWNLOADED Failed, already downloaded.
CP_FAILURE_PAUSED Failed download paused.
CP_FAILURE_CANCELLED Failed, download canceled.
CP_FAILURE_UNLICENSED Failed, not licensed for the requested map.
CP_FAILURE_ENQUEUE Failed to add download to the download queue.
CP_FAILED_GENERIC_ERROR Failed, no specific error available.

MapDataComponent

Overview
Description This is an enum that represents a component for a set of map data to optionally disable features such as POIs, Traffic, and SpeedLimit.
Supported on Android Since Version 9.6.8.645
Supported on iOS Since Version Android, Linux
Type Enum
Package com.alk.cpik.mapdata

Values

Value Description
COMPONENT_POI Indicates POI component in map data.
COMPONENT_TRAFFIC Indicates TRAFFIC component in map data.
COMPONENT_SPEEDLIMIT Indicates SPEEDLIMIT component in map data.

DownloadStatus

Overview
Description An enum that represents the status of a current download. This can be used to identify the status at any stage through the download map status process.
Supported on Android Since Version 9.6.8.645
Type Enum
Package com.alk.cpik.mapdata

Values

Value Description
STATUS_UNKNOWN Indicates map download status is unknown.
DOWNLOADING Indicates the map is currently downloading.
SUCCEEDED Indicates map download succeeded.
CANCELLED Indicates map download has been cancelled.
FAILED Indicates map download failed.
PAUSED Indicates map download is currently paused.
NOT_INITIATED Indicates map download wasn't started yet.

MapDataMgr.setAutomaticUpdateRequest

Overview
Description This API will enable automatic map updates for defined map sets.
Within this APIs additional map data components should also be defined.
Supported on Android Since Version 10.9.0.530
Type Method
Package com.alk.cpik.mapdata

Syntax

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

Parameters

Parameter Description
mapRegionList List of map regions to download automatically.
disabledComponents List of components to disable. These components will not be downloaded with the map data.

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

MapDataMgr.sendMapFeedback

Overview
Description This API facilitates the sending of map feedback to Trimble MAPS via a json string. The format and an example can be found below.
This JSON will call the API to send to the MapSure web service. The json string above includes all fields. Required fields are dependent on the combination passed to CoPilot.

This API is only applicable for users with North American data present on the device

Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik

JSON Format

{
  "coPilotVersion": "10.9.0.5",
  "dataVersion": "GRD_ALK.NA-base-4.2017.02.13.11.1.3",
  "description": "",
  "heading": 0,
  "speed": 0,
  "timeStamp": 1504724835,
  "issueType": 1,
  "feedbackLocation": {
    "Address": {
      "StreetAddress": "124 North Nassau Street  (NJ-27)",
      "City": "Princeton",
      "State": "NJ",
      "Zip": "08542",
      "County": "Mercer",
      "Country": ""
    },
    "Coords": {
      "Lat": "40.350010",
      "Lon": "-74.658530"
    }
  },
  "customFields": {
    "StopType": 1,
    "showUI": true
  }
}

Information on further information can be found below.

StopType: Integer

Value Description
0 Last Stop
1 Current location
2 (default) Choose Stop
3 Pick point on the map

For value 2, you have to provide a feedback stop, otherwise FAILURE_STOPINFO_NOT_PROVIDED error will be provided.

showUI: boolean

Value Description
True Will display the map feedback UI flow in CoPilot
False Submit the map feedback json without UI flow

If timeStamp is included and the report is submitted through the UI flow, the timeStamp will be overwritten when submitted through the UI. The timeStamp will not be overwritten if showUI is set to false.

If showUI is set to be true, issueType is provided and so is a description, we will ignore these two fields as the issue type has been selected and/or description in the map feedback CoPilot UI flow.

If your StopType is PICK_ON_MAP but you set showUI to be false, you will end up getting FAILURE_INVALID_POI_JSON. So be careful about the combination of those options.

ReturnMapPickUp: boolean

Value Description
True Return the picked feedback location to the calling application and stay on the map location pickup view
False Proceed CoPilot feedback UI flow after picking up the location

The picked location will be returned from the callback onMapLocationPicked(Stop stop). This callback is under MapDataListener.

issueType:

Value Description
0 Missing Address
1 Address Location Error
2 Height Restriction
3 Weight Restriction
4 Truck Restriction
5 Hazmat Restriction
6 Missing Street
7 Exit Sign Post Correction
8 One Way Street Error
9 Speed Limit Error
10 Road Closure
11 Turn Restriction
12 Road Name Error
13 Other

The API will either send the feedback to the MapSure web service or cache it in local device. The decision is made by the following config:

[Mapsure]
"SendMapFeedbackOTA"=1

Setting the config to true (=1) will result in the API will sending the feedback to web service and not caching it on device. MapDataMgr.getMapFeedback() API should be used when set to =0 to send the information back to Trimble MAPS. This can be used at certain times when you want to send the information to CoPilot.

Syntax

 static MapFeedbackSendStatus sendMapFeedback(String feedbackJSON)
+(enum MapFeedbackSendStatus) sendMapFeedback:(NSString*)feedbackJSON

Parameters

Parameter Description
String A string in json format which has all the map feedback information that user wants to report.

Return Values MapFeedbackSendStatus

Sample Code

String feedbackJSON = "your map feedback json";
MapDataMgr.sendMapFeedback(feedbackJSON);
NSString *feedbackJSON = @"your map feedback json";
[MapDataMgr sendMapFeedback:feedbackJSON];

MapDataMgr.getMapFeedback

Overview
Description The API returns all cached map feedback in json string. If no map feedback is cached on device, the API will return an json string which contains an empty array object.
Note: to send feedback to Trimble MAPS,the API will either send the feedback to our MapSure web service or cache it in local device. The decision is made by the following config:

[Mapsure]
"SendMapFeedbackOTA"=1

Set the config to true means the API will send the feedback to web service and not caching it on device. MapDataMgr.getMapFeedback() API should be used when set to =0 to send the information back to Trimble MAPS. This can be used at certain times when you want to send the information to CoPilot.

Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

static String getMapFeedback()
+(NSString*) getMapFeedback

Return Values String

Sample Code

String feedbackJSONs = MapDataMgr.getMapFeedback();
NSString *feedbackJSON = [MapDataMgr getMapFeedback];

MapDataMgr.clearMapFeedback

Overview
Description The API will clear all cached map feedback on device. After calling this API, MapDataMgr.getMapFeedback should return a json that contains empty feedback object.
Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Method
Package com.alk.cpik.mapdata

Syntax

 static MapFeedbackClearStatus clearMapFeedback()
+(enum MapFeedbackClearStatus ) clearMapFeedback

Return Values MapFeedbackClearStatus

Sample Code

MapFeedbackClearStatus res = MapDataMgr.clearMapFeedback();
enum MapFeedbackClearStatus res = [MapDataMgr clearMapFeedback];

MapFeedbackSendStatus

Overview
Description This enum is the return value of MapDataMgr.sendMapFeedback(String) with the result of the API call.
Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.mapdata

Values

Value Description
SUCCESS Successful in sending the request to CoPilot
FAILURE_JSON_PARSE JSON parsing failed - Please make sure a valid json object is being passed
FAILURE_INVALID_POI_JSON JSON has missing/incomplete fields required for map feedback
FAILURE_STOPINFO_NOT_PROVIDED Stop Type required feedback location but missing in JSON
FAILURE_GENERIC_ERROR Unknown Error

MapFeedbackClearStatus

Overview
Description This Enum is the return value of MapDataMgr.clearMapFeedback with the result of the API call.
Supported on Android Since Version 10.9
Supported on iOS Since Version 10.9
Type Enum
Package com.alk.cpik.mapdata

Values

Value Description
SUCCESS Successfully delete all cached map feedback
FAILURE Failed to delete cached map feedback

Last update: June 8, 2020