QtPositioning: extend Android docs

This patch extends the docs to mention some Android-specific topics

Task-number: QTBUG-71396
Pick-to: 6.2
Change-Id: I8f0757a896faeee279cfa0f16a940fe5e66df3a9
Reviewed-by: Assam Boudjelthia <assam.boudjelthia@qt.io>

6 files changed, 149 insertions, 2 deletions

diff --git a/src/positioning/doc/images/permissions.png b/src/positioning/doc/images/permissions.png
new file mode 100644
index 00000000..bd8c4850
--- /dev/null
+++ b/src/positioning/doc/images/permissions.png
diff --git a/src/positioning/doc/src/external-resources.qdoc b/src/positioning/doc/src/external-resources.qdoc
new file mode 100644
index 00000000..3c71d1f5
--- /dev/null
+++ b/src/positioning/doc/src/external-resources.qdoc
@@ -0,0 +1,46 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\externalpage https://developer.android.com/about/versions/oreo/background-location-limits
+\title Background Location Limits
+*/
+
+/*!
+\externalpage https://developer.android.com/guide/components/foreground-services
+\title Foreground Service
+*/
+
+/*!
+\externalpage https://developer.android.com/reference/android/Manifest.permission#ACCESS_BACKGROUND_LOCATION
+\title ACCESS_BACKGROUND_LOCATION
+*/
+
+/*!
+\externalpage https://developer.android.com/training/location/background
+\title Access Location in the Background
+*/
diff --git a/src/positioning/doc/src/qtpositioning-android.qdoc b/src/positioning/doc/src/qtpositioning-android.qdoc
new file mode 100644
index 00000000..1857574e
--- /dev/null
+++ b/src/positioning/doc/src/qtpositioning-android.qdoc
@@ -0,0 +1,82 @@
+/****************************************************************************
+**
+** Copyright (C) 2021 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\page qtpositioning-android.html
+\inmodule QtPositioning
+\title Qt Positioning on Android
+\brief Notes on using Qt Positioning on Android
+
+\section1 Using Qt Positioning from Android Services
+
+Using Qt Positioning from a service requires several extra actions to be taken,
+depending on the Android version. The sections below give more details on
+these actions.
+
+\note Since Android 8 (API level 26), the OS limits how frequently an
+application can retrieve the user's current location while running in the
+background. The application will normally be able to receive location updates
+only a few times each hour. For more information, see
+\l {Background Location Limits}.
+
+\section2 Using Foreground Service
+
+Since Android 8 (API level 26), the background service can be killed by the
+Android OS when the application goes to the background. This normally happens
+after around a minute of running in the background. To keep the location service
+running, the service should be implemented as a \l {Foreground Service}. Such
+service shows a status bar notification, which cannot be dismissed until the
+service is stopped or removed from the foreground. This allows the user to be
+always aware of the important background activities.
+
+\note Since Android 9 (API level 28), foreground services require a special
+\c FOREGROUND_SERVICE permission. See the Android documentation for more
+details on implementing foreground services.
+
+\section2 Use Background Location Permission
+
+Since Android 10 (API level 29), the service \e must request the
+\l {ACCESS_BACKGROUND_LOCATION} permission. It should be added to the
+\c AndroidManifest.xml file as follows:
+
+\badcode
+<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+\endcode
+
+\note Once the permission is added to \c {AndroidManifest.xml}, it is still
+required to explicitly allow the constant access to the location services
+for the application. To do it, one should navigate to \uicontrol Settings ->
+\uicontrol {Apps}, select a proper application, open its permissions, and
+specify the \uicontrol {Allow all the time} permission for Location
+(see the screenshot below).
+
+\image permissions.png
+
+Check \l {Access Location in the Background} Android documentation for more
+details.
+
+*/
diff --git a/src/positioning/doc/src/qtpositioning.qdoc b/src/positioning/doc/src/qtpositioning.qdoc
index a38a8392..daa7cb7f 100644
--- a/src/positioning/doc/src/qtpositioning.qdoc
+++ b/src/positioning/doc/src/qtpositioning.qdoc
@@ -133,6 +133,7 @@ See \l{Qt Licensing} for further details.
     \li \l {Positioning (QML)} {Positioning introduction for QML}
     \li \l {Qt Positioning Plugins}
     \li \l {Interfaces between C++ and QML Code in Qt Positioning}
