From 7253f6cac009a724edc1bfa22ed2109d2d44538b Mon Sep 17 00:00:00 2001 From: Nicholas Bennett Date: Wed, 5 Oct 2022 15:51:25 +0300 Subject: [PATCH] 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 (cherry picked from commit a0ca5f433fdc45e97e461ece2d9839eebd3c7ea0) Reviewed-by: Volker Hilsheimer --- src/corelib/doc/src/external-resources.qdoc | 30 +++++++++++++++++++ .../android-content-uri-limitations.qdocinc | 13 ++++++++ src/corelib/io/qdir.cpp | 7 +++++ src/corelib/io/qfile.cpp | 5 ++++ src/corelib/io/qfileinfo.cpp | 4 +++ 5 files changed, 59 insertions(+) create mode 100644 src/corelib/doc/src/includes/android-content-uri-limitations.qdocinc diff --git a/src/corelib/doc/src/external-resources.qdoc b/src/corelib/doc/src/external-resources.qdoc index 7e8977dbd98..3210d92cc74 100644 --- a/src/corelib/doc/src/external-resources.qdoc +++ b/src/corelib/doc/src/external-resources.qdoc @@ -82,6 +82,36 @@ \title Android: Keeping your app responsive */ +/*! + \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 +*/ + /*! \externalpage https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html \title GNUInstallDirs 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 00000000000..f08086407ee --- /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 42130be37e2..bb0633864bb 100644 --- a/src/corelib/io/qdir.cpp +++ b/src/corelib/io/qdir.cpp @@ -507,6 +507,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} */ @@ -990,6 +994,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 b1115ad15c0..997a5f8bd53 100644 --- a/src/corelib/io/qfile.cpp +++ b/src/corelib/io/qfile.cpp @@ -192,6 +192,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} */ @@ -857,6 +859,9 @@ QFile::copy(const QString &fileName, const QString &newName) will try to create a new file before opening it. The file will be created with mode 0666 masked by the umask on POSIX systems, and with permissions inherited from the parent directory on Windows. + 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 17f717c3437..d4439fa8f93 100644 --- a/src/corelib/io/qfileinfo.cpp +++ b/src/corelib/io/qfileinfo.cpp @@ -290,6 +290,10 @@ QDateTime &QFileInfoPrivate::getFileTime(QAbstractFileEngine::FileTime request) If you want to make sure that all information is read from the file system, use stat(). + \section1 Platform Specific Issues + + \include android-content-uri-limitations.qdocinc + \sa QDir, QFile */