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

-(instancetype) NS_UNAVAILABLE

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

-(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:( NMAGeoCoordinates *) coordinates

Try to find a NMAMapPackage which contains the given NMAGeoCoordinates

-(BOOL) getMapPackages

Requests the list of available NMAMapPackages

-(BOOL) installMapPackages:(NSArray *) 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:(NSArray *) theMapPackages

Requests that the specified NMAMapPackages be uninstalled

Class Method Summary

Table 3. Class Methods
Class Methods

+( 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 method.

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

-(instancetype) NS_UNAVAILABLE

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

-(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:( 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.

-(BOOL) installMapPackages:(NSArray *) 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:(NSArray *) 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

+( 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

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.