1// Copyright (C) 2024 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
6\page position-plugin-android.html
7\title Qt Positioning Android plugin
8\ingroup QtPositioning-plugins
10\brief Wraps Android positioning subsystem.
14The Qt Positioning Android plugin wraps native Android APIs and provides
15access to positioning and satellite information.
17The plugin can be loaded by using the provider name \b android.
21The following table lists parameters that \e can be passed to the Android
30 \li The parameter is introduced in Qt 6.8. It determines if the plugin will
31 try to provide an altitude above Mean Sea Level (MSL). The default value
32 is \c false, which means that it provides the altitude in WGS84 format.
33 This parameter is only relevant for Android 14 and later. See
34 \l {Altitude Conversion} section for more details.
37\section2 Altitude conversion
39Android traditionally provides altitude above the World Geodetic System 1984
40(WGS84) reference ellipsoid. However, starting from Android 14, a new
41\l {https://developer.android.com/reference/android/location/altitude/AltitudeConverter}
42{AltitudeConverter} class was introduced. This class allows to convert the
43WGS84 altitude into \e {altitude above Mean Sea Level (MSL)} format.
45If the \c {useMslAltitude} plugin parameter is set to \c {true}, and the
46application is running on \b {Android 14} or later, the
47\l QGeoCoordinate::altitude component of \l QGeoPositionInfo objects retrieved
48during position updates will contain the MSL altitude.
50\note According to the Android
51\l {https://developer.android.com/reference/android/location/altitude/AltitudeConverter#addMslAltitudeToLocation(android.content.Context,%20android.location.Location)}
52{documentation}, the conversion to the MSL altitude \e may take several seconds.
53It means that \l {QGeoPositionInfoSource::}{lastKnownPosition()} requests \e may
54execute longer when this feature is enabled, because the method is synchronous.
55Other position update requests are not affected.
59The following examples show how to create an \b android \l PositionSource from
64The following snippet creates a \l PositionSource with no parameters. The
65altitude will be reported in WGS84 format.
73The next snippet explicitly adds the \c {useMslAltitude} \l PluginParameter
74and sets its value to \c true. This \l PositionSource will report the altitude
81 name: "useMslAltitude"
89The following snippet shows how to use C++ to create a
90\l {QGeoPositionInfoSource}{position source} which reports the altitude in MSL
95params["useMslAltitude"] = true;
96QGeoPositionInfoSource *positionSource = QGeoPositionInfoSource::createSource("android", params, this);