MapUpdater

public class MapUpdater
extension MapUpdater: NativeBase
extension MapUpdater: Hashable

A class for updating regions previously downloaded using the MapDownloader. First, updates for the regions are downloaded. Once the download is complete, the update process begins, installing the new content. It is recommended to regularly call MapUpdater.retrieveCatalogsUpdateInfo(...) to check for available updates for any downloaded regions.

If updates are available, regions can be updated asynchronously using MapUpdater.updateCatalog(...). The MapUpdateProgressListener provides update progress for each region.

Incremental map updates are supported, by default: Instead of downloading an entire region, only the parts that have changed will be installed. This results in a faster update process. MapUpdater also aligns previously downloaded content with LayerConfiguration changes made via SDKOptions.

Note that patching (also called “incremental updates”) is only supported for up to 8 versions. For example, if an update started with version x.y.0 then it will be supported till x.y.8 and stopped starting with x.y.9. Usually, OCM updates are released weekly. Incremental updates will stop after 2 months and a full update is performed instead.

In case of an error, the previous map data remains available for use. It is only replaced after new map data has been successfully downloaded. Regions that fail to update must be retried in a new call. Paused updates can be resumed later.

During the update process, MapUpdater internally retries failed downloads until a timeout occurs. If this happens, it is reported via MapUpdateProgressListener.

If the user cancels the update process during the update phase, it is ignored. The update phase begins after all content has been downloaded, then the HERE SDK installs and replaces the existing regions. Cancellation is only possible during the download phase, and a successful cancellation is indicated via onComplete(...).

Note that a MapLoaderError.notReady occurs when the MapDownloader is used in parallel. In general, background updates are not supported explicitly, as the OS can abort background processes. In addition, the OfflineSearchEngine and the OfflineRoutingEngine cannot be used while a map update is in progress and it will be indicated by a MapLoaderError.

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

  • Map update statistics for the current application session. In the event of binary updates, patches are downloaded and applied. This property helps to determine the success or failure rate of applied patches.

    Declaration

    Swift

    public var updateStatistics: UpdateStatistics { get }

  • Defines if installed regions and subregions are updated one-by-one or if all regions are updated only once the updates for all installed regions have been downloaded entirely. This influences the required size of the storage during an update. Regardless of the set policy, during an update, the previous region data is kept until the new region data is committed successfully to the persisted storage. This allows to revert to the previous version in case the update fails. With MapUpdater.MapUpdateVersionCommitPolicy.onComplete, more data has to be kept until the update process finishes, while MapUpdater.MapUpdateVersionCommitPolicy.onFirstRegion allows to make faster use of the downloaded region and requires less disk space as only the currently updated region is kept until the process completes. However, with an MapUpdater.MapUpdateVersionCommitPolicy.onFirstRegion policy the overall process can be less reliable and bears a higher risk of errors.

    See more

    Declaration

    Swift

    public enum MapUpdateVersionCommitPolicy : UInt32, CaseIterable, Codable

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

    Declaration

    Swift

    public static func fromEngineAsync(_ sdkEngine: SDKNativeEngine, _ mapUpdaterConstructionCallback: @escaping MapUpdaterConstructionHandler)

    Parameters

    sdkEngine

    An instance of the SDKNativeEngine
    mapUpdaterConstructionCallback

    A callback that will receive the result of construction

  • Returns a handle that contains the map version of the already downloaded and installed regions. This information is only needed for debugging purposes.

    Throws

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

    Declaration

    Swift

    public func getCurrentMapVersion() throws -> MapVersionHandle

    Return Value

    A handle to get the map version.

  • Performs an asynchronous request for each catalog to update map data to the latest available version. This applies to all previously installed Region map data and any incomplete downloads in a pending state.

    If no regions are downloaded, this method updates only the map version. The map cache and persisted regions are always bound to the same map version.

    If no updates are available, CatalogsUpdateInfoCallback from MapUpdater.retrieveCatalogsUpdateInfo(...) returns an empty list. In this case, onComplete(...) is called immediately.

    To check for available updates, use MapUpdater.retrieveCatalogsUpdateInfo(...) to retrieve catalogs with newer versions. Individual catalogs can then be updated using this method. Ensure that the device has enough free disk space to perform a catalog update. Information about the required disk space is available in CatalogUpdateInfo.diskSizeInBytes.

    If there is not enough space to perform the catalog update with the default MapUpdater.MapUpdateVersionCommitPolicy.onComplete, try using MapUpdater.MapUpdateVersionCommitPolicy.onFirstRegion. This option requires less space but follows a different strategy for handling errors during the map update.

    If indexing is enabled through OfflineSearchEngine.setIndexOptions, the index is rebuilt after the map is updated. The index helps OfflineSearchEngine provide better search results.

    Note: Indexing is a beta feature and may have bugs or unexpected behavior.

    Declaration

    Swift

    public func updateCatalog(catalogInfo: CatalogUpdateInfo, completion: CatalogUpdateProgressListener) -> CatalogUpdateTask

    Parameters

    catalogInfo

    catalog to update. CatalogUpdateInfo should be get from MapUpdater.retrieveCatalogsUpdateInfo(...)
    completion

    Callback which receives the result on the main thread.

    Return Value

    A handle that will be used to manipulate the execution of the task, for example, to cancel an ongoing request.

  • Retrieves information of all catalogs that have newer version available. This method can also be used to query catalog information like HRN, current installed version and newer available version on server. An empty list in CatalogsUpdateInfoCallback represent no map updates.

    Declaration

    Swift

    public func retrieveCatalogsUpdateInfo(callback: @escaping CatalogsUpdateInfoCallback) -> TaskHandle

    Parameters

    callback

    Callback which receives the result on the main thread.

    Return Value

    A handle to cancel a pending operation.

  • Sets the map update version policy. Defaults to MapUpdater.MapUpdateVersionCommitPolicy.onComplete.

    Declaration

    Swift

    public func setVersionCommitPolicy(versionCommitPolicy: MapUpdater.MapUpdateVersionCommitPolicy)

    Parameters

    versionCommitPolicy