MapDownloader

public class MapDownloader
extension MapDownloader: NativeBase
extension MapDownloader: Hashable

A class for downloading and managing map data for various regions worldwide. Downloaded map data is permanently stored on disk, enabling maps at all zoom levels, search, routing, and other features without an active data connection. Users can query available regions, download them to disk, or delete them. An instance of this class can be created using MapDownloader.fromEngineAsync(...).

The storage path for downloaded maps can be specified via SDKOptions.persistentMapStoragePath.

To control the type of content included in a map download, use LayerConfiguration. Once applied, it affects both the map cache and offline maps. Satellite-based map schemes are not included in the downloaded region data.

Note: During turn-by-turn navigation, while a map download or update is in progress, navigation may not function as expected, and the app may be blocked until the operation is completed. Ensure that all pending map operations are finished before starting navigation. This applies only to MapDownloader and MapUpdater. RoutePrefetcher operations are not affected.

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

    Declaration

    Swift

    public var taskCount: UInt32 { get set }

  • Gets a single instance of this class per provided SDKNativeEngine.

    Declaration

    Swift

    public static func fromEngineAsync(_ sdkEngine: SDKNativeEngine, _ mapDownloaderConstructionCallback: @escaping MapDownloaderConstructionHandle)

    Parameters

    sdkEngine

    An instance of the SDKNativeEngine
    mapDownloaderConstructionCallback

    A callback that will receive the result of construction

  • 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.enUs.

    Declaration

    Swift

    @discardableResult
public func getDownloadableRegions(completion: @escaping CompletionHandler) -> TaskHandle

    Parameters

    completion

    Callback which receives the result on the main thread.

    Return Value

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

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

    Declaration

    Swift

    @discardableResult
public func getDownloadableRegions(languageCode: LanguageCode, completion: @escaping CompletionHandler) -> TaskHandle

    Parameters

    languageCode

    The language code determines the language of Region.name.
    completion

    Callback which receives the result on the main thread.

    Return Value

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

  • Performs an asynchronous request to download map data for regions specified by a list of RegionId instances. MapDownloader.downloadRegions(...).statusListener receives notifications until onDownloadRegionsComplete(...) is called. The returned MapDownloaderTask can be used to pause or resume the download using MapDownloaderTask.pause(Bool) or MapDownloaderTask.resume(...).

    To cancel the request, call MapDownloaderTask.cancel(...) on the returned MapDownloaderTask object. After cancellation, onDownloadRegionsComplete(...) is called with the error MapLoaderError.operationCancelled.

    MapDownloaderTask remains operational until onDownloadRegionsComplete(...) is called.

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

    Simultaneous downloads of the same region are not supported. If this occurs, onDownloadRegionsComplete(...) is called with MapLoaderError.serviceAccessFailed 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.

    Declaration

    Swift

    @discardableResult
public func downloadRegions(regions: [RegionId], statusListener: DownloadRegionsStatusListener) -> MapDownloaderTask

    Return Value

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

  • Performs an asynchronous request to download map data for area specified by a GeoPolygon. MapDownloader.downloadArea(...).statusListener is receiving notifications until onDownloadRegionsComplete(...) is called. Returned MapDownloaderTask should be used to pause or resume started download, by invoking MapDownloaderTask.pause(Bool) or MapDownloaderTask.resume(...). Request can be cancelled by calling MapDownloaderTask.cancel(...) on returned MapDownloaderTask object, afterwards onDownloadRegionsComplete(...) is called with error MapLoaderError.operationCancelled.

    MapDownloaderTask remains operational until onDownloadRegionsComplete(...) 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 onDownloadRegionsComplete(...) is called with error MapLoaderError.serviceAccessFailed 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.

    Declaration

    Swift

    public func downloadArea(area: GeoPolygon, statusListener: DownloadRegionsStatusListener) -> MapDownloaderTask

    Return Value

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

  • 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.internalError. Also, deleting a region when there is an ongoing download returns error MapLoaderError.parallelRequest.

    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.

    Declaration

    Swift

    public func deleteRegions(regions: [RegionId], completion: @escaping DeleteRegionsCompletionHandler)

    Parameters

    regions

    List of regions to be deleted.
    completion

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

  • 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 MapDownloader.downloadRegions(...) to learn more about index.

    Declaration

    Swift

    public func clearPersistentMapStorage(completion: @escaping CacheCallbackCompletionHandler)

    Parameters

    completion

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

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

    Throws

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

    Declaration

    Swift

    public func getInstalledRegions() throws -> [InstalledRegion]

    Return Value

    List of IDs of regions that are installed on the device

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

    Declaration

    Swift

    public func getInitialPersistentMapStatus() -> PersistentMapStatus

    Return Value

    Initial status of the persistent map.

  • Tries to repair already downloaded regions that are in a corrupted state (see MapDownloader.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.

    Declaration

    Swift

    public func repairPersistentMap(completion: @escaping RepairCompletionHandler)

    Parameters

    completion

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

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

    Throws

    MapLoaderException Specifies reason, why current map size is not returned.

    Declaration

    Swift

    public func getOfflineMapsStorageSizeInBytes() throws -> UInt64

    Return Value

    Value of offline map size.

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

    Declaration

    Swift

    public func getOfflineMapsStorageSizeInBytes(completion: @escaping OfflineStorageSizeHandler) -> TaskHandle

    Parameters

    completion

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

    Return Value

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