Skip to main content

MapDataMgr (CPIK Libraries)

Contents

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

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.
Android Support
>=9.6.8.645
iOS Support
>=10.9
Type
Class
Package
com.alk.cpik.mapdata

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

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.

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

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

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 Android Since Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.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
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 Android Since Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.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
DescriptionCalling 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 Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
setMapRegion to query for update.
yearThe specific map set year to check for update.
quarterThe 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
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 Android Since Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
setThe 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

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 Android Since Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
setObject 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
DescriptionResumes a paused download of a specific MapRegion.
Supported on Android Since Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
setObject 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

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 Android Since Version9.6.8.645
Supported on iOS Since VersionAndroid, Linux
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
setObject 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
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 Android Since Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
setObject 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
DescriptionThis 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, List, 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 Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
mapRegionListList of map regions to download.
disabledComponentsList of components to disable. These components will not be downloaded with the map data.
yearThe 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 mapRegionList, List disabledComponents, boolean bOverwriteExistingMaps) to obtain the most recent maps.
quarterThe 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 mapRegionList, List disabledComponents, boolean bOverwriteExistingMaps) to obtain the most recent maps.
mapDataVersionStringA 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.
bOverwriteExistingMapsWhether 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
DescriptionThis 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 Version9.6.8.645
Supported on iOS Since Version10.9
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
mapRegionListList of map regions to download.
disabledComponentsList of components to disable. These components will not be downloaded with the map data.
bOverwriteExistingMapsWhether 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
DescriptionThis 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 Version9.6.8.645
Supported on iOS Since Version10.9
TypeEnum
Packagecom.alk.cpik

Android Values

Values
Error
AFRICA_Southern_Africa
ASIA_Southeast_Asia
ASIA_India
AUSTRALASIA_Australasia
AUSTRALASIA_Australia
AUSTRALASIA_New_Zealand
CENTRAL_AND_SOUTH_AMERICA_Brazil
EUROPE_Europe
EUROPE_Eastern_Europe
EUROPE_Western_Europe
EUROPE_UK_and_Ireland
EUROPE_Balkans
EUROPE_BeNeLux
EUROPE_Central_Eastern_Europe
EUROPE_DACH
EUROPE_France
EUROPE_Greece
EUROPE_Iberia
EUROPE_Italy
EUROPE_Nordics
EUROPE_Poland
EUROPE_Romania
EUROPE_Russia
EUROPE_Turkey
EUROPE_Ukraine
MIDDLE_EAST_Middle_East
NORTH_AMERICA_North_America
NORTH_AMERICA_United_States
NORTH_AMERICA_Canada
NORTH_AMERICA_Eastern
NORTH_AMERICA_South
NORTH_AMERICA_Midwest
NORTH_AMERICA_Plains_and_Rockies
NORTH_AMERICA_Southwest
NORTH_AMERICA_Northwest
NORTH_AMERICA_Alaska
NORTH_AMERICA_Hawaii
NORTH_AMERICA_New_Jersey
NORTH_AMERICA_Puerto_Rico
NORTH_AMERICA_California
NORTH_AMERICA_Alabama
NORTH_AMERICA_Arizona
NORTH_AMERICA_Arkansas
NORTH_AMERICA_Colorado
NORTH_AMERICA_Connecticut
NORTH_AMERICA_Delaware
NORTH_AMERICA_District_of_Columbia
NORTH_AMERICA_Florida
NORTH_AMERICA_Georgia
NORTH_AMERICA_Idaho
NORTH_AMERICA_Illinois
NORTH_AMERICA_Indiana
NORTH_AMERICA_Iowa
NORTH_AMERICA_Kansas
NORTH_AMERICA_Kentucky
NORTH_AMERICA_Louisiana
NORTH_AMERICA_Maine
NORTH_AMERICA_Maryland
NORTH_AMERICA_Massachusetts
NORTH_AMERICA_Michigan
NORTH_AMERICA_Minnesota
NORTH_AMERICA_Mississippi
NORTH_AMERICA_Missouri
NORTH_AMERICA_Montana
NORTH_AMERICA_Nebraska
NORTH_AMERICA_Nevada
NORTH_AMERICA_New_Hampshire
NORTH_AMERICA_New_Mexico
NORTH_AMERICA_New_York
NORTH_AMERICA_North_Carolina
NORTH_AMERICA_North_Dakota
NORTH_AMERICA_Ohio
NORTH_AMERICA_Oklahoma
NORTH_AMERICA_Oregon
NORTH_AMERICA_Pennsylvania
NORTH_AMERICA_Rhode_Island
NORTH_AMERICA_South_Carolina
NORTH_AMERICA_South_Dakota
NORTH_AMERICA_Tennessee
NORTH_AMERICA_Texas
NORTH_AMERICA_Utah
NORTH_AMERICA_Vermont
NORTH_AMERICA_Virginia
NORTH_AMERICA_Washington
NORTH_AMERICA_West_Virginia
NORTH_AMERICA_Wisconsin
NORTH_AMERICA_Wyoming
NORTH_AMERICA_Alberta
NORTH_AMERICA_British_Columbia
NORTH_AMERICA_Manitoba
NORTH_AMERICA_New_Brunswick
NORTH_AMERICA_Newfoundland_and_Labrador
NORTH_AMERICA_Northwest_Territories
NORTH_AMERICA_Nova_Scotia
NORTH_AMERICA_Nunavut
NORTH_AMERICA_Ontario
NORTH_AMERICA_Prince_Edward_Island
NORTH_AMERICA_Quebec
NORTH_AMERICA_Saskatchewan
NORTH_AMERICA_Yukon
NORTH_AMERICA_US_Virgin_Islands

