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
Class
com.alk.cpik.mapdata
Methods
Method Name | Return Type | Description | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
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
| 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 |
| 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.
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.
-
bOverwriteExistingMaps set to true:
-
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.
-
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.
-
-
bOverwriteExistingMaps set to false:
-
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.
-
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
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
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 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(Listquarter | 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 | 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
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
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:
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 |