HERE iOS SDK Developer's Guide

NMAPositioningManager

Class Summary

class NMAPositioningManager

Derived from: NSObject

Manages positioning services for the NMA SDK.

Include: NMAKit.framework/headers/NMAPositioningManager.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMAPositioningManager

[For complete information, see the section Class Details]

Public Property Summary

Table 1. Public Properties
Public Properties

[readable, assign] BOOL  active

Indicates whether the NMAPositioningManager is currently broadcasting position updates

[readable, assign] NMAGeoPosition currentPosition

The best estimate for the user's current position.

[readable, writable, assign] id< NMAPositionDataSource dataSource

The current provider of raw position data for the positioning manager.

[readable, writable, assign] NMAPositionLogType   logType

Configures position update logging

[readable, writable, assign] NMAMapMatchMode   mapMatchMode

The mode in which raw position data is matched to the road network.

[readable, assign] NMAGeoPosition mapMatchedPosition

The best esimated position on the road network based on the current rawPosition.

[readable, writable, assign] BOOL  mapMatchingEnabled

Controls whether or not map matching is performed

[readable, assign] NMAGeoPosition rawPosition

The latest unprocessed position received from the current dataSource

Instance Method Summary

Table 2. Instance Methods
Instance Method Summary

-(nullable NMARoadElement *) currentRoadElement

Get the road element of the current position

-(void) dataSourceDidUpdatePosition:(nonnull id< NMAPositionDataSource >) dataSource

Used by the dataSource to indicate that a new position update is available.

-(nonnull instancetype) init

-(BOOL) startPositioning

Enables position broadcasting.

-(void) stopPositioning

Disables position broadcasting.

Class Method Summary

Table 3. Class Methods
Class Methods

+(nonnull instancetype) new

+(nonnull NMAPositioningManager *) sharedPositioningManager

Returns the NMAPositioningManager singleton instance

Class Details

Manages positioning services for the NMA SDK.

This is a singleton class and thus should never be retained, released, or instantiated. The singleton instance is accessed via the sharedPositioningManager method.

Use the startPositioning method to begin tracking position, and stopPositioning to stop. By default, position data comes from an instance of NMADevicePositionSource, which uses CLLocationManager to determine position. Any custom source of position data can be used instead by subclassing NMAPositionDataSource and installing an instance of the subclass in the NMAPositioningManager dataSource property.

Two types of position are available from the positioning manager: the raw position and the map-matched position. The raw position is simply passed straight through from the positioning manager's data source. The map-matched position is the estimated position on the road network based on the raw position input. When either type of position changes, a NMAPositioningManagerDidUpdatePositionNotification will be sent out. If the raw position is lost, a NMAPositioningManagerDidLosePositionNotification is sent.

Note:

Certain other SDK features may require the use of the positioning manager; if these features are accessed, the positioning manager will be enabled automatically (for example, the NMAPositionIndicator of a NMAMapView).

Note:

NMAPositioningManager 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 the NMAPositioningManager is currently broadcasting position updates.

[readable, assign] NMAGeoPositioncurrentPosition

The best estimate for the user's current position.

The currentPosition will be equal to either the rawPosition or the mapMatchedPosition, depending on availability, SDK usage, and circumstances.

If SDK services such as navigation which require the use of map matching are active, the currentPosition will typically be the map-matched position.

Note:

Will be nil if the positioning manager is not active or does not have a valid position.

[readable, writable, assign] id< NMAPositionDataSourcedataSource

The current provider of raw position data for the positioning manager.

If positioning is started with a nil dataSource, a default instance of NMADevicePositionSource is created and installed. This instance can then be accessed and configured using the dataSource property. Similarly, if the dataSource is set to nil while positioning is active, a default position source is installed.

Note:

It is NOT recommended to change data source whilst the app is backgrounded as some attributes of the data source (such as enabling background updates) may not be reliably configurable in the background.

[readable, writable, assign] NMAPositionLogType  logType