iOS Properties

PropertyType
DescriptionsNSString
mapidEnum CPMapIDs

MapInfo

Overview
DescriptionThis 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 Version9.6.8.645
Supported on iOS Since Version10.9
TypeObject
Packagecom.alk.cpik

Methods

Method NameReturn TypeDescription
getRegion()MapRegionReturns 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

PropertyTypeDescription
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
DescriptionThis 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 Version9.6.8.645
Supported on iOS Since Version10.9
TypeEnum
Packagecom.alk.cpik

Android Values

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.

iOS Values

ValueDescription
CP_SUCCESSThe map download was successful.
CP_FAILURE_PREPROCESSINGDialed to retrieve URL, inputs were invalid, the connection was invalid or the manager is handling an operation. Check log for details
CP_FAILURE_VALIDATIONFailed to validate request. This flag gets expanded on the codes below.
CP_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.
CP_FAILURE_INSTALLEDFailed, already installed.
CP_FAILURE_DOWNLOADINGFailed, already downloading.
CP_FAILURE_DOWNLOADED Failed, already downloaded.
CP_FAILURE_PAUSEDFailed download paused.
CP_FAILURE_CANCELLEDFailed, download canceled.
CP_FAILURE_UNLICENSEDFailed, not licensed for the requested map.
CP_FAILURE_ENQUEUEFailed to add download to the download queue.
CP_FAILED_GENERIC_ERRORFailed, no specific error available.

MapDataComponent

Overview
DescriptionThis 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 Version9.6.8.645
Supported on iOS Since VersionAndroid, Linux
TypeEnum
Packagecom.alk.cpik.mapdata

Values

ValueDescription
COMPONENT_POIIndicates POI component in map data.
COMPONENT_TRAFFICIndicates TRAFFIC component in map data.
COMPONENT_SPEEDLIMITIndicates SPEEDLIMIT component in map data.

DownloadStatus

Overview
DescriptionAn 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 Version9.6.8.645
TypeEnum
Packagecom.alk.cpik.mapdata

Values

ValueDescription
STATUS_UNKNOWNIndicates map download status is unknown.
DOWNLOADINGIndicates the map is currently downloading.
SUCCEEDEDIndicates map download succeeded.
CANCELLEDIndicates map download has been cancelled.
FAILEDIndicates map download failed.
PAUSEDIndicates map download is currently paused.
NOT_INITIATEDIndicates map download wasn’t started yet.

MapDataMgr.setAutomaticUpdateRequest

Overview
DescriptionThis 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 Version10.9.0.530
TypeMethod
Packagecom.alk.cpik.mapdata

Syntax

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

Parameters

ParameterDescription
mapRegionListList of map regions to download automatically.
disabledComponentsList 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
DescriptionThis 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 Version10.9
Supported on iOS Since Version10.9
TypeMethod
Packagecom.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

ValueDescription
0Last Stop
1Current location
2 (default)Choose Stop
3Pick 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

ValueDescription
TrueWill display the map feedback UI flow in CoPilot
FalseSubmit 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

ValueDescription
TrueReturn the picked feedback location to the calling application and stay on the map location pickup view
FalseProceed 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:

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

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

ParameterDescription
StringA 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
DescriptionThe 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 Version10.9
Supported on iOS Since Version10.9
TypeMethod
Packagecom.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
DescriptionThe 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 Version10.9
Supported on iOS Since Version10.9
TypeMethod
Packagecom.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
DescriptionThis enum is the return value of MapDataMgr.sendMapFeedback(String) with the result of the API call.
Supported on Android Since Version10.9
Supported on iOS Since Version10.9
TypeEnum
Packagecom.alk.cpik.mapdata

Values

ValueDescription
SUCCESSSuccessful in sending the request to CoPilot
FAILURE_JSON_PARSEJSON parsing failed - Please make sure a valid json object is being passed
FAILURE_INVALID_POI_JSONJSON has missing/incomplete fields required for map feedback
FAILURE_STOPINFO_NOT_PROVIDEDStop Type required feedback location but missing in JSON
FAILURE_GENERIC_ERRORUnknown Error

MapFeedbackClearStatus

Overview
DescriptionThis Enum is the return value of MapDataMgr.clearMapFeedback with the result of the API call.
Supported on Android Since Version10.9
Supported on iOS Since Version10.9
TypeEnum
Packagecom.alk.cpik.mapdata

Values

ValueDescription
SUCCESSSuccessfully delete all cached map feedback
FAILUREFailed to delete cached map feedback
Last updated October 31, 2022.