+    \li \l {Qt Positioning on Android}
 \endlist
 
 \section1 Reference
diff --git a/src/positioning/qgeopositioninfosource.cpp b/src/positioning/qgeopositioninfosource.cpp
index 6f10de85..e09be54e 100644
--- a/src/positioning/qgeopositioninfosource.cpp
+++ b/src/positioning/qgeopositioninfosource.cpp
@@ -90,8 +90,11 @@ Q_GLOBAL_STATIC_WITH_ARGS(QFactoryLoader, loader,
     To remove an update interval that was previously set, call
     setUpdateInterval() with a value of 0.
 
-    Note that the position source may have a minimum value requirement for
+    \note The position source may have a minimum value requirement for
     update intervals, as returned by minimumUpdateInterval().
+
+    \note To use this class from Android service, see
+    \l {Qt Positioning on Android}.
 */
 
 /*!
@@ -523,6 +526,9 @@ QGeoPositionInfoSource::QGeoPositionInfoSource(QGeoPositionInfoSourcePrivate &dd
     \note Since Qt6 this method always resets the last error to
     \l {QGeoPositionInfoSource::}{NoError} before starting the updates.
 
+    \note To understand how to use this method from an Android service, see
+    \l {Qt Positioning on Android}.
+
     On iOS, starting from version 8, Core Location framework requires additional
     entries in the application's Info.plist with keys NSLocationAlwaysUsageDescription or
     NSLocationWhenInUseUsageDescription and a string to be displayed in the authorization prompt.
@@ -563,6 +569,9 @@ QGeoPositionInfoSource::QGeoPositionInfoSource(QGeoPositionInfoSourcePrivate &dd
     \note Since Qt6 this method always resets the last error to
     \l {QGeoPositionInfoSource::}{NoError} before requesting
     the position.
+
+    \note To understand how to use this method from an Android service, see
+    \l {Qt Positioning on Android}.
 */
 
 /*!
diff --git a/src/positioning/qgeosatelliteinfosource.cpp b/src/positioning/qgeosatelliteinfosource.cpp
index 2099dd9f..b109e839 100644
--- a/src/positioning/qgeosatelliteinfosource.cpp
+++ b/src/positioning/qgeosatelliteinfosource.cpp
@@ -81,8 +81,11 @@ QT_BEGIN_NAMESPACE
     To remove an update interval that was previously set, call
     setUpdateInterval() with a value of 0.
 
-    Note that the satellite source may have a minimum value requirement for
+    \note The satellite source may have a minimum value requirement for
     update intervals, as returned by minimumUpdateInterval().
+
+    \note To use this class from Android service, see
+    \l {Qt Positioning on Android}.
 */
 
 /*!
@@ -347,6 +350,9 @@ QStringList QGeoSatelliteInfoSource::availableSources()
     \l {QGeoSatelliteInfoSource::}{NoError} before starting
     the updates.
 
+    \note To understand how to use this method from an Android service, see
+    \l {Qt Positioning on Android}.
+
     \sa satellitesInViewUpdated(), satellitesInUseUpdated()
 */
 
@@ -377,6 +383,9 @@ QStringList QGeoSatelliteInfoSource::availableSources()
     \note Since Qt6 this method always resets the last error to
     \l {QGeoSatelliteInfoSource::}{NoError} before requesting
     the satellite information.
+
+    \note To understand how to use this method from an Android service, see
+    \l {Qt Positioning on Android}.
 */
 
 /*!