HERE iOS SDK Developer's Guide

NMAMapLoader

Class Summary

class NMAMapLoader

Derived from: NSObject

Provides various methods which facilitate usage of offline map data capabilities. Calls made to NMAMapLoader are asynchronous and return results through the NMAMapLoaderDelegate interface.

Include: NMAKit.framework/headers/NMAMapLoader.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMAMapLoader

[For complete information, see the section Class Details]

Public Property Summary

Table 1. Public Properties
Public Properties

[readable, assign] BOOL  active

Indicates whether or not the NMAMapLoader is currently performing an operation

[readable, writable, weak] id< NMAMapLoaderDelegate delegate

The current NMAMapLoaderDelegate for the NMAMapLoader

[readable, atomic, strong] NMAMapPackage rootPackage

The root item of the package hierarchy, representing the entire world map.

Instance Method Summary

Table 2. Instance Methods
Instance Method Summary

-(BOOL) cancelCurrentOperation

Request the currently running NMAMapLoader operation be cancelled

-(BOOL) checkForMapDataUpdate

Requests that a check be performed to see if an updated map data version is available

-(void) deselectDataGroup:( NMAMapDataGroup ) dataGroup

Deselects a map data group for installation

-(BOOL) getMapDataUpdateSize

Gets the size of a pending map data version update

-(BOOL) getMapPackageAtGeoCoordinates:(nonnull NMAGeoCoordinates *) coordinates

Try to find a NMAMapPackage which contains the given NMAGeoCoordinates

-(BOOL) getMapPackages

Requests the list of available NMAMapPackages

-(nonnull instancetype) init

NMAMapLoader is a singleton, use sharedMapLoader to obtain a shared instance

-(BOOL) installMapPackages:(nonnull NSArray< NMAMapPackage * > *) mapPackages

Requests that the specified NMAMapPackages be installed

-(BOOL) isDataGroupSelected:( NMAMapDataGroup ) dataGroup

Checks if a map data group is currently selected

-(BOOL) performMapDataUpdate

Requests that the map data version be updated if an update is available

-(void) selectDataGroup:( NMAMapDataGroup ) dataGroup

Selects a map data group for installation

-(BOOL) uninstallMapPackages:(nonnull NSArray< NMAMapPackage * > *) theMapPackages

Requests that the specified NMAMapPackages be uninstalled

Class Method Summary

Table 3. Class Methods
Class Methods

+(nonnull instancetype) new

+(nonnull NMAMapLoader *) sharedMapLoader

Returns the NMAMapLoader singleton instance

Class Details

Provides various methods which facilitate usage of offline map data capabilities. Calls made to NMAMapLoader are asynchronous and return results through the NMAMapLoaderDelegate interface.

Usage

The NMAMapLoader may only perform a single operation at a time. Therefore, if a method is called before the callback for a previous method call has been made, the call will fail and return NO.

Incremental Updates

All map data downloaded by the client application has a version. This includes data downloaded through the NMAMapLoader and data downloaded automatically as a result of map browsing. At any given time, all cached map data has the same version.

Periodically, new versions of the map database are released. To ensure that the client application is always using the freshest map data available, the map cache should be updated regularly. This is accomplished by first calling -checkForMapDataUpdate. If an update is available, it can be performed by calling -performMapDataUpdate.

When map data is updated, only the differences between the current version and the new version need to be downloaded. These "incremental updates" allow the map data to be kept up to date without having to delete and re-download the entire map cache every time. Thus, the size of a map data update is typically much smaller than the size of the cache itself.

Note:

NMAMapLoader is a singleton which must be obtained using the sharedMapLoader property.

Note:

NMAMapLoader requires valid authentication credentials to be set via NMAApplicationContext. If valid credentials are not present the API may not function correctly or may stop functioning correctly in the future when server side configurations change.

Public Property Details

[readable, assign] BOOL active

Indicates whether or not the NMAMapLoader is currently performing an operation.

Note:

The getMapPackageAtGeoCoordinates operation may be performed while other operations are in progress (including itself).

[readable, writable, weak] id< NMAMapLoaderDelegatedelegate

The current NMAMapLoaderDelegate for the NMAMapLoader. To remove the current delegate, set this property to nil.

[readable, atomic, strong] NMAMapPackagerootPackage

The root item of the package hierarchy, representing the entire world map.

The package hierarchy is accessed through the root package using its children property (and the children of the children, and so on).

When packages are installed or uninstalled, a new list is generated to reflect the updated state. Existing package lists are static and thus become obsolete when a new list is generated.

Note:

May be nil if the package list has not yet been retrieved or access to this operation is denied. To populate the list use the getMapPackages method. If this operation is denied, a warning message is issued through the console. In this case, contact your HERE representative for more information.

Instance Method Details

-(BOOL) cancelCurrentOperation

Request the currently running NMAMapLoader operation be cancelled. Cancellation is completed once the completion callback for the currently running operation has been made with the NMAMapLoaderResult::NMAMapLoaderResultOperationCancelled result.

Note:

When offline, the following operations can not be cancelled and NO is returned: Installing packages, uninstalling packages, getting map packages, updating map data and getting map data update size.

Returns:

YES if an operation was cancelled, NO if the map loader was not performing an operation or the operation could not be cancelled.

-(BOOL) checkForMapDataUpdate

Requests that a check be performed to see if an updated map data version is available. Please see the Incremental Updates section of the NMAMapLoader documentation for more info on map version updates.

Note:

The result is obtained through the NMAMapLoaderDelegate didFindUpdate:fromVersion:toVersion:withResult: callback.

Note:

If any NMAMapPackage has a state of NMAMapPackageInstallation::NMAMapPackageInstallationPartiallyInstalled, the callback will indicate that an update is available. In such case, calling performMapDataUpdate will fully install the partially installed packages.

Returns:

YES if the request has been made successfully, NO if the NMAMapLoader is currently busy processing another request.

-(void) deselectDataGroup:( NMAMapDataGroup ) dataGroup

Deselects a map data group for installation.

Note:

This method do nothing and warns through the console if access to this operation is denied. Contact your HERE representative for more information.

-(BOOL) getMapDataUpdateSize

Gets the size of a pending map data version update.

Note:

The result is obtained through the NMAMapLoaderDelegate mapLoader:didGetUpdateSize:withSuccess: callback.

Returns:

YES if the request has been made successfully, NO if the NMAMapLoader is currently busy processing another request.

-(BOOL) getMapPackageAtGeoCoordinates:(nonnull NMAGeoCoordinates *) coordinates

Try to find a NMAMapPackage which contains the given NMAGeoCoordinates.

This method will try to find a map package based on a map location ( NMAGeoCoordinates). If it can be identified, the smallest package containing the point is returned. For some input coordinates a larger package will be returned, but it should never be higher than country level (i.e. continental packages will not be returned).

The result of this operation is passed via the NMAMapLoaderDelegate -mapLoader:didGetMapPackage:atCoordinates:withResult.

Returns:

YES if the request has been made successfully, NO if the request was unsuccessful or if this operation was denied. If this operation is denied, a warning message is issued through the console. In this case, contact your HERE representative for more information.

-(BOOL) getMapPackages

Requests the list of available NMAMapPackage s. The list of available packages is returned in NMAMapLoaderDelegate via the mapLoader:didGetPackagesWithResult: callback.

Note:

NMAMapPackage s returned represent a snapshot of the current packages only; their state is not updated dynamically. Therefore, if any operation which modifies the state of an NMAMapPackage is performed (install/uninstall/update), packages will have to be retrieved again to reflect this state change.

Returns:

YES if the request has been made successfully, NO if the NMAMapLoader is currently busy processing another request or if this operation is denied. If this operation is denied, a warning message is issued through the console. In this case, contact your HERE representative for more information.

-(nonnull instancetype) init

NMAMapLoader is a singleton, use sharedMapLoader to obtain a shared instance.

-(BOOL) installMapPackages:(nonnull NSArray< NMAMapPackage * > *) mapPackages

Requests that the specified NMAMapPackage s be installed.

Note:

Status of the installation can be monitored through the NMAMapLoaderDelegate didUpdateProgress: and didInstallPackagesWithResult: callbacks.

Note:

If an already-installed package is selected again for installation, it will be skipped (and the NMAMapLoader will return immediately with success if it was the only package requested).

Parameters:

Returns:

YES if the request has been made successfully, NO if the NMAMapLoader is currently busy processing another request or if this operation is denied. If this operation is denied, a warning message is issued through the console. In this case, contact your HERE representative for more information.

-(BOOL) isDataGroupSelected:( NMAMapDataGroup ) dataGroup

Checks if a map data group is currently selected.

Returns:

YES if a map data group is currently selected, NO otherwise or if this operation was denied. If this operation is denied, a warning message is issued through the console. In this case, contact your HERE representative for more information.

-(BOOL) performMapDataUpdate

Requests that the map data version be updated if an update is available. Please see the Incremental Updates section of the NMAMapLoader documentation for more info on map version updates.

Note:

Status of the map update can be monitored through the NMAMapLoaderDelegate didUpdateProgress: and didUpdateWithResult: callbacks.

Note:

Performing a map data update will fully install any partially installed NMAMapPackage (i.e. NMAMapPackages with an NMAMapPackageInstallation state of NMAMapPackageInstallationPartiallyInstalled).

Returns:

YES if the request has been made successfully, NO if the NMAMapLoader is currently busy processing another request.

-(void) selectDataGroup:( NMAMapDataGroup ) dataGroup

Selects a map data group for installation.

Each map package is divided into several data groups. Some of these groups may be optionally selected for installation if needed by the application. Conversely, data groups which may be selected by default can be deselected by the application if not needed, saving disk space.

Note:

Changes to the data group selection are only reflected in subsequent installations. To add data groups to previously installed packages, call performMapDataUpdate after changing the group selection.

Note:

This method do nothing and warns through the console if access to this operation is denied. Contact your HERE representative for more information.

See also:

NMAMapDataGroup

-(BOOL) uninstallMapPackages:(nonnull NSArray< NMAMapPackage * > *) theMapPackages

Requests that the specified NMAMapPackage s be uninstalled.

Note:

Status of the uninstallation can be monitored through the NMAMapLoaderDelegate didUpdateProgress: and didUninstallPackagesWithResult: callbacks.

Parameters:

Returns:

YES if the request has been made successfully, NO if the NMAMapLoader is currently busy processing another request or if this operation is denied. If this operation is denied, a warning message is issued through the console. In this case, contact your HERE representative for more information.

Class Method Details

+(nonnull instancetype) new

Instances of this class should not be initialized directly

+(nonnull NMAMapLoader *) sharedMapLoader

Returns the NMAMapLoader singleton instance.

Note:

Use this method to obtain a NMAMapLoader instance. Do not call init directly.

Returns:

shared NMAMapLoader instance