Docs:Android: Add docs notes about support for content Uris

Add some details about the support of Qt apis (QFile, QDir, QFileInfo)
for Android content uris.

Fixes: QTBUG-99664
Task-number: QTBUG-98974
Change-Id: I4b884623702ccad116d47049e34ccddfe21f83ca
Reviewed-by: Nicholas Bennett <nicholas.bennett@qt.io>
(cherry picked from commit a0ca5f433fdc45e97e461ece2d9839eebd3c7ea0)

5 files changed, 59 insertions, 0 deletions

diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc
index f16a21d521..0096bca948 100644
--- a/src/corelib/doc/src/external-resources.qdoc
+++ b/src/corelib/doc/src/external-resources.qdoc
@@ -65,3 +65,33 @@
     \externalpage http://marcmutz.wordpress.com/effective-qt/containers/
     \title Understand the Qt Containers
 */
+
+/*!
+    \externalpage https://developer.android.com/training/data-storage/shared/documents-files
+    \title Android: Access documents and other files from shared storage
+*/
+
+/*!
+    \externalpage https://developer.android.com/reference/androidx/documentfile/provider/DocumentFile#getParentFile()
+    \title Android: DocumentFile.getParentFile()
+*/
+
+/*!
+    \externalpage https://developer.android.com/guide/topics/providers/content-provider-basics#ContentURIs
+    \title Android: Content URIs
+*/
+
+/*!
+    \externalpage https://developer.android.com/training/data-storage#scoped-storage
+    \title Android: Scoped storage
+*/
+
+/*!
+    \externalpage https://developer.android.com/training/data-storage/use-cases
+    \title Android: storage best practices
+*/
+
+/*!
+    \externalpage https://developer.android.com/reference/android/provider/MediaStore
+    \title Android: MediaStore
+*/
diff --git a/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc
new file mode 100644
index 0000000000..f08086407e
--- /dev/null
+++ b/src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc
@@ -0,0 +1,13 @@
+On Android, some limitations apply when dealing with
+\l {Android: Content URIs}{content URIs}:
+\list
+    \li Access permissions might be needed by prompting the user through the
+        \l QFileDialog which implements
+        \l {Access documents and other files from shared storage}{Android's native file picker}.
+        \li Aim to follow the \l {Android: Scoped storage}{Scoped storage} guidelines,
+            such as using app specific directories instead of other public external directories.
+            For more information, also see
+            \l {Android: storage best practices}{storage best practices}.
+        \li Due to the design of Qt APIs (e.g. QFile), it's not possible to fully
+            integrate the latter APIs with Android's \l {Android: MediaStore}{MediaStore} APIs.
+\endlist
diff --git a/src/corelib/io/qdir.cpp b/src/corelib/io/qdir.cpp
index 6e0e133cc8..00d189b618 100644
--- a/src/corelib/io/qdir.cpp
+++ b/src/corelib/io/qdir.cpp
@@ -554,6 +554,10 @@ inline void QDirPrivate::initFileEngine()
 
     \snippet qdir-listfiles/main.cpp 0
 
+    \section1 Platform Specific Issues
+
+    \include android-content-uri-limitations.qdocinc
+
     \sa QFileInfo, QFile, QFileDialog, QCoreApplication::applicationDirPath(), {Find Files Example}
 */
 
@@ -1039,6 +1043,9 @@ bool QDir::cd(const QString &dirName)
     otherwise returns \c false. Note that the logical cdUp() operation is
     not performed if the new directory does not exist.
 
+    \note On Android, this is not supported for content URIs. For more information,
+    see \l {Android: DocumentFile.getParentFile()}{DocumentFile.getParentFile()}.
+
     \sa cd(), isReadable(), exists(), path()
 */
 bool QDir::cdUp()
diff --git a/src/corelib/io/qfile.cpp b/src/corelib/io/qfile.cpp
index 5da126470c..59212e22cb 100644
--- a/src/corelib/io/qfile.cpp
+++ b/src/corelib/io/qfile.cpp
@@ -229,6 +229,8 @@ QAbstractFileEngine *QFilePrivate::engine() const
     function mostly useless for NTFS volumes. It may still be of use for USB
     sticks that use VFAT file systems. POSIX ACLs are not manipulated, either.
 
+    \include android-content-uri-limitations.qdocinc
+
     \sa QTextStream, QDataStream, QFileInfo, QDir, {The Qt Resource System}
 */
 
@@ -961,6 +963,9 @@ QFile::copy(const QString &fileName, const QString &newName)
     \note In \l{QIODevice::}{WriteOnly} or \l{QIODevice::}{ReadWrite}
     mode, if the relevant file does not already exist, this function
     will try to create a new file before opening it.
+    On Android, it's expected to have access permission to the parent
+    of the file name, otherwise, it won't be possible to create this
+    non-existing file.
 
     \sa QIODevice::OpenMode, setFileName()
 */
diff --git a/src/corelib/io/qfileinfo.cpp b/src/corelib/io/qfileinfo.cpp
index 339341a077..d7802dac70 100644
--- a/src/corelib/io/qfileinfo.cpp
+++ b/src/corelib/io/qfileinfo.cpp
@@ -317,6 +317,10 @@ QDateTime &QFileInfoPrivate::getFileTime(QAbstractFileEngine::FileTime request)
     off a QFileInfo's caching and force it to access the file system
     every time you request information from it call setCaching(false).
 
+    \section1 Platform Specific Issues
+
+    \include android-content-uri-limitations.qdocinc
+
     \sa QDir, QFile
 */