Method Details

• fromEngineAsync

  public static void fromEngineAsync(@NonNull SDKNativeEngine sdkEngine, @NonNull MapDownloaderConstructionCallback mapDownloaderConstructionCallback)

  Gets a single instance of this class per provided SDKNativeEngine.

  Parameters:

  sdkEngine -

  An instance of the SDKNativeEngine

  mapDownloaderConstructionCallback -

  A callback that will receive the result of construction

• getDownloadableRegions

  @NonNull public TaskHandle getDownloadableRegions(@NonNull DownloadableRegionsCallback callback)

  Performs an asynchronous request to fetch a list of Region objects for downloading map data in a separate request.

  The default language for Region.name is LanguageCode.EN_US.

  Parameters:

  callback -

  Callback which receives the result on the main thread.

  Returns:

  Handle that will be used to manipulate the execution of the task, for example, to cancel on ongoing request.

• getDownloadableRegions

  @NonNull public TaskHandle getDownloadableRegions(@NonNull LanguageCode languageCode, @NonNull DownloadableRegionsCallback callback)

  Performs an asynchronous request to fetch a list of Region objects with Region.name in given languageCode, that can be used to download the actual map data in a separate request.

  Parameters:

  languageCode -

  The language code determines the language of Region.name.

  callback -

  Callback which receives the result on the main thread.

  Returns:

  Handle that will be used to manipulate the execution of the task, for example, to cancel on ongoing request.

• downloadRegions

  @NonNull public MapDownloaderTask downloadRegions(@NonNull List<RegionId> regions, @NonNull DownloadRegionsStatusListener statusListener)

  Performs an asynchronous request to download map data for regions specified by a list of RegionId instances. statusListener receives notifications until DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called. The returned MapDownloaderTask can be used to pause or resume the download using MapDownloaderTask.pause(boolean) or MapDownloaderTask.resume().

  To cancel the request, call MapDownloaderTask.cancel() on the returned MapDownloaderTask object. After cancellation, DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called with the error MapLoaderError.OPERATION_CANCELLED.

  MapDownloaderTask remains operational until DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called.

  To get list of downloadable regions use getDownloadableRegions(LanguageCode, DownloadableRegionsCallback) API.

  Simultaneous downloads of the same region are not supported. If this occurs, DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called with MapLoaderError.SERVICE_ACCESS_FAILED for the new request, while the previous one continues uninterrupted.

  If indexing is enabled through OfflineSearchEngine.setIndexOptions, then after the requested regions have been downloaded, the corresponding index will be created. The index is used by OfflineSearchEngine to find better results. Note: Indexing is a beta feature, so there could be a few bugs and unexpected behaviors.

  To control list of map content features for region download, use LayerConfiguration.enabledFeatures.
  Note: If an application is forcefully closed or crashes during a map download operation, then this method can be called again to resume the download. For example, if a download was interrupted at 60%, then the next call to download the same region will load the remaining 40%.
  Note: If a download fails during runtime, then the HERE SDK will automatically retry to download the affected region three times before giving up. A connection will be timed out after one minute.

  Parameters:

  regions -

  List of regions to download. Can be fetched using getDownloadableRegions(LanguageCode, DownloadableRegionsCallback) API.

  statusListener -

  Notifies on the download progress.

  Returns:

  Handle that will be used to manipulate the execution of the task, for example, to cancel on ongoing request.

• downloadArea

  @NonNull public MapDownloaderTask downloadArea(@NonNull GeoPolygon area, @NonNull DownloadRegionsStatusListener statusListener)

  Performs an asynchronous request to download map data for area specified by a GeoPolygon. statusListener is receiving notifications until DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called. Returned MapDownloaderTask should be used to pause or resume started download, by invoking MapDownloaderTask.pause(boolean) or MapDownloaderTask.resume(). Request can be cancelled by calling MapDownloaderTask.cancel() on returned MapDownloaderTask object, afterwards DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called with error MapLoaderError.OPERATION_CANCELLED.

  MapDownloaderTask remains operational until DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called.

  Downloaded area will be associated to a unique id that will be reported via DownloadRegionsStatusListener.

  Simultaneous download of the same region twice is not supported. When such condition occurs then DownloadRegionsStatusListener.onDownloadRegionsComplete(com.here.sdk.maploader.MapLoaderError, java.util.List<com.here.sdk.maploader.RegionId>) is called with error MapLoaderError.SERVICE_ACCESS_FAILED for a new request, while previous one continues uninterrupted.

  If indexing is enabled through OfflineSearchEngine.setIndexOptions, then after the requested regions have been downloaded, the corresponding index will be created. The index is used by OfflineSearchEngine to find better results. Note: Indexing is a beta feature, so there could be a few bugs and unexpected behaviors.

  To control list of map content features for area download, use LayerConfiguration.enabledFeatures.
  Note: If an application is forcefully closed or crashes during a map download operation, then this method can be called again to resume the download. For example, if a download was interrupted at 60%, then the next call to download the same region will load the remaining 40%.
  Note: If a download fails during runtime, then the HERE SDK will automatically retry to download the affected region three times before giving up. A connection will be timed out after one minute.
  Note: If user try to re-download same GeoPolygon the status will be reported as per the state of previous download operation.

  Parameters:

  area -

  Area to download.

  statusListener -

  Notifies on the download progress.

  Returns:

  Handle that will be used to manipulate the execution of the task, for example, to cancel on ongoing request.

• deleteRegions

  public void deleteRegions(@NonNull List<RegionId> regions, @NonNull DeletedRegionsCallback callback)

  Performs an asynchronous operation to delete map data for regions specified by a list of RegionId. Note: Deleting a region when there is a pending download returns error MapLoaderError.INTERNAL_ERROR. Also, deleting a region when there is an ongoing download returns error MapLoaderError.PARALLEL_REQUEST.

  If indexing is enabled through OfflineSearchEngine.setIndexOptions, then after the requested regions have been deleted, the index over remaining regions will be rebuilt, so that entries related to deleted regions are removed. The index is used by OfflineSearchEngine to find better results. Note: Indexing is a beta feature, so there could be a few bugs and unexpected behaviors.

  Parameters:

  regions -

  List of regions to be deleted.

  callback -

  Callback which receives the result of deletion on the main thread.

• clearPersistentMapStorage

  public void clearPersistentMapStorage(@NonNull SDKCacheCallback callback)

  Performs an asynchronous operation to clear the persistent map storage from all data. All downloaded regions will be removed. Note: Must be called only when no other region operation is ongoing. Returns an error if there is any active operation.

  Any previously built index will also be deleted. See downloadRegions(java.util.List<com.here.sdk.maploader.RegionId>, com.here.sdk.maploader.DownloadRegionsStatusListener) to learn more about index.

  Parameters:

  callback -

  Callback which receives the result of clearing on the main thread.

• getInstalledRegions

  @NonNull public List<InstalledRegion> getInstalledRegions() throws MapLoaderException

  Method to get a list of map regions that are currently installed on the device. Throws if it's not possible to return list of installed regions. Returned list contains:

  • successfully downloaded regions, indicated by InstalledRegionStatus.INSTALLED in InstalledRegion.status;
  • regions, that are in the download process, indicated by InstalledRegionStatus.PENDING in InstalledRegion.status;
  • regions, which were failed to be downloaded, indicated by InstalledRegionStatus.PENDING in InstalledRegion.status. Note: precise Japan content is stored in separate catalog on the HERE platform, and when corresponding region is downloaded, then the status of siblings and parent regions is set to the InstalledRegionStatus.PENDING in InstalledRegion.status. Precise Japan content is available as an additional offering, please contact sales team for more information.

  Returns:

  List of IDs of regions that are installed on the device

  Throws:

  MapLoaderException -

  Specifies reason, why list of installed regions is not returned.

• getInitialPersistentMapStatus

  @NonNull public PersistentMapStatus getInitialPersistentMapStatus()

  Gets the initial status of the already downloaded regions at start-up time of the app. It is not recommended to download or to upload map data while an app is running in background. However, it can happen, that an app gets shut down during an ongoing operation, for example, due to a crash. In such a case, some or all of the downloaded map data may be in a corrupted state. Refer to the PersistentMapStatus for exact healing procedure for specific status. Note: This value will not change during the lifetime of an app.

  Returns:

  Initial status of the persistent map.

• repairPersistentMap

  public void repairPersistentMap(@NonNull RepairPersistentMapCallback callback)

  Tries to repair already downloaded regions that are in a corrupted state (see getInitialPersistentMapStatus()).

  If indexing is enabled through OfflineSearchEngine.setIndexOptions, then index will be rebuilt if existing index does not match with the installed map regions after this operation. The index is used by OfflineSearchEngine to find better results. Note: Indexing is a beta feature, so there could be a few bugs and unexpected behaviors.

  Parameters:

  callback -

  A callback which receives the result of the repair operation on the main thread.

• getOfflineMapsStorageSizeInBytes

  public long getOfflineMapsStorageSizeInBytes() throws MapLoaderException

  Get the total size of all downloaded regions currently persisted on disk at the location that is specified via SDKOptions.persistentMapStoragePath. This includes also data that is currently being downloaded.

  Returns:

  Value of offline map size.

  Throws:

  MapLoaderException -

  Specifies reason, why current map size is not returned.

• getOfflineMapsStorageSizeInBytes

  @NonNull public TaskHandle getOfflineMapsStorageSizeInBytes(@NonNull OfflineStorageSizeCallback callback)

  Get the total size of all downloaded regions currently persisted on disk at the location that is specified via SDKOptions.persistentMapStoragePath. This includes also data that is currently being downloaded.

  Parameters:

  callback -

  A callback which receives the value of offline map size or error on the main thread.

  Returns:

  Handle that will be used to manipulate the execution of the task, for example, to cancel on ongoing request.

• onEnterForeground

  @Deprecated public void onEnterForeground()

  Deprecated.

  Only part of Internal variant. Please use sdk.maploader.BackgroundMapOperationContext.onEnterForeground instead.

  To enable background map downloads for iOS, this method must be invoked when the application moves from the foreground to the background, usually triggered when the user switches to another application or when the device's screen is turned off. Please note that this method is only relevant to the iOS platform. Robust handling of online requests finished while in the background depends on the integration with AppDelegate. How to integrate it see sdk.maploader.BackgroundMapOperationContext.

• getTaskCount

  public long getTaskCount()

  Gets the number of concurrent tasks for downloading a map.

  A valid task count is between 1 to 64. When the value set is outside the valid range, then it is clamped to a valid range:

  • when passed in value is 0 or less, then task count is set to 1;
  • when passed in value is 65 or more, then task count is set to 64.

  Returns:

  The number of concurrent tasks for downloading a map.

• setTaskCount

  public void setTaskCount(long value)

  Sets the number of concurrent tasks for downloading a map.

  A valid task count is between 1 to 64. When the value set is outside the valid range, then it is clamped to a valid range:

  • when passed in value is 0 or less, then task count is set to 1;
  • when passed in value is 65 or more, then task count is set to 64.

  Parameters:

  value -

  The number of concurrent tasks for downloading a map.