Method Details

• start

  @NonNull public LocationEngineStatus start(@NonNull LocationAccuracy locationAccuracy)

  Starts the location engine with desired LocationAccuracy. Make sure to call either confirmHEREPrivacyNoticeInclusion() or confirmHEREPrivacyNoticeException() beforehand.

  Specified by:

  start in interface LocationEngineBase

  Parameters:

  locationAccuracy - Desired location accuracy

  Returns:

  the status of the LocationEngine

  Throws:

  IllegalArgumentException - if the argument is null

• start

  @NonNull public LocationEngineStatus start(@NonNull LocationOptions locationOptions)

  Starts the location engine with desired LocationOptions. Make sure to call either confirmHEREPrivacyNoticeInclusion() or confirmHEREPrivacyNoticeException() beforehand.

  Specified by:

  start in interface LocationEngineBase

  Parameters:

  locationOptions - Desired location options.

  Returns:

  the status of the LocationEngine

  Throws:

  IllegalArgumentException - if the argument is null

• updateLocationAccuracy

  @NonNull public LocationEngineStatus updateLocationAccuracy(@NonNull LocationAccuracy locationAccuracy)

  Reconfigures the location engine with desired LocationAccuracy. This method is a faster way to change location accuracy for already started location engine, than calling LocationEngineBase.stop() and LocationEngineBase.start(LocationOptions) in sequence. Returns LocationEngineStatus.NOT_READY, if called for unstarted location engine.

  Specified by:

  updateLocationAccuracy in interface LocationEngineBase

  Parameters:

  locationAccuracy -

  Desired location accuracy. Requested accuracy is not guaranteed.

  Returns:

  Engine status. Valid values are defined in LocationEngineStatus

  Throws:

  IllegalArgumentException - if the argument is null

• updateLocationOptions

  @NonNull public LocationEngineStatus updateLocationOptions(@NonNull LocationOptions locationOptions)

  Reconfigures the location engine with desired LocationOptions. This method is a faster way to change location options for already started location engine, than calling LocationEngineBase.stop() and LocationEngineBase.start(LocationOptions) in sequence. Returns LocationEngineStatus.NOT_READY, if called for unstarted location engine.

  Specified by:

  updateLocationOptions in interface LocationEngineBase

  Parameters:

  locationOptions -

  Desired location options.

  Returns:

  Engine status. Valid values are defined in LocationEngineStatus

  Throws:

  IllegalArgumentException - if the argument is null

• stop

  public void stop()

  Stops the location engine.

  Specified by:

  stop in interface LocationEngineBase

• isStarted

  public boolean isStarted()

  Checks if the engine is in started state.

  Specified by:

  isStarted in interface LocationEngineBase

  Returns:

  true if started, false otherwise

• confirmHEREPrivacyNoticeInclusion

  @NonNull public ConfirmationStatus confirmHEREPrivacyNoticeInclusion()

  It is the responsibility of the application developer to ensure that the application user is informed about the collection of characteristic information regarding nearby mobile and Wi-Fi network signals. Additionally, a link to the related HERE Privacy Notice must be made available to the user.

  This information can be included in the application's Terms & Conditions, Privacy Policy, or otherwise made accessible to the user.

  An example text for informing users about the data collection: "This application uses location services provided by HERE Technologies. To maintain, improve, and provide these services, HERE Technologies occasionally collects characteristic information about nearby mobile and Wi-Fi network signals. For more information, please refer to the HERE Privacy Notice at: https://legal.here.com/here-network-positioning-via-sdk"

  By calling this method, the application developer confirms that this information is made available to the end user. For example, it is sufficient to inform users once that using the app requires acceptance of its terms (if any). Then, in the terms include the above mentioned data collection information and a link to the related HERE Privacy Notice. The user is not required to open the terms to acknowledge the data collection details. The "Positioning" example app on GitHub provides an example of this. When the above criteria are met, it is recommended to silently execute this method each time before starting the LocationEngine, as failure to do so will result in the engine being non-functional.

  Specified by:

  confirmHEREPrivacyNoticeInclusion in interface LocationEngineBase

  Returns:

  Immediately returns with ConfirmationStatus.OK.

• confirmHEREPrivacyNoticeException

  @NonNull public ConfirmationStatus confirmHEREPrivacyNoticeException()

  By calling this method, the application developer confirms that they have received an exceptional permission from HERE in written form to **not** include a reference to the HERE Privacy Notice. As a result, the LocationEngine will not collect characteristic information about the nearby mobile and Wi-Fi network signals. However, the engine will still be fully functional and it will deliver location updates when the exception can be confirmed.

  Note that this call should not involve user interaction and it should be executed silently by the application before starting the LocationEngine.

  The permission for exceptional use will be verified asynchronously using your HERE SDK credentials. A missing permission will lead to stopping of the LocationEngine and LocationEngineStatus.PRIVACY_NOTICE_UNCONFIRMED is delivered to LocationStatusListener.

  Specified by:

  confirmHEREPrivacyNoticeException in interface LocationEngineBase

  Returns:

  Confirmation action status. Valid values are defined in ConfirmationStatus. A first-time call may result in ConfirmationStatus.PENDING, make sure to use the LocationStatusListener to get notified on an unconfirmed permission.

• enableVehicleSensors

  public void enableVehicleSensors(@NonNull androidx.car.app.hardware.CarHardwareManager manager)

  This feature enables the utilization of the vehicle's GNSS and movement sensor information. It is recommended to always enable this feature by default when the application supports Android Auto. This allows the phone's positioning sensor information to be augmented with the vehicle's sensor data, resulting in the best possible positioning estimates. However, given the varying quality of car sensor implementations, it is also advisable to provide application users with the option to disable the usage of vehicle sensor information - this would be helpful in case the vehicle reports information that is clearly misleading or contradictory. Furthermore, users should be able to re-enable this feature if the vehicle's capability improves.

  Specified by:

  enableVehicleSensors in interface LocationEngineBase

  Parameters:

  manager - Android Auto car hardware manager.

• disableVehicleSensors

  public void disableVehicleSensors()

  Disables access to vehicle's sensor information.

  Specified by:

  disableVehicleSensors in interface LocationEngineBase

• getLastKnownLocation

  @Nullable public Location getLastKnownLocation()

  Gets the last known location obtained by the engine.

  Specified by:

  getLastKnownLocation in interface LocationEngineBase

  Returns:

  last known Location if available, null if never obtained.

• addLocationListener

  public void addLocationListener(@NonNull LocationListener listener)

  Adds a LocationListener to the engine to get notified when there is a new Location.

  Specified by:

  addLocationListener in interface LocationEngineBase

  Parameters:

  listener - The listener to be added

  Throws:

  IllegalArgumentException - if the listener is null

• removeLocationListener

  public void removeLocationListener(@NonNull LocationListener listener)

  Removes a LocationListener from the engine

  Specified by:

  removeLocationListener in interface LocationEngineBase

  Parameters:

  listener - The listener to be removed

  Throws:

  IllegalArgumentException - if the listener is null

• addLocationStatusListener

  public void addLocationStatusListener(@NonNull LocationStatusListener listener)

  Adds a LocationStatusListener to the engine to get notified when there is an important status change.

  Specified by:

  addLocationStatusListener in interface LocationEngineBase

  Parameters:

  listener - The listener to be added

  Throws:

  IllegalArgumentException - if the listener is null

• removeLocationStatusListener

  public void removeLocationStatusListener(@NonNull LocationStatusListener listener)

  Removes a LocationStatusListener from the engine

  Specified by:

  removeLocationStatusListener in interface LocationEngineBase

  Parameters:

  listener - The listener to be removed

  Throws:

  IllegalArgumentException - if the listener is null

• addLocationIssueListener

  public void addLocationIssueListener(@NonNull LocationIssueListener listener)

  Adds a LocationIssueListener to the engine to get notified when a location issue has occurred

  Specified by:

  addLocationIssueListener in interface LocationEngineBase

  Parameters:

  listener - The listener to be added

  Throws:

  IllegalArgumentException - if the listener is null

• removeLocationIssueListener

  public void removeLocationIssueListener(@NonNull LocationIssueListener listener)

  Removes a LocationIssueListener from the engine

  Specified by:

  removeLocationIssueListener in interface LocationEngineBase

  Parameters:

  listener - The listener to be removed

  Throws:

  IllegalArgumentException - if the listener is null

• setLastKnownLocationPersistent

  public LocationEngineStatus setLastKnownLocationPersistent(boolean persistent)

  Enables or disables saving of last known location so it persists between application sessions. Defaults to enabled.

  Specified by:

  setLastKnownLocationPersistent in interface LocationEngineBase

  Parameters:

  persistent - If true enables last known location to be saved persistently, or if false disables it.

  Returns:

  LocationEngineStatus.OK always.