Configures position update logging.

NMAPositionLogTypeDataSource will log "input positions" from the current NMAPositionDataSource to a file ending with the suffix "_ios_source". This GPX file is suitable for playback via NMALoggedPositionSource. In addition, if the current NMAPositionDataSource supports source specific logging then an additional GPX log will be written. For example, NMADevicePositionSource will log detailed CLLocationManager state information to a file ending with the suffix "_ios_cl".

NMAPositionLogTypeCurrent, NMAPositionLogTypeRaw, and NMAPositionLogTypeMatched will log the results of processing the input position from the data source. The content of these logs represents the historical values of the rawPosition, mapMatchedPosition, and currentPosition properties. GPX logs produced for these logging types are for analysis only and are not suitable for playback via NMALoggedPositionSource.

GPX logs will be written to the Documents directory of the application. Logs will be prefixed with a timestamp representing the time logging was enabled and suffix indicating the log type (see NMAPositionLogType).

To ensure log files are flushed to disk make sure logging is disabled prior to application exit.

Defaults to NMAPositionLogTypeNone (no logging).

Note:

IMPORTANT: Logging should NOT be permanently enabled in production builds submitted to the App Store.

[readable, writable, assign] NMAMapMatchMode  mapMatchMode

The mode in which raw position data is matched to the road network.

If the mode is NMAMapMatchModeCar, the raw position data will only be matched to roads which are accessible by a car. If the mode is NMAMapMatchModePedestrian, the data will only be matched to roads or paths which are accessible on foot.

Note:

Attempts to set NMAMapMatchModePedestrian will be ignored when the position data source is derived from NMAPositionDataSourceAutomotive as this position source type does not support pedestrian map matching.

See also:

NMAMapMatchMode

[readable, assign] NMAGeoPositionmapMatchedPosition

The best esimated position on the road network based on the current rawPosition.

When a new raw position is received and map matching is enabled, the position is processed to estimate where on the road network the user is likely to be. If the user is in a car on a known road, this position is likely to be more accurate than the raw position. Map matching can be disabled by setting the mapMatchingEnabled property to NO.

Note:

Will be nil if map matching could not be performed, or if mapMatchingEnabled is set to NO.

[readable, writable, assign] BOOL mapMatchingEnabled

Controls whether or not map matching is performed.

The Map Matching is not enabled if access to this operation is denied. Contact your HERE representative for more information.

Note:

The default value is NO.

[readable, assign] NMAGeoPositionrawPosition

The latest unprocessed position received from the current dataSource.

Note:

Will be nil if the latest update from the current dataSource did not return a valid position.

Instance Method Details

-(nullable NMARoadElement *) currentRoadElement

Get the road element of the current position. Nil if not valid.

Returns:

Road element of the current position.

-(void) dataSourceDidUpdatePosition:(nonnull id< NMAPositionDataSource >) dataSource

Used by the dataSource to indicate that a new position update is available.

When the current dataSource has a new position update ready, it calls this method passing itself as the parameter. Only one position source may be active at a time, so the parameter should match the current dataSource. Objects other than the current dataSource should not call this method.

-(nonnull instancetype) init

Instances of this class should not be initialized directly

-(BOOL) startPositioning

Enables position broadcasting.

When positioning is started, the current dataSource will receive a start callback. If no dataSource is set, a default instance of NMADevicePositionSource is created and installed as the source.

Returns:

YES if positioning was successfully started, NO if positioning was already in progress or if positioning failed to start.

See also:

NMAPositionDataSource

-(void) stopPositioning

Disables position broadcasting.

When positioning is stopped, the current dataSource will receive a stop callback.

See also:

NMAPositionDataSource

Class Method Details

+(nonnull instancetype) new

Instances of this class should not be initialized directly

+(nonnull NMAPositioningManager *) sharedPositioningManager

Returns the NMAPositioningManager singleton instance.

Note:

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

Returns:

shared NMAPositioningManager